co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
NAME
co -- check out a file under RCS
SYNOPSIS
co [-ddate] [-f[rev]] [-Ffile...] [-G] [-g] [-h] [-I] [-jjoin-
list] [-K] [-k]
[-l[rev]] [-O] [-p[rev]] [-q[rev]] [-r[rev]] [-sstate] [-u[rev]]
[-w[author]]
[-x] [-Yfile] file...
DESCRIPTION
Note: The MPE/iX implementation of this utility does not function
exactly as this man page describes. For details, see the MPE/iX
NOTES section at the end of this man page.
co checks out the most recent revision of a file from the corre-
sponding RCS file and makes it available in a working file.
Revisions from an RCS file may be checked out locked or unlocked.
Locking a revision prevents overlapping updates. A revision
checked out for reading or processing (that is, compiling) need
not be locked. A revision checked out for editing should usually
be locked, to prevent someone else from editing the file at the
same time. If you try to check out a revision and lock it, the
operation fails if the revision is already locked by another
user. (A lock may be broken with the rcs(1) command if you
insist.)
To use co with locking, you must be on the access list of the RCS
file, unless you are the owner of the file, you are the system
administrator, or the access list is empty. co without locking
is not subject to access list restrictions, and is not affected
by the presence of locks.
Revisions may be selected for check-out according to revision
number, branch number, check-in date/time, author, or state.
This is done by putting options after the co command. When two
or more options are specified in combination, co retrieves the
latest revision that satisfies all of them. If no options are
specified, co retrieves the latest revision on the default branch
(normally the trunk; see the -b option of rcs(1)). A revision or
branch number may be attached to any of the options -f, -l, -p,
-q, -r, or -u. The options -ddate, -sstate, and -wauthor
retrieve a revision with particular identification fields from
the default branch or the branch specified by one of -f, -l, -p,
-q, -r, or -u.
A co command applied to an RCS file with no revisions creates a
zero-length working file.
co suppresses keyword expansion unless the configuration file
specifies KeywordExpand. If you specify the -k or -K options,
1
co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
keyword expansion is suppressed in any case.
You do not need to specify whether the RCS file is compressed
when checking out a revision. For all commands, RCS automati-
cally determines whether or not the file is compressed; in either
case, the checked-out working file is not compressed.
Options
co accepts the following options:
-ddate
retrieves the latest revision on the selected branch with a
check-in date/time that is less than or equal to date. The
date and time may be given in free format and are converted
to local time. Below we give some examples of formats for
date:
22-April-1982, 17:20-CDT
2:25 AM, Dec. 29, 1983
Tue-PDT, 1981, 4pm Jul 21
Fri, April 16 15:52:25 EST 1982
If parts of the date or time are omitted, co determines the
defaults in the order year, month, day, hour, minute, and
second (most to least significant). At least one of the
fields of the date/time must be provided. For omitted
fields that are of higher significance than the highest pro-
vided field, the current values are assumed. For all other
omitted fields, the lowest possible values are assumed. For
example, the date 20, defaults to 10:30:00 of the 20th of
the current month and current year. The date/time must be
enclosed in quotes if it contains spaces.
-f[rev]
forces the overwriting of the working file. This is useful
in connection with -q. Also see the File Modes subsection.
-Ffile
provides an alternate way to specify file names. The given
file is a text file containing a list of file names, one
file name per line. co checks out all the files named in
file, using the options specified on the command line. Mul-
tiple -F options may be specified on the command line, and
can either be grouped together or interspersed between
options.
-G sets the RCS file date to the current date. Normally, when
updating, the date stamp of the RCS file is set to the
check-in date of the head revision.
-g sets the date of the working file to the current date. Nor-
mally, it is set to the check-in date of the revision.
2
co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
-h forces diff to use the -h option when called by co. This
saves time if you know that the file is large enough to
require the -h option.
-I allows co to accept redirected input from a file or input
from a pipe instead of standard input. Input is a sequence
of strings separated by lines containing only a single dot.
-jjoinlist
is typically used to take changes from one branch and incor-
porate them into another branch. Technically speaking, -j
generates a new revision which is the join of the revisions
on joinlist. A join operation works with three revisions:
root, rev1, and rev2. co determines all the changes needed
to change root into rev1 and applies those changes to a copy
of rev2. This is particularly useful if rev1 and rev2 are
the ends of two branches that have root as a common ances-
tor.
If rev1 < root < rev2 on the same branch, joining generates
a new revision which is like rev2 but with all changes that
lead from rev1 to root undone. If changes from root to rev1
overlap with changes from root to rev2, co prints a warning
and includes the overlapping sections, delimited by the
lines:
<<<<<<< rev1
lines in rev1
=======
lines in rev2
>>>>>>> rev2
In the option -jjoinlist, joinlist is a comma-separated list
of colon-separated pairs, of the form root:rev2, where root
and rev2 are (symbolic or numeric) revision numbers.
For the initial pair in the joinlist, rev1 is taken to be
the revision selected by previous options to the co command,
such as -r, -l, etc. For later pairs in the list, rev1 is
the revision generated by the previous pair. The output of
one join becomes the input to the next.
For the initial pair in the list, root may be omitted. The
default is the latest common ancestor of rev1 and rev2. If
any of the arguments indicate branches, the latest revisions
on those branches are assumed. The options -l and -u lock
or unlock rev1.
-K suppresses keyword expansion and removes all existing expan-
sions. This option takes precedence over the -k option.
-k suppresses keyword expansion, even if KeywordExpand is
specified in the configuration file. This is useful for
non-readable binary files such as object files.
3
co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
-l[rev]
same as -r, except that it also locks the retrieved revision
for the person checking out the file. See -r for handling
of the revision number rev.
-O ignores any default options found in the local configuration
file.
-p[rev]
prints the retrieved revision on the standard output rather
than storing it in the working file. This option is useful
when co is part of a pipeline.
-q[rev]
quiet mode; diagnostics are not printed.
-r[rev]
retrieves the latest revision number that is less than or
equal to rev. If rev indicates a branch rather than a revi-
sion, the latest revision on that branch is retrieved. If
rev is omitted, the latest revision on the default branch is
retrieved (see the -b option for rcs(1)). rev is composed
of one or more numeric or symbolic names separated by a dot
(.). The numeric equivalent of a symbolic field is speci-
fied with the -n option of the commands ci(1) and rcs(1).
-sstate
retrieves the latest revision on the selected branch with a
state that is set to state.
-u[rev]
same as -r, except that it unlocks the retrieved revision
(if it was locked by the person checking it out). If rev is
omitted, -u retrieves the latest revision locked by the
user; if no such lock exists, it retrieves the latest revi-
sion on the default branch.
-w[author]
retrieves the latest revision on the selected branch which
was checked in by the user with login name author. If the
argument author is omitted, the caller's login name is
assumed.
-x forces keyword expansion. This option takes precedence over
the -K option.
-Yfile
specifies file as the local configuration file.
Keyword Substitution
Strings of the form $keyword$ and $keyword:...$ embedded in the
text are replaced with strings of the form $keyword: value$ where
keyword and value are pairs from the Table of Keywords shown in
4
co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
this man page. Keywords may be embedded in literal strings or
comments to identify a revision. To use keyword expansion, you
enter strings of the form
$keyword$
in the original file. On check-out, co replaces these strings
with strings of the form
$keyword: value$
If a revision containing strings of the latter form is checked
back in, the value fields is replaced during the next check-out.
Thus, the keyword values are automatically updated on check-out.
Keyword expansion can be performed in all kinds of files, includ-
ing binary files. If keyword expansion is inappropriate for your
file, you can specify the -k option of co or add NoKeywordExpand
to your configuration file. If you wish to remove all previous
keyword expansions, specify the -K option of co.
_________________________________________________
|Keyword Meaning |
|________________________________________________|
|$Author$ The login name of the user who |
| checked in the revision. |
|$Date$ The date and time the revision was |
| checked in. |
|$Header$ A standard header containing the |
| full path name of the RCS file, the |
| revision number, the date, the |
| author, and the state. |
|$Id$ Same as $Header$, except that the |
| RCS file name is without a path. |
|$Locker$ The login name of the user who |
| locked the revision (empty if not |
| locked). |
|$Log$ The log message supplied during |
| check-in, preceded by a header con- |
| taining the RCS file name, the |
| revision number, the author, and |
| the date. Existing log messages |
| are not replaced. Instead, the new |
| log message is inserted after |
| $Log:...$. This is useful for accu- |
| mulating a complete change log in a |
| source file. |
|$Name$ The symbolic name of the revision. |
|$RCSfile$ The name of the RCS file without |
| path. |
| The revision number assigned to the |
|________________________________________________|
5
co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
_________________________________________________
| revision. | $Revision$
|$Source$ The full path name of the RCS file. |
|$State$ The state assigned to the revision. |
|________________________________________________|
Table 1: Table of RCS Keywords
File Modes
The working file inherits the read and execute permissions of the
RCS file. In addition, the owner's write permission is turned on
unless the file is checked out unlocked and locking is set to
strict (see rcs(1)).
If a file with the name of the working file already exists and
has write permission, co aborts the check-out if -q is given, or
asks whether to abort if -q is not given. If the existing work-
ing file is not writable or -f is given, the working file is
deleted without asking.
Files
The person who enters the command must have write permission in
the working directory, read permission for the RCS file, and
either read permission (for reading) or read/write permission
(for locking) in the directory which contains the RCS file.
A number of temporary files are created. A semaphore file is
created in the directory of the RCS file to prevent simultaneous
update.
DIAGNOSTICS
Possible exit status values are:
0 Successful completion.
1 An error occurred while checking out one of the specified
files.
The RCS file name, the working file name, and the revision number
retrieved are written to the diagnostic output.
Messages
Message: -K has precedence over -k
Cause: You specified both the -K option and the -k option.
These two options are mutually exclusive. The command
behaves as though only the -K option was specified.
Action: If you do not want the behaviour described under CAUSE,
specify only one of the two options.
Message: -l has precedence over -u
Cause: You specified both the -l option and the -u option.
These two options are mutually exclusive. The command
behaves as though only the -l option was specified.
Action: If you do not want the behaviour described under CAUSE,
6
co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
specify only one of the two options.
Message: -x has precedence over -k
Cause: You specified both the -x option and the -k option.
These two options are mutually exclusive. The command
behaves as though only the -x option was specified.
Action: If you do not want the behaviour described under CAUSE,
specify only one of the two options.
Message: Can't adjust mode of filename: system error
Cause: See syserror(3).
Action: See syserror(3).
Message: cannot create "filename": system error
Cause: See syserror(3).
Action: See syserror(3).
Message: Can't create workfile; see new_workfile: system error
Cause: See syserror(3).
Action: See syserror(3).
Message: Can't parse date/time: dates
Cause: You specified a date/time string with the -d option
that was not properly formatted.
Action: Check the DESCRIPTION section of this man page for the
proper format for the date/time string provided with
the -d option.
Message: Can't preserve mode of filename: system error
Cause: See syserror(3).
Action: See syserror(3).
Message: Can't rewrite rcsfile; saved in: new_rcsfile: system
error
Cause: See syserror(3).
Action: See syserror(3).
Message: Can't unlink filename: system error
Cause: See syserror(3).
Action: See syserror(3).
Message: empty join
Cause: You specified the -j option without providing any argu-
ments.
Action: Provide the list of revisions that you want to join as
an argument to the -j option.
Message: Error closing input file filename
Cause: The RCS file filename is compressed and an error
occurred during decompression.
Action: The file is possibly corrupt. Try again with another
copy of the file.
7
co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
Message: Inconsistent date/time: date
Cause: You specified an argument with the -d option that was
not a valid date and time.
Action: Make sure that the time you entered was correct, and
try again.
Message: join pair incomplete
Cause: You specified the -j option, but the list of revisions
provided as an argument was not in the correct format.
Action: Check the DESCRIPTION section for details on the format
of the revision list used with the -j option.
Message: merge failed.: system error
Cause: See syserror(3).
Action: See syserror(3).
Message: Missing date for -d option
Cause: You specified the -d option, but did not provide a date
as its argument.
Action: Provide the missing date.
Message: No filename present for -F option.
Cause: You specified the -F option, but did not provide a file
name as its argument.
Action: Provide the missing file name.
Message: No input file.
Cause: You failed to specify an input file on the command
line.
Action: Provide the missing file name.
Message: Redefinition of -option option
Cause: You specified the -d, -j, -s, or -w option more than
once on the command line.
Action: Specify each of the given options only once on a com-
mand line.
Message: Redefinition of revision number
Cause: You have specified more than one revision to be checked
out. The -f, -l, -p, -q, -r, and -u options can each
take a revision as an argument; however, only one
option per command line may specify a revision.
Action: Specify, at most, a single revision.
Message: revision rev locked by username; use co -r or rcs -u
Cause: You specified a revision rev with the -u flag that is
already locked by username.
Action: Either use the -u option of rcs to break the lock or
the -r option of co to check out the given revision
without attempting to unlock it.
Message: too many joins
Cause: The list of revisions that you provided as an argument
8
co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
to the -j option contained more than the maximum number
of revisions that co can join.
Action: Try to join subsets of the list in consecutive calls to
co.
Message: Unknown option "-option"
Cause: You specified an option that is not valid for co.
Action: Check the DESCRIPTION section for a list of valid co
options.
Message: Write error when zeroing file filename: system error
Cause: See syserror(3).
Action: See syserror(3).
Message: writeable filename exists; checkout aborted.
Cause: You attempt to check out the file filename, but co
found a writable version of the file, and refused to
overwrite it.
Action: Make sure the specified file name was correct. Deter-
mine whether there have been any changes made to the
writable version, delete or move it, and try again.
For a list of error messages common to all RCS utilities, see
rcserror(3).
PORTABILITY
All UNIX systems.
The -F, -G, -g, -I, -K, -O, -q, and -Y options are extensions to
traditional implementations of co.
NOTE
The -d option accepts no date before 1970.
Some unusual date formats may not be recognized.
Links to the RCS and working files are not preserved.
MPE/iX NOTES
The current MPE/iX implementation of co has the following limita-
tions:
* Due to the fact that the comma (,) is not a valid character in
MPE/iX file names, the traditional ,v naming convention is not
currently implemented. You must have a subdirectory named RCS
under your current directory or RCS will not work properly.
* For compatibility with traditional MPE/iX security features,
you can only rename a file in an MPE/iX group if you own the
file or if you have SM capability. Because this command
attempts to rename files to which it may not have write access,
this feature can interfere with the command's operation. For
this reason, RCS archives should not be placed in an MPE/iX
9
co(1) MPE/iX Shell and Utilities co(1)
______________________________________________________________________
group, but rather should be located elsewhere in the hierarchi-
cal file system where the restriction does not apply. For
example, the default RCSPATH places the archives in a subdirec-
tory named RCS in the current working directory.
For more information on how the current MPE/iX implementation may
affect the operation of this utility, see Appendix A, MPE/iX
Implementation Considerations.
SEE ALSO
ci(1), ident(1), rcs(1), rcsclean(1), rcsdiff(1), rcsmerge(1),
rlog(1), rcsfile(3)
10