home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / rcs / cio.man < prev    next >
Text File  |  1990-12-07  |  12KB  |  282 lines
  1. NAME
  2.      cio - a pair of RCS user interface programs
  3.  
  4. SYNOPSIS
  5.      cii [cii options] [ci options] [filename ...] [dirname ... ]
  6.      coo [coo options] [co options] [filename ...] [dirname ... ]
  7.  
  8. DESCRIPTION
  9.      Cii and coo are two programs that will provide an interface
  10.      to the RCS programs ci and co. They add: Recursively check
  11.      in/out directory structures, Store RCS files in a separate
  12.      directory structure, Default stores only ASCII files, ena-
  13.      bling program to be run on directories with both source and
  14.      binary.
  15.  
  16.      Command line options include:
  17.  
  18.      -A   All files.  Forces a "cp" of files that are non-ASCII.
  19.  
  20.      -H   Insert RCS header.  If a valid RCS header not found, a
  21.           template header will be inserted at the beginning of
  22.           the file being checked in.
  23.  
  24.      -N   No operation.  Causes cii or coo to display the action
  25.           that would have resulted. Nothing is executed.
  26.  
  27.      -R   Recursively walk down directories to check in/out
  28.  
  29.      -T   Force title request at start of program (Default only
  30.           gets title when required.)
  31.  
  32.      -U   Update source directory.  During a check-in, a copy is
  33.           made to the directory structure specified by $RCSSRC.
  34.           If $RCSSRC is not defined, $HOME will be used instead.
  35.  
  36.      -V   Verbose.  Be real talkative about the work being done.
  37.  
  38.      [all ci/co options]
  39.           Passes all other options  on to ci or co.
  40.  
  41.      filename
  42.           Optional file names.  If not provided, the cii program
  43.           will take all files in the current directory, or coo
  44.           will take all files saved in the RCS directory.
  45.           (Binary files only if -A was also specified.)
  46.  
  47.      dirname
  48.           Both programs will take a directory name as an argu-
  49.           ment, however: the -R option must also be specified for
  50.           it to work.
  51.  
  52. ENVIRONMENT
  53.      RCSDIR
  54.           If defined, names a path that will be used to store the
  55.           RCS files. Default is $HOME/RCS.  Final path is com-
  56.           puted by removing $HOME and/or $RCSWORK from current
  57.           path.
  58.  
  59.      RCSWORK
  60.           If defined, an alternate prefix for current working
  61.           directory.  Allows having multiple directory structures
  62.           with different prefix's.
  63.  
  64.      HOME Must be defined as the users home directory.
  65.  
  66.      RCSSRC
  67.           If defined and -U flag is specified, during a cii pro-
  68.           cedure, a copy of what's being checked in will be made
  69.           in the directory structure starting at $RCSSRC.  If not
  70.           specified, cii uses $HOME instead.
  71.  
  72.      RCSHEAD
  73.           If -H flag is specified, cii finds template header from
  74.           $RCSHEAD directory.
  75.  
  76. SAMPLES
  77.      A user with a home directory of /usr/bog, has a directory
  78.      structure called sample/arix.  He want's to store all of the
  79.      files in /usr/bog/sample/arix into the RCS system.  If nei-
  80.      ther RCSDIR or RCSWORK is defined, the RCS path defaults to
  81.      his home directory, followed by RCS, followed by the current
  82.      path.  So:
  83.  
  84.              Current directory   :  /usr/bog/sample/arix
  85.              Home directory      :  /usr/bog
  86.              RCSDIR              :
  87.              RCSWORK             :
  88.              RCSSRC              :
  89.  
  90.              Final RCS storage   :  /usr/bog/RCS/sample/arix
  91.              Final source storage:  /usr/bog/sample/arix 
  92.  
  93.      The net effect of this command is to create the RCS
  94.      directory, then to duplicate the directory structure in a
  95.      defined place. In this case, since the RCSDIR was not
  96.      defined, it defaulted to the users home directory. It is not
  97.      necessary to build the directories in RCS, the program will
  98.      build all necessary directories (Including the RCS dir, if
  99.      needed). Another example: All RCS files should reside in
  100.      /usr/RCS, so the above example turns into:
  101.  
  102.              Current directory   :  /usr/bog/sample/arix
  103.              Home directory      :  /usr/bog
  104.              RCSDIR              :  /usr/RCS
  105.              RCSWORK             :
  106.              RCSSRC              :
  107.  
  108.              Final RCS storage   :  /usr/RCS/sample/arix
  109.              Final source storage:  /usr/bog/sample/arix 
  110.  
  111.      Here is an example showing use of the RCSWORK variable. Some
  112.      sys- tems may have more than one person working on file. In
  113.      this case, the path names will have to be similar, but only
  114.      to a point. Example, /usr/tog is also working in a directory,
  115.      called sample/arix. His system would look like:
  116.  
  117.              Current directory   :  /usr/tog/sample/arix
  118.              Home directory      :  /usr/tog
  119.              RCSDIR              :  /usr/RCS
  120.              RCSWORK             :
  121.              RCSSRC              :
  122.  
  123.              Final RCS storage   :  /usr/RCS/sample/arix
  124.              Final source storage:  /usr/tog/sample/arix 
  125.  
  126.      Note that the RCS dir is the same for him. Now, let's take a
  127.      user who has decided to work somewhere other than his home
  128.      directory.
  129.  
  130.              Current directory   :  /usr/src/rog/sample/arix
  131.              Home directory      :  /usr/rog
  132.              RCSDIR              :  /usr/RCS
  133.              RCSWORK             :  /usr/src/rog
  134.              RCSSRC              :
  135.  
  136.              Final RCS storage   :  /usr/RCS/sample/arix
  137.              Final source storage:  /usr/rog/sample/arix 
  138.      
  139.      If RCSSRC is specified to keep the current source (very
  140.      useful to when one wants to browse through the current source
  141.      files) in a directory other than his HOME.
  142.  
  143.              Current directory   :  /usr/src/rog/sample/arix
  144.              Home directory      :  /usr/rog
  145.              RCSDIR              :  /usr/RCS
  146.              RCSWORK             :  /usr/src/rog
  147.              RCSSRC              :  /usr/group
  148.  
  149.              Final RCS storage   :  /usr/RCS/sample/arix
  150.              Final source storage:  /usr/group/sample/arix 
  151.      
  152.      The RCSWORK variable was removed from the current path,
  153.      before the directory structure was defined. Thus, it is
  154.      possible to be working in just about anywhere on the system
  155.      and still use the same directory structure and RCS files.
  156.  
  157.      If you want to recover a directory (or multiple ones) into a
  158.      new working directory, simply create whatever part of the
  159.      path you need, set the RCSWORK variable to be the first part
  160.      of the path, and type "coo [-R]".  Example:  A new user
  161.      (/usr/log) has decided to examine the sample/* files.  Here
  162.      are the steps:
  163.  
  164.            Current working directory: /usr/llog
  165.            mkdir sample
  166.            chdir sample
  167.            RCSDIR=/usr/RCS  export RCSDIR
  168.            RCSWORK=/usr/log  export RCSWORK
  169.  
  170.      This is the final setup:
  171.  
  172.            Current directory:  /usr/log/sample
  173.            Home directory   :  /usr/llog
  174.            RCSDIR           :  /usr/RCS
  175.            RCSWORK          :  /usr/log
  176.  
  177.            Final RCS storage:  /usr/RCS/sample/arix
  178.  
  179.  
  180. SECURITY
  181.                            Secure archives
  182.      Cii/coo will also secure archives.  Changing ownership of
  183.      the cii or coo program to root, and making it suid will
  184.      allow private archives.  With this option, an additional
  185.      environment variable is searched for: "RCSOWN".  If this is
  186.      not found, the default name "rcsfiles" is used in the fol-
  187.      lowing step.  The user name is searched for in the
  188.      /etc/password.  If not found, the real users UID will be
  189.      used instead.  In this fashion, the ci and co programs will
  190.      be called with the appropriate uses abilities to create
  191.      directories, and save files.  Only the user who owns the RCS
  192.      files has write ability without going through the cii or coo
  193.      programs.  The only condition that allows the program to
  194.      remain in the root owned mode is to have the rcsfiles have a
  195.      root account.  Otherwise, it moves out of the root as soon
  196.      as it's found the user.
  197.  
  198. OTHER NOTES
  199.      Cii will not unlink files not owned by the user who is
  200.      checking in the files.  This prevents users from deleting
  201.      files not owned by them, possibly causing harm. (I.E.,
  202.      checking in the /etc/passwd file.) coo does not run as root,
  203.      it runs as the real user.  Hence, it is not possible for a
  204.      user to overwrite files or directories they normally do not
  205.      have write access to.  Cii/coo only will allow extraction of
  206.      code by the users in the same group as the user who checked
  207.      the sources in.
  208.  
  209.      We highly suggest that you exmine the code in the security
  210.      area if you plan on running it secure.  We've tried it
  211.      secure, and it seems to work.  However...  We are by no
  212.      means the "great U*IX hackers", so there is probably some
  213.      way to run the program that we missed that can allow others
  214.      access to restricted files.  Check it out! If you *do* find
  215.      something we missed, please send us mail.
  216.  
  217. EDITOR COMMANDS
  218.      The input editor for the logfile entries and title file
  219.      entries have tilde (~) command options available.  These
  220.      are:
  221.              ?  -  Print a help menu.
  222.              .  -  End of input.
  223.              !  -  Invoke a user shell.  Note: Shell is invoked
  224.                    as the real user-id; No arguments are passed
  225.                    or allowed.  The ENV variable "SHELL" is
  226.                    searched for, if not present /bin/sh will be
  227.                    invoked.
  228.              e  -  Edit the message using a default editor.
  229.                    Searches for the ENV variable VISUAL or
  230.                    EDITOR.  If not found, /usr/bin/vi is the
  231.                    default editor.
  232.              p  -  Print message buffer.  Displays the current
  233.                    contents of the message buffer.
  234.              r  -  Read in a file.  Requires file name as an
  235.                    argument.  Named file will be appended to
  236.                    current buffer.
  237.              w  -  Write message to a file.  Requires file name
  238.                    as an argument.  Appends message buffer to
  239.                    file name given.  If file does not exist,
  240.                    creates file.  Does not create directories.
  241.  
  242. AUTHORS
  243.      Jason P. Winters (jason@grinch.uucp) and Craig J. Kim
  244.      (cjkim@aeras.uucp)
  245.  
  246. FILES
  247.      The following template files can be created to insert RCS
  248.      header into source files during cii process with -H option.
  249.      The location for these files is specified by setting
  250.      $RCSHEAD environment variable.  If $RCSHEAD is not set,
  251.      $HOME will be used instead.  File types are determined by
  252.      examining the content via file(1) program and by file exten-
  253.      sions (e.g. .c for C programs, .mk for makefiles, .1 for
  254.      nroff, and .s for assembly).
  255.  
  256.              .rcshead       - default template
  257.              .rcshead.c     - C program template
  258.              .rcshead.s     - Assembly source template
  259.              .rcshead.sh    - Shell script template
  260.              .rcshead.f     - Fortran program template
  261.              .rcshead.mk    - makefile template
  262.              .rcshead.h     - C header file template
  263.              .rcshead.roff  - nroff, troff, man file template
  264.  
  265. DIAGNOSTICS
  266.      Linking cio to ciitest or cootest will cause the program to
  267.      parse the directory paths, and print out the final path-
  268.      names.  Nothing else happens.  Using the -N option will
  269.      cause the program to execute as normal, except that no files
  270.      or directories will be created.
  271.  
  272. BUGS
  273.      On some systems, the Control-D as end of input to a log or
  274.      title entry can cause problems with STDIN.  We've added a
  275.      call to clearerr(), but have not tested if that fixes it. (
  276.      It doesn't break it, so... ) Any other bugs we would like to
  277.      hear about.  We might even make a new release, if people
  278.      actually use this.  :)
  279.  
  280. AUTHOR
  281.      Jason Winters, grinch!jason
  282.