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