home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / rcs567x.zip / doc / cio.man < prev    next >
Text File  |  1994-03-23  |  14KB  |  397 lines
  1.  
  2.  
  3.  
  4. CIO(1)                                                     CIO(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        cio - a pair of RCS user interface programs
  9.  
  10. SSYYNNOOPPSSIISS
  11.        cii [cii options] [ci options] [filename ...] [dirname ...
  12.        ]
  13.  
  14.        coo [coo options] [co options] [filename ...] [dirname ...
  15.        ]
  16.  
  17. DDEESSCCRRIIPPTTIIOONN
  18.        _C_i_i  and  _c_o_o are two programs that will provide an inter-
  19.        face to the RCS programs _c_i and _c_o_.  They add:
  20.  
  21.        Recursively check in/out directory structures
  22.  
  23.        Store RCS files in a separate directory structure
  24.  
  25.        Default stores only ASCII files, enabling  program  to  be
  26.        run on directories with both source and binary
  27.  
  28.  
  29.        Command line options include:
  30.  
  31.        --AA   All  files.   Forces  a  "cp"  of files that are non-
  32.             ASCII.
  33.  
  34.        --HH   Insert RCS header.  If a valid RCS header not  found,
  35.             a  template  header will be inserted at the beginning
  36.             of the file being checked in.
  37.  
  38.        --NN   No operation.  Causes  _c_i_i  or  _c_o_o  to  display  the
  39.             action that would have resulted. Nothing is executed.
  40.  
  41.        --RR   Recursively walk down directories to check in/out
  42.  
  43.        --TT   Force title request at start of program (Default only
  44.             gets title when required.)
  45.  
  46.        --UU   Update  source  directory.  During a check-in, a copy
  47.             is made  to  the  directory  structure  specified  by
  48.             $RCSSRC.   If  $RCSSRC  is not defined, $HOME will be
  49.             used instead.
  50.  
  51.        --VV   Verbose.  Be real  talkative  about  the  work  being
  52.             done.
  53.  
  54.        [[aallll ccii//ccoo ooppttiioonnss]]
  55.             Passes all other options  on to _c_i or _c_o_.
  56.  
  57.        ffiilleennaammee
  58.             Optional  file  names.  If not provided, the _c_i_i pro-
  59.             gram will take all files in the current directory, or
  60.             _c_o_o  will  take all files saved in the RCS directory.
  61.  
  62.  
  63.  
  64.                                                                 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CIO(1)                                                     CIO(1)
  71.  
  72.  
  73.             (Binary files only if -A was also specified.)
  74.  
  75.        ddiirrnnaammee
  76.             Both programs will take a directory name as an  argu-
  77.             ment,  however:  the -R option must also be specified
  78.             for it to work.
  79.  
  80.  
  81.  
  82.  
  83.  
  84. EENNVVIIRROONNMMEENNTT
  85.        RRCCSSDDIIRR
  86.             If defined, names a path that will be used  to  store
  87.             the  RCS  files. Default is $HOME/RCS.  Final path is
  88.             computed by removing $HOME and/or $RCSWORK from  cur-
  89.             rent path.
  90.  
  91.  
  92.        RRCCSSWWOORRKK
  93.             If  defined,  an alternate prefix for current working
  94.             directory.  Allows having multiple  directory  struc-
  95.             tures with different prefix's.
  96.  
  97.  
  98.        HHOOMMEE Must be defined as the users home directory.
  99.  
  100.  
  101.        RRCCSSSSRRCC
  102.             If  defined  and  -U  flag is specified, during a _c_i_i
  103.             procedure, a copy of what's being checked in will  be
  104.             made  in the directory structure starting at $RCSSRC.
  105.             If not specified, _c_i_i uses $HOME instead.
  106.  
  107.  
  108.        RRCCSSHHEEAADD
  109.             If -H flag is specified, _c_i_i  finds  template  header
  110.             from $RCSHEAD directory.
  111.  
  112.  
  113. SSAAMMPPLLEESS
  114.        A  user with a home directory of /usr/bog, has a directory
  115.        structure called sample/arix.  He want's to store  all  of
  116.        the files in /usr/bog/sample/arix into the RCS system.  If
  117.        neither  RCSDIR  or  RCSWORK  is  defined,  the  RCS  path
  118.        defaults  to his home directory, followed by RCS, followed
  119.        by the current path.  So:
  120.  
  121.                Current directory   :  /usr/bog/sample/arix
  122.                Home directory      :  /usr/bog
  123.                RCSDIR              :
  124.                RCSWORK             :
  125.                RCSSRC              :
  126.  
  127.  
  128.  
  129.  
  130.                                                                 2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CIO(1)                                                     CIO(1)
  137.  
  138.  
  139.                Final RCS storage   :  /usr/bog/RCS/sample/arix
  140.                Final source storage:  /usr/bog/sample/arix
  141.  
  142.        The net effect of this command is to create the RCS direc-
  143.        tory,  then  to  duplicate  the  directory  structure in a
  144.        defined place.  In this case, since  the  RCSDIR  was  not
  145.        defined, it defaulted to the users home directory.
  146.  
  147.        It  is  not necessary to build the directories in RCS, the
  148.        program will build all  necessary  directories  (Including
  149.        the RCS dir, if needed).
  150.  
  151.        Another example:  All RCS files should reside in /usr/RCS,
  152.        so the above example turns into:
  153.  
  154.                Current directory   :  /usr/bog/sample/arix
  155.                Home directory      :  /usr/bog
  156.                RCSDIR              :  /usr/RCS
  157.                RCSWORK             :
  158.                RCSSRC              :
  159.  
  160.                Final RCS storage   :  /usr/RCS/sample/arix
  161.                Final source storage:  /usr/bog/sample/arix
  162.  
  163.        Here is an example showing use of  the  RCSWORK  variable.
  164.        Some  systems  may  have  more  than one person working on
  165.        file.  In this case, the path names will have to be  simi-
  166.        lar, but only to a point.  Example, /usr/tog is also work-
  167.        ing in a directory, called sample/arix.  His system  would
  168.        look like:
  169.  
  170.                Current directory   :  /usr/tog/sample/arix
  171.                Home directory      :  /usr/tog
  172.                RCSDIR              :  /usr/RCS
  173.                RCSWORK             :
  174.                RCSSRC              :
  175.  
  176.                Final RCS storage   :  /usr/RCS/sample/arix
  177.                Final source storage:  /usr/tog/sample/arix
  178.  
  179.        Note  that  the  RCS  dir is the same for him.  Now, let's
  180.        take a user who has decided to work somewhere  other  than
  181.        his home directory.
  182.  
  183.                Current directory   :  /usr/src/rog/sample/arix
  184.                Home directory      :  /usr/rog
  185.                RCSDIR              :  /usr/RCS
  186.                RCSWORK             :  /usr/src/rog
  187.                RCSSRC              :
  188.  
  189.                Final RCS storage   :  /usr/RCS/sample/arix
  190.                Final source storage:  /usr/rog/sample/arix
  191.  
  192.        If  RCSSRC  is  specified to keep the current source (very
  193.  
  194.  
  195.  
  196.                                                                 3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CIO(1)                                                     CIO(1)
  203.  
  204.  
  205.        useful to when one wants to  browse  through  the  current
  206.        source files) in a directory other than his HOME.
  207.  
  208.                Current directory   :  /usr/src/rog/sample/arix
  209.                Home directory      :  /usr/rog
  210.                RCSDIR              :  /usr/RCS
  211.                RCSWORK             :  /usr/src/rog
  212.                RCSSRC              :  /usr/group
  213.  
  214.                Final RCS storage   :  /usr/RCS/sample/arix
  215.                Final source storage:  /usr/group/sample/arix
  216.  
  217.        The  RCSWORK  variable  was removed from the current path,
  218.        before the directory structure was defined.  Thus,  it  is
  219.        possible  to be working in just about anywhere on the sys-
  220.        tem and still use the same  directory  structure  and  RCS
  221.        files.
  222.  
  223.  
  224.        If you want to recover a directory (or multiple ones) into
  225.        a new working directory, simply create  whatever  part  of
  226.        the  path  you  need,  set  the RCSWORK variable to be the
  227.        first part of the path, and type "coo [-R]".
  228.  
  229.        Example:  A new user (/usr/log) has decided to examine the
  230.        sample/* files.  Here are the steps:
  231.  
  232.              Current working directory: /usr/llog
  233.              mkdir sample
  234.              chdir sample
  235.              RCSDIR=/usr/RCS  export RCSDIR
  236.              RCSWORK=/usr/log  export RCSWORK
  237.  
  238.        This is the final setup:
  239.  
  240.              Current directory:  /usr/log/sample
  241.              Home directory   :  /usr/llog
  242.              RCSDIR           :  /usr/RCS
  243.              RCSWORK          :  /usr/log
  244.  
  245.              Final RCS storage:  /usr/RCS/sample/arix
  246.  
  247.  
  248. SSEECCUURRIITTYY
  249.                             Secure archives
  250.  
  251.        _C_i_i_/_c_o_o  will also secure archives.  Changing ownership of
  252.        the cii or coo program to root, and making  it  suid  will
  253.        allow  private  archives.  With this option, an additional
  254.        environment variable is searched for: "RCSOWN".   If  this
  255.        is  not  found, the default name "rcsfiles" is used in the
  256.        following step.
  257.  
  258.        The user name is searched for in  the  /etc/password.   If
  259.  
  260.  
  261.  
  262.                                                                 4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CIO(1)                                                     CIO(1)
  269.  
  270.  
  271.        not  found,  the  real users UID will be used instead.  In
  272.        this fashion, the ci and co programs will be  called  with
  273.        the  appropriate uses abilities to create directories, and
  274.        save files.  Only the user who  owns  the  RCS  files  has
  275.        write  ability  without  going through the cii or coo pro-
  276.        grams.
  277.  
  278.        The only condition that allows the program  to  remain  in
  279.        the  root  owned  mode is to have the rcsfiles have a root
  280.        account.  Otherwise, it moves out of the root as  soon  as
  281.        it's found the user.
  282.  
  283.  
  284. OOTTHHEERR NNOOTTEESS
  285.        _C_i_i  will  not  unlink  files not owned by the user who is
  286.        checking in the files.  This prevents users from  deleting
  287.        files  not  owned  by  them, possibly causing harm. (I.E.,
  288.        checking in the /etc/passwd file.)  _c_o_o does  not  run  as
  289.        root, it runs as the real user.  Hence, it is not possible
  290.        for a user to overwrite files or directories they normally
  291.        do not have write access to.
  292.  
  293.        _C_i_i_/_c_o_o only will allow extraction of code by the users in
  294.        the same group as the user who checked the sources in.
  295.  
  296.  
  297.        We highly suggest that you exmine the code in the security
  298.        area  if  you  plan  on running it secure.  We've tried it
  299.        secure, and it seems to work.  However...  We  are  by  no
  300.        means  the "great U*IX hackers", so there is probably some
  301.        way to run the program that we missed that can allow  oth-
  302.        ers access to restricted files.  Check it out! If you *do*
  303.        find something we missed, please send us mail.
  304.  
  305.  
  306. EEDDIITTOORR CCOOMMMMAANNDDSS
  307.        The input editor for the logfile entries  and  title  file
  308.        entries  have  tilde (~) command options available.  These
  309.        are:
  310.                ?  -  Print a help menu.
  311.                .  -  End of input.
  312.                !  -  Invoke a user shell.  Note: Shell is invoked
  313.                      as the real user-id; No arguments are passed
  314.                      or allowed.  The ENV variable "SHELL" is
  315.                      searched for, if not present /bin/sh will be
  316.                      invoked.
  317.                e  -  Edit the message using a default editor.
  318.                      Searches for the ENV variable VISUAL or
  319.                      EDITOR.  If not found, /usr/bin/vi is the
  320.                      default editor.
  321.                p  -  Print message buffer.  Displays the current
  322.                      contents of the message buffer.
  323.                r  -  Read in a file.  Requires file name as an
  324.                      argument.  Named file will be appended to
  325.  
  326.  
  327.  
  328.                                                                 5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. CIO(1)                                                     CIO(1)
  335.  
  336.  
  337.                      current buffer.
  338.                w  -  Write message to a file.  Requires file name
  339.                      as an argument.  Appends message buffer to
  340.                      file name given.  If file does not exist,
  341.                      creates file.  Does not create  directories.
  342.  
  343.  
  344.  
  345. AAUUTTHHOORRSS
  346.        Jason  P.  Winters  (jason@grinch.uucp)  and  Craig J. Kim
  347.        (cjkim@aeras.uucp)
  348.  
  349. FFIILLEESS
  350.        The following template files can be created to insert  RCS
  351.        header  into  source  files  during  _c_i_i  process  with -H
  352.        option.  The location for these files is specified by set-
  353.        ting  $RCSHEAD  environment  variable.  If $RCSHEAD is not
  354.        set, $HOME will be used instead.  File  types  are  deter-
  355.        mined  by examining the content via file(1) program and by
  356.        file extensions (e.g. .c for C  programs,  .mk  for  make-
  357.        files, .1 for nroff, and .s for assembly).
  358.  
  359.                .rcshead       - default template
  360.                .rcshead.c     - C program template
  361.                .rcshead.s     - Assembly source template
  362.                .rcshead.sh    - Shell script template
  363.                .rcshead.f     - Fortran program template
  364.                .rcshead.mk    - makefile template
  365.                .rcshead.h     - C header file template
  366.                .rcshead.roff  - nroff, troff, man file template
  367.  
  368.  
  369. DDIIAAGGNNOOSSTTIICCSS
  370.        Linking  cio  to ciitest or cootest will cause the program
  371.        to parse the directory paths,  and  print  out  the  final
  372.        pathnames.   Nothing  else  happens.   Using the -N option
  373.        will cause the program to execute as normal,  except  that
  374.        no files or directories will be created.
  375.  
  376.  
  377. BBUUGGSS
  378.        On some systems, the Control-D as end of input to a log or
  379.        title entry can cause problems with STDIN.  We've added  a
  380.        call  to clearerr(), but have not tested if that fixes it.
  381.        ( It doesn't break it, so... )
  382.  
  383.        Any other bugs we would like to hear about.  We might even
  384.        make a new release, if people actually use this.  :)
  385.  
  386. AAUUTTHHOORR
  387.        Jason Winters, grinch!jason
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                                                                 6
  395.  
  396.  
  397.