Current Supported Releases: Sablime® v6.0 & v5.2
NAME
nadmin - create and administer SBCS files
SYNOPSIS
nadmin [-nsLNRY] [-a id-list] [-d flag[value]] [-e id-list]
[-f flag[value]] [-i init-file] [-m mr-list] [-r rel] [-t
desc-file] [-v name] [-y comment] s-file ...
DESCRIPTION
nadmin is used both for creating new SBCS files and updating
internal information in existing ones. An SBCS file is
called an s-file (also version, history or storage file) and
its name always begins with an s. prefix. To each text or
binary file under SBCS control corresponds an s-file. The
s-file stores multiple versions of the original file along
with descriptive, comment and other status information
needed to maintain the version history of the file.
Command arguments start with option arguments and end with
s-file arguments. Option arguments begin with a - character
and follow standard option conventions (see OPTION RULES
below). s-file arguments can be a mix of s-files, direc-
tories and the single - character; s-file and directory
names can be full or relative path names.
If an s-file argument is a directory, nadmin processes all
s-files in that directory. Files in that directory that do
not have the s. prefix are ignored.
If an s-file argument is the - character, nadmin will read
its standard input for names of s-files and directories, one
name per line, and process them as it would command line s-
file arguments. Other names read from standard input are
ignored.
Each valid s-file name generated from the s-file arguments
is processed by nadmin. The s-file arguments need not
always themselves be s-file names but SBCS commands must
eventually resolve them into individual s-file names. The
default mechanism will expand directory names to the s-files
they contain. Additional mechanisms include the -R option,
and the sbcsenv(1) variables auto_prefix [= no] and
source_tree [= ""].
files
If a source tree is used (see sbcsenv(1)), the location of s-
is derived unambiguously from the location of the
matching g-files. In this case s-file arguments must
be g-file names. This is an extension of the tradi-
tional s-file naming conventions.
Creating new s-files.
SBCS Release 1.2 Last change: 1 April 1994 1
If the s-file does not exist, then one of the -n or -i
options must be used, and nadmin will create the s-
file. The option arguments are used to initialize the
s-file information.
Changing parameters of existing s-files.
If the s-file exists, then neither the -n nor the -i
option can be used, and the option arguments are used
to modify the s-file internal information.
The s-file internal information (flags, attributes and
descriptive text) can be queried using nprs(1) DATA key-
words, or accessed by nadmin special option values (see
TILDE SEQUENCES below).
OPTIONS
-n Create a new s-file. One of the options -n or -i is
needed when creating a new s-file.
-s Run silently. Normally nadmin prints file sizes and, if
there is more than one file, file names. It also issues
warnings when text files have no ID keywords (see
nget(1)). With -s, nadmin only reports actual errors.
If the command needs to prompt but -s is set, nadmin
declares an error and moves on to the next s-file (see
Y/N PROMPTS below).
-L Print the path to the license file. The license infor-
mation is also checked. The file is a readable text
file that is checked by most SBCS commands on start-up.
Editing the license will render it invalid.
-N No execution. nadmin simply prints the files that it
would process, but no processing is actually done.
Useful to get an advance look at what the command will
try to do when multiple files or directories are
involved.
-R Recursive mode. Without -i: for all s-file arguments
that are directories, descend recursively into sub-
directories searching for more s-files. With -i init-
file: if init-file is a directory, then the s-file
argument must also be a directory. In this case descend
recursively into the init-file directory and for each
new file create a new s-file in a matching directory
under the s-file directory. There is a y/n prompt
whenever an s-file directory needs to be created (see
Y/N PROMPTS below). This option is also controlled by
the sbcsenv(1) variable recursive [= no]. The -R
option overrules the sbcsenv setting.
-Y Suppress any y/n prompt that may arise by always
SBCS Release 1.2 Last change: 1 April 1994 2
answering y. (see Y/N PROMPTS below). This option is
also controlled by the sbcsenv variable answer_yes [=
no] The -Y option overrules the sbcsenv setting.
-a id-list
Add these IDs, login names or numerical UNIX group IDs,
to the user list of users allowed to edit the s-file.
Specifying a UNIX group ID allows all logins belonging
to that group ID. The -a option understands (1) a
comma or space separated list of names, (2) multiple -a
instances on the same command line, (3) the tilde
sequences -a~e, -a~r[file] and -a~w[file] to edit, read
or write the user table directly (see TILDE SEQUENCES
below) (4) a single - character to clear the user
table. If a list with blank separators is used, the
list must be quoted. A login or group ID preceded by a
! is denied permission to edit the s-file. By default
the user list is empty and anyone with the right UNIX
permissions is allowed to edit the s-file. The user
list matters only after all regular UNIX permissions
have been satisfied. nprs -d:UN: can be used to query
the user list.
-d flag
Delete, or unset, the specified flag in the s-file.
The -d option can only be applied to existing s-files.
Several -d options may be supplied with a single nadmin
command. See the -f flag option for the list of all
recognized flags. The only flag that can take a value
when used with -d is -df[list] where list is a list of
releases to unlock or a for all. Specifying no list is
equivalent to specifying a.
-e id-list
Erase these IDs, login names or numerical group IDs,
from the user list of users allowed to edit the s-file.
Like -a, the -e option supports (1) a comma or space
separated list of names, (2) multiple -e instances on
the same command line, user list with a text editor and
(3) a single - character to clear the user table. If a
list with blank separators is used, the list must be
quoted.
-f flag[value]
Set flag, or set flag to value. Flags and their values
are stored in the s-file flag section. The flag sec-
tion is initialized with default settings and values
and is modified using this option. There can be
several -f options on a nadmin command line. The tilde
sequence -f~e allows editing the full flag with a
screen editor, after all other flag specifications have
been applied. Recognized flags and their values are:
SBCS Release 1.2 Last change: 1 April 1994 3
- The special flag option -f- resets the full flag
table to its default.
b Allow branch versions to be created from leaf ver-
sions. Branch versions are always allowed, and
automatically created from older versions but not
from the last, or leaf, version of each branch.
If the s-file b flag is set, however, nget -b will
be able to start a new branch from a leaf version.
cceiling
Set the ceiling, or highest, release for any new
version. This must be a number greater than 0 but
less than 10000. The default is 9999. Any ver-
sion with a release number above the set ceiling
can still be retrieved, but no longer for editing.
ffloor
Set the floor, or lowest, release for any new ver-
sion. This must be a number greater than 0 but
less than 9999. The default is 1. Any version
with a release number below the set floor can
still be retrieved, but no longer for editing.
dsid Set the default version SID number (see nget(1))
to be used when nget does not specify a SID. Nor-
mally nget would retrieve the latest trunk ver-
sion.
i Change the No id keywords message (nget,
ndelta(1)) from a warning to an actual error.
This message is issued when no ID keywords (see
nget) are found in a retrieved version that is
being scanned for ID keyword expansion. Any ID
keyword, anywhere in the file, will satisfy the
check.
j Allow joint, or concurrent, edit of the same ver-
sion of a file. When a user attempts to retrieve
for editing (nget -e) a version that is already
being edited, nget issues a warning but the
attempt will succeed. The reserved version will
automatically be on a different branch. Be aware
that SBCS, at this time, provides no direct sup-
port for merging versions from different branches.
By default joint edit is not allowed.
llist
Lock this list of releases against further edit-
ing, i.e., an nget -e on any of these releases
will fail. list is a comma or space separated
list of release numbers; ranges can be indicated
SBCS Release 1.2 Last change: 1 April 1994 4
by a - between two release numbers numbers. If
spaces are used the list must be quoted. A valid
release number is an integer between 1 and 9999,
inclusive. A single a is used to indicate all
releases and is equivalent to specifying 1-9999.
A release does not have to exist in the s-file to
be locked.
n Create null deltas whenever releases are skipped.
Normally intermediate releases are skipped when
nget retrieves for edit a version with a release
number higher than the highest release in the s-
file. If the highest release version is 3.2, nget
-e -r6 will create version 6.1, skipping releases
4 and 5. If the n flag is set, skipped releases
become valid null deltas, corresponding to the
unchanged previous version. This is useful for
anchoring future branch versions. By default
there is no version associated with a skipped
release, and branching from a skipped release is
not possible.
qtext
Set the user defined text for the s-file. This
string will be substituted for all occurrences of
the %Q% ID keyword when retrieved versions are
expanded. This ID keyword is provided for appli-
cations to define and use as they choose. The
default is the null string.
mmod Set the module name of the s-file. This string
will be substituted for all occurrences of the %M%
ID keyword when retrieved versions are expanded.
The default is the s-file base name, without the
s. prefix.
ttype
Set the module type of the s-file. E.g. C code,
executable, plain text, formatted text, etc...
This string will be substituted for all
occurrences of the %Y% ID keyword when retrieved
versions are expanded. The default is the null
string.
v[program]
Make ndelta prompt for modification request
numbers (MRs) that can be used to validate a new
version. If program is given, it must be the name
of the program used to validate the MRs either
specified on the command line (-m mr-list) or
entered in reply to the MRs? prompt (see
ndelta(1)). Without a specified program, the MRs
SBCS Release 1.2 Last change: 1 April 1994 5
are recorded but not validated.
w[comp]
The -fw flag controls the compression scheme. It
can take one of the three values {"", "b", "d"}.
If -fw is given with no comp, the flag value is ""
and all compression is turned off. Under the "b"
scheme, only base versions are compressed (the
default in SBCS 1.0 and 1.1). There is always at
least one base version: the last trunk version,
but there may be more. For example, a version with
a zero size predecessor cannot be differenced and
is a natural base. Under the "d" scheme (default
in 1.2), all versions, bases and deltas, are
compressed.
Although generically called deltas, versions in an
s-file are either bases or deltas. A base version
is stored whole (and compressed), whereas a delta
is a version that has been differenced with its
predecessor version, and only the difference
stored. The predecessor is itself either a base
or a delta. In SBCS the last trunk version is
always a base version. Versions that are too
small too benefit from differencing are also
stored as bases. Depending on version sizes and
the delta scheme selected (see -fy flag), base
version may also appear in branches.
Unless increasing ndelta(1) speed is critical,
base compression is recommended. Delta compression
is not costly and makes a significant difference
when sizable deltas are expected.
x The file is executable or binary. In reality this
means "do not expand the ID keywords" (see nget(1)
ID keywords). This flag must be set for true
binary files to avoid expanding accidental
occurrences of ID keywords, thereby corrupting the
retrieved file. It should also be set for any
special format file that should not be scanned for
ID keywords. This flag also has implications for
sbcsdiff(1) and sb2sccs(1). This is the only way
SBCS currently can tell if a file should be
treated as binary or text.
By default SBCS assumes a file is text and the -fx
flag is not set. The flag can be unset, through
-dx, but this should only be done when it is known
that none of the versions already stored are
really binary or need to be protected from ID key-
word expansion.
SBCS Release 1.2 Last change: 1 April 1994 6
The fact that all SBCS s-files are binary should
not be confused with the fact that files retrieved
or stored are allowed to be binary. SBCS files
are binary because the format to for the s-file
internal tables is binary and because the dif-
ferencing algorithm produces binary deltas.
y[diff]
The -fy flag controls the delta scheme. It can
take one of the three values {"f", "d", "r"}. If
it is not set or set to "", it reverts to the
default "d". All three schemes use reverse deltas
along the trunk and differ only in how deltas are
handled along branches. The reverse deltas along
the trunk carry the trunk base version down the
trunk as the trunk grows so retrieval of the last
version is always fast. In the "f" scheme (the
default in SBCS 1.0 and 1.1), deltas along the
branches are forward. In the "d" scheme (the
default in 1.2), branches automatically use
reverse deltas when growing from a natural base.
A natural base occurs when a version is itself so
small (<50 characters) or its predecessor is so
small that it does not benefit from differencing.
Scheme "r" forces reverse deltas on all new
branches, automatically creating a base at the
beginning of a new branch. When a branch grows by
reverse deltas, as a result of scheme "d" or "r",
the branch base moves down the branch as the
branch grows, so retrieval of the last branch ver-
sion is always fast.
An application that uses long branches derived
from non-null trunk nodes should consider setting
the delta scheme to "r". The change will only
affect new branches. To extend the benefit to
existing branches, the s-file can be processed by
ncomb -p- -fyr (see ncomb(1)). A diagram showing
the delta status of the trunk and branches can be
generated with sidtree -f1679 (see sidtree(1).
-i init-file
Use init-file as the first version in the new s-file.
If the value is a single dash (-i-), nadmin reads the
initial version from standard input.
If the s-file argument is a (single) directory, the
name of the s-file created is derived from that of
init-file by adding an s. prefix to the init-file base
name.
If init-file is itself a directory, then the s-file
SBCS Release 1.2 Last change: 1 April 1994 7
argument must be a directory. In this case all files
from the init-directory are used to initialize matching
s-files in the s-file directory. If the option -R is
used, the init-directory and its subdirectories are
recursively searched for potential init-files. All
files are considered, including those beginning with a
. (dot). These files are then used to initialize s-
files in matching subdirectories of the s-file direc-
tory.
If any of the implied s-file directories does not
exist, nadmin prompts (on standard output) and waits
for a y/n reply (on standard input). If any of the -s
option or the s-file argument -, implying standard
input, was also used, nadmin declares an error and
moves on to the next init-file. If standard input is
not a terminal, the prompt is issued with a terminating
newline; if reading from standard input fails, nadmin
-i declares and error and moves on to the next init-
file. These y/n prompts can be suppressed and automat-
ically answered y by providing the -Y option (see Y/N
PROMPTS below).
Without -i, but with -n, an s-file is created empty
with the attributes specified. It will contain all the
administrative s-file tables, but version 1.1 will be
empty.
-m mr-list
Insert the indicated Modification Request (MR) IDs into
the commentary for the initial version. When specify-
ing more than one MR on the command line, mr-list is a
comma or space separated list; if spaces are used the
list must be quoted. If no MRs are needed, mr-list can
be set to -. An error results if the -fv flag is not
set or the MR validation fails (see ndelta -m).
-r rel
Set the release number of the initial version. This
can only be used with -i, when actually specifying the
initial version. The level of an initial version is
always 1, so the initial version SID will be rel.1. The
default initial release is 1. The -r option also
recognizes tilde sequences: nadmin -r~e to interac-
tively edit delta header information; -r~r[file] or
-r~w[file] to read or write the delta header informa-
tion from or to an optional file. If the file is omit-
ted, the standard input or output is used. See TILDE
SEQUENCES below.
-t desc-file
Use the text from file desc-file as the s-file
SBCS Release 1.2 Last change: 1 April 1994 8
descriptive text. The descriptive text can be queried
with nprs -d:FD:. If the s-file already exists, (1)
-t- causes the removal of any existing description, (2)
-t desc-file replaces any descriptive text by the con-
tents of the specified file and (3) -t~e brings up the
sbcsenv text editor to edit the full descriptive text.
Other available tilde sequences are -t~r[file], or
-t~w[file], to read or write the descriptive text from
or to an optional file. If the file is omitted, the
standard input or output is used. These last two
options are similar to nprs -d:FD: and nadmin -t file.
-v name
Give the initial version this version name. Version
names can be used to complement the SBCS ID (SID)
numbers that are automatically given to new versions
(see nget(1)). Across SBCS commands, new names are
specified by -v and existing names can be used with -r
wherever complete SIDs can be used (this excludes nad-
min). nadmin can be used with -r~e to edit delta table
information, including version names (see -r above).
-y comment
Install comment as a the initial version comment. If
the -y is not used, a default comment is generated, of
the form:
date and time created YY/MM/DD HH:MM:SS by login
Other versions do not automatically get a default com-
ment. Normally the -y option requires the -i and/or -n
options, and the comment of an existing version cannot
be changed. ncdc(1) has to be used to amend an exist-
ing comment. The -y option also supports tilde
sequences to directly access the delta header, MRs and
comment information (see TILDE SEQUENCES below).
OPTION RULES
All SBCS commands follow option conventions (see getopts(1))
a. all options begin with -,
b. option names are one character long,
c. options that take no value (or a numerical value) may
be grouped after a single - character,
d. options that take a value must always be used with a
value (- is usually the default value),
e. white space is allowed between an option and its value,
f. all option arguments precede file arguments on the com-
mand line.
g. a -- may be used to indicate the end of options and
beginning of file arguments.
Examples
nadmin -i /etc/motd -fv -m- s.motd
nget -e s.motd
SBCS Release 1.2 Last change: 1 April 1994 9
nget -sgl- s.motd
ndelta -y- -m- s-file
nprs -r- s-file
COMMENTS
All SBCS s-files have an s. prefix, and are created by nad-
min with default permission modes 444. The actual modes are
modified by the user's umask value (see chmod(1),
umask(1,2)) and can end up being less than 444. Secure s-
files should have mode 440, implying a umask value of 027.
(See MULTI USER ACCESS AND SECURITY below). Other SBCS com-
mands will preserve the initial modes.
If an s-file already exists and nadmin is used to modify its
internal information, a backup file is first made in the s-
file directory. It is called a Z-file and begins with a Z.
prefix. Only after successful execution of nadmin is the
Z-file removed. Any SBCS command that detects the presence
of a Z-file will first try to restore the s-file before com-
pleting its task (see Y/N PROMPTS below). Z-files are
created by all SBCS commands that need to modify the s-file.
Although this is not expected to occur, if an SBCS s-file
becomes corrupted without a Z-file backup, it cannot be
repaired with a regular text editor because of the s-file
binary format. Projects should ensure regular backups of
their s-file databases.
COMPRESSION SCHEME
The w flag (nadmin -fw/-dw) controls the amount of compres-
sion that ndelta(1) will do. Possible values are:
none defaults to "d"
"b" compress base versions
"d" compress bases and deltas
"" no compression at all
DELTA SCHEME
The y flag (nadmin -fy/-dy) controls the differencing method
used on branches. Reverse deltas are always used on trunk
versions. The default branch method (none, or "d") uses
reverse deltas along a branch if this can be done without
introducing a new base version. This is the case, e.g., if
the trunk node of the branch is a null version, because then
the first branch delta is already a base (not differenced).
Otherwise forward delta are used.
none defaults to "d"
"f" always forward delta on branches
"d" reverse delta on branches if no new base is created
"r" force reverse delta on new branches
LOCKING SCHEME
The SBCS file locking scheme is based on z-files (not to be
SBCS Release 1.2 Last change: 1 April 1994 10
confused with backup Z-files). z-file locks are used to
prevent two users from simultaneously updating an s-file or
p-file (edit-edit), or to prevent any user from reading an
s-file or p-file that is being updated (read-edit). Commands
that modify the s-files or p-files first create a z-file,
containing their process ID (PID), in the s-file directory
and remove it when they terminate. Any command that finds a
z-file must determine if it is still valid before concluding
that one of the s-file or p-file is being updated. SCCS
checks if a process with the same PID as that in the z-file
still exists; this is also the default method in SBCS (see
host_only_lock = yes below). This method fails in a host
and workstation environment and has been been complemented
in SBCS 1.2 by other locking options. There are three dis-
tinct locking options controlled by sbcsenv(1) variables.
Opt1 Opt2 Opt3
file_control_lock no no yes
host_only_lock yes no -
time_zfile_valid - 3600 -
lock_timeout 10 10 10
Opt1 The default method; it is adequate for single user pro-
jects, and for projects that run all their SBCS com-
mands on the same host.
Opt2 This modified Opt1 relies on the z-file time stamp
rather than on the z-file PID record. The lock is
assumed to be valid if it is less than time_zfile_valid
seconds old. This type of locking it more secure than
Opt1 for multi-machine environments. time_zfile_valid
should not be too low or may become meaningless because
of clock differences between host and workstations.
Opt3 This is a more general solution, based on UNIX fcntl(2)
system and network locks; it is a more complete locking
scheme than Opt1 and implements access as well as
modification locks. It will prevent someone from updat-
ing an s-file if someone is currently reading it
(edit-read). This risk is quite small but grows with
the size of the file and the number of users. Note:
some network implementations of fcntl locks my intro-
duce noticeable delays.
Faced with a valid lock, obtained from one of the above
schemes, all commands will wait lock_timeout [= 10] seconds
before giving up, polling the lock every second.
Unlike compression and differencing, the locking policy is
determined only by sbcsenv variables, and a mechanism is
needed to enforce the same locking scheme on all members of
a project. Such a mechanism exists, in the form of the
SBCSPROJ environment variable. Multi-user projects have to
SBCS Release 1.2 Last change: 1 April 1994 11
worry about access security (permissions) as well as edit
conflicts (locking). Access security is handled by the
sbcsproj(1) interface, and sbcsproj can also be used to set
SBCSPROJ and define a common set of key sbcsenv variables,
including the locking scheme (see SBCSPROJ below).
TILDE SEQUENCES
An SBCS s-file is a binary file and its internal tables are
not directly accessible. They can, however, be accessed
indirectly. nadmin makes use of intermediate plain text
formats that can be written out, read back in and even
interactively edited. These formats are accessed through
special tilde sequences in option values. These sequences
are recognized by -r (delta header table), -f (flag table),
-a (user list}, -t (descriptive text) and -y (delta header
table, delta MRs and comment). The tilde sequences are ~e
for editing, and ~r[file] and ~w[file] for reading from and
writing to file. If file is omitted, the standard input and
output are used.
Delta Header Table
The following table format is produced or expected by
the the nadmin -r~e, -r~r[file] and -r~w[file] com-
mands. The format allows comments (leading #) and
blank lines. Fields are separated by one or more blank
spaces (' ' or tab), and each record can occupy only
one line.
# s.nadmin.1
# version table
# type SID date time seq pred author [version name]
Dbc 1.4 94/02/06 09:59:50 4 0 sbcs []
Dd 1.3 94/01/21 10:39:37 3 4 sbcs []
Dd 1.2 94/01/19 10:10:44 2 3 sbcs []
Dd 1.1 94/01/14 09:57:59 1 2 sbcs []
In normal usage there should be no need to edit these
entries, but if the need arises, columns 3-4 and 7-8
representing date, time, author and version name can be
edited interactively, or read back in. When the table
is read back into the s-file, the type, SID, and seq
must match an actual s-file version, the date and time
must be valid and the version name, if any, must be
unique and not exist in the p-file. The pred field is
not checked. Only one of the type fields is checked:
whether the delta is type R or D, removed or real
delta. Note: Interactive editing locks the s-file and
should be used with care in a multi-user environment.
An alternative is to write the table out, edit it
separately, then read it back in.
Flag Table
The following table format is produced or expected by
the the nadmin -f~e, -f~r[file] and -f~w[file]
SBCS Release 1.2 Last change: 1 April 1994 12
commands. The format allows comments (leading #) and
blank lines. Fields are separated by one or more blank
spaces (' ' or tab) and each record can occupy only one
line.
# s.nadmin.1
# flag table
# flag name value
b allow_leaf_branches no
c release_ceiling 9999
d default_release none
f release_floor 1
i require_id_keywords no
j allow_joint_edit no
l locked_releases none
m module_name none
n auto_null_delta no
q user_defined_text none
t file_type none
v mr_validation none
w compression_scheme "d"
x binary_file no
y delta_scheme "d"
Entries from column 3, value, can be edited. When the
table is read back into the s-file, the flag character
and flag name must match before the value is used; when
appropriate, the value is also checked. A boolean flag
has a value of yes or no. If the flag allows or
expects a numerical or text value, that value can be
given, and if it is a text value, that value must be
double quoted. The special values no, yes and none are
keywords and should never be quoted. Not specifying
any value or specifying none is equivalent to resetting
the flag to its default. Some flags, such as w and y,
take their values from discrete sets tailored to their
meaning (see COMPRESSION SCHEME and DELTA SCHEME
above).
The values in this table match the values printed using nprs
DATA keywords (see nprs(1)).
User List
The user list is a list of names and UNIX group IDs,
possibly prefixed with !. Comments (leading #) and
blank lines are allowed and a maximum name length of 16
characters is enforced.
# s.nadmin.1
# user table
...
Descriptive Text
The descriptive text format
# s.nadmin.1
SBCS Release 1.2 Last change: 1 April 1994 13
# descriptive text
...
has a two line comment header but is otherwise the
unformatted contents of the s-file descriptive text
section. This should be line oriented ASCII text. The
ncdc command can be used by non-administrators to
append information to the descriptive text. When this
text is read back into the s-file, up to two lines of
header comments are ignored; other comments and blank
lines are preserved.
Delta MRs and Comments
The nadmin -y~e, -y~r[file] and -y~w[file] commands, on
existing s-files only, produce a table that contains
the delta header information as well as the delta MRs
and comments. The fields of the delta header that can
be changed are the same as the four fields above (see
Delta Header Table).
# s.nadmin.1
# version mr and comment table
::::: 3/3 :::::
Dd 1.3 94/01/21 02:39:37 sbcs 3 0 []
MRs:
COMMENTS:
::::: 2/3 :::::
Dd 1.2 94/01/19 02:10:44 sbcs 2 3 []
MRs:
COMMENTS:
::::: 1/3 :::::
Dd 1.1 94/01/14 01:57:59 sbcs 1 2 []
MRs:
COMMENTS:
date and time created 94/01/14 01:57:59 by sbcs
The ::::: n/m ::::: dividers as well as the MRs: and
COMMENTS: fields should be left intact. MR and comment
values should be written on new lines under their
respective keyword.
ENVIRONMENT
SBCS commands access a few exported UNIX shell environment
variables. Most of these are standard variables used by
other applications, but two of them (SBCSENV and SBCSPROJ)
are special entry points into a separately defined SBCS
environment (see sbcsenv(1)).
VISUAL, EDITOR
The ~e tilde sequence causes nadmin to first look for
the env variables VISUAL or EDITOR for the name and
path of the editor to use. If both these variables are
SBCS Release 1.2 Last change: 1 April 1994 14
not set or null, the sbcsenv variable editor [= "vi"]
is used.
PAGER
Some commands that expect more than a screenful of out-
put automatically page themselves through the pager
specified by PAGER. If that variable is not set or
null, the sbcsenv variable pager [= "cat"] is used.
The less(1) pager, a synthesis of more(1) and pg(1), is
recommended for its ability to scroll forward and back-
ward and for its improved highlight handling.
SBCSENV
Before scanning their command line, SBCS commands look
at this environment variable to locate a file contain-
ing name and value pairs used to customize the user's
SBCS environment (see sbcsenv(1)).
One important variable is source_tree [= ""]. If set,
the value for this variable must be a pair of directory
paths separated by a colon, "g-node:s-node". This
variable is used by SBCS to support the use of a
separate s-file directory tree. If this variable is
set SBCS uses it to resolve s-file arguments into
actual s-file names. A source tree is a good way to
share files among project members or simply to keep s-
files organized and safely out of the way.
SBCSPROJ
This variable is similar to, but processed just before,
SBCSENV. If it is set and non null, it is expected to
point to a file containing name and value pairs of
sbcsenv(1) variables. Variables set by SBCSPROJ are
defined cannot be redefined by SBCSENV. Setting
SBCSPROJ is be the responsibility of the SBCS adminis-
trator, and can conveniently be done in the sbcsproj
interface (see sbcsproj(1)). Only those variables that
must be similarly set for all group members have to be
set through SBCSPROJ; other variables can be set
through each user's SBCSENV.
TMPDIR, TMP, TEMP
If any of these variables, in that order, is set and
not null, SBCS will use its value as the path of the
directory for temporary files. If all three variables
are not set or null, SBCS uses the sbcsenv variable
tmpdir [ = "/tmp"].
FILES
z-file
This transient lock file serves as an edit lock. It is
created when a command (including nadmin) needs to
SBCS Release 1.2 Last change: 1 April 1994 15
modify the s-file and is removed before the command
terminates. It should not to be confused with the
backup Z-file.
Z-file
Backup file for the s-file; created for existing s-
files, it may exist after nadmin terminates if the com-
mand terminated improperly (see Y/N PROMPTS above). If
it exists, the next SBCS command will use it to restore
the s-file.
MULTI USER ACCESS AND SECURITY
Secure access of a project s-file database by multiple users
is based on UNIX system permissions and can be done in a
number of ways. The following describes one possible
arrangement, using the sbcsproj.c code template that is pro-
vided with SBCS (see sbcsproj(1)).
1. Project members should belong to a common UNIX group
(proj). (UNIX groups are maintained by the UNIX system
administrator).
2. One project member, the SBCS administrator (adm), must
own all s-files and their directories; group ownership
of these files and directories must belong to proj.
3. Permission modes are to be rwxr-x---, octal 750, for
the directories and r--r-----, octal 440, for s-files.
4. Project members access SBCS commands through a set-UID
program compiled from the sbcsproj.c template.
sbcsproj should be owned by adm and proj and its per-
mission modes should be 750. Users will type, for
example,
sbcsproj nget -e s.file
instead of
nget -e s.file
The combinations like sbcsproj nget could be aliased to
something more convenient, or, alternatively, adm could
make one line scripts (e.g., projget, containing
sbcsproj nget "$@") and place in the sbcsproj bin.
Other commands can all be handled similarly.
5. Project members' umask value should be set to 027.
6. If not all project members are to be allowed to make
new versions, the s-file user table feature must be
used to allow or disallow delta permission on an indi-
vidual basis.
If the above steps are taken, the SBCS commands will
preserve the s-file database security. The file and
SBCS Release 1.2 Last change: 1 April 1994 16
directory permissions allow direct access to the s-files
only to adm. Others must use the set-UID sbcsproj interface
to modify the s-files, and only members of proj can run that
program.
Y/N PROMPTS
nadmin issues y/n prompts on two occasions.
A backup file exists.
The command will warn that a Z-file exists and prompt
with
restore s-file now (y/n)?
When an SBCS command that modifies the s-file does not
terminate properly, it leaves behind a backup Z-file.
Termination by untrapped signals (KILL) or malfunction-
ing hardware are improper terminations, but termination
because of processing errors or interrupt signals are
proper terminations. The Z-file contains all the
information needed to restore the s-file to its state
before the last command tried to modify it. It is not,
by itself, a valid s-file. Answering y to the prompt
will restore the file before carrying out the current
task. If the user does not have the appropriate per-
missions, the command will fail. The nadmin command
with no option arguments can be used to check for the
existence of backup files. nadmin -YR can be used to
automate "search and restore" operations.
A directory does not exist.
In this case nadmin prompts
create directory now (y/n)?
If the answer is n, that file is skipped, as well as
any subsequent file that would have needed that direc-
tory.
If the silent option is set or if s-file arguments are
expected from standard input (-), the command will fail.
The prompts are issued to standard output and read the reply
from standard input. If standard input is not a terminal,
the last ' ' (space) of the prompt is replaced by \n (new-
line). If the standard input is redirected or closed the
command may also not get the expected y or n answer and
fail. The option -Y is useful in these cases.
OTHER NOTES
File Level Control
SBCS, like SCCS, provides file level version control.
To implement product level version control these tools
have to be supplemented by application specific code.
For a clear discussion that is directly applicable to
SBCS, see Source File Management with SCCS; I. Silver-
berg; Prentice Hall, Englewood Cliffs, New Jersey
SBCS Release 1.2 Last change: 1 April 1994 17
07632; 1992.
Multiple Files
The SBCS nadmin can effectively initialize or modify
multiple s-files in one command line.
Multi-User
When used in a secure multi-user project, nadmin's
editing capabilities should be limited to SBCS adminis-
trator only (see MULTI USER ACCESS above). nadmin
should not run as a set-UID program to ensure that
members of the project group can use it for its display
capabilities, but not for making administrative
changes.
Y/N Prompts
Such prompts can be unexpected and arise from (1) a
request to create a new s-file directory (when used
with -i); (2) a request to restore the s-file. Speci-
fying -Y provides a default y answer. In a secure
multi-user environment, nadmin is not set-UID, so
unless the user is the SBCS administrator, attempts to
restore an s-file will fail.
COMPARISON WITH SCCS
Unlike SCCS, SBCS uses a binary format for s-files and
therefore these files cannot be usefully examined with a
text editor. The same binary s-file format is used for all
files, text or binary. The SBCS tilde sequences provide
indirect editor access to the s-files.
SCCS only:
Options -b to uuencode(1) a binary file, -h to verify
the s-file structure, and -z to recompute the check-
sum. Some versions allow the -fi flag to specify a
string of ID keywords. Note: some version of SCCS use
uuencode to convert binary files to ASCII and then han-
dle them as text files. The s-file produced is much
larger than an SBCS binary encoded and compressed s-
file, and the difference increases with each deltas.
SBCS only:
The -fx flag for executable or binary files, the -fw
flag to control compression and the -fy flag to control
differencing. Also options -v, -L, -NRY. In SBCS the
capabilities of the -i option and the matching of s-
file arguments is much generalized. Only SBCS supports
a separate application environment and a source tree
for s-files, decoupled from the work files directories.
DIAGNOSTICS
Warning and error messages have error codes that can be used
SBCS Release 1.2 Last change: 1 April 1994 18
with nhelp(1) for a more detailed explanation.
SEE ALSO
nadmin(1), ncdc(1), ndelta(1), nedges(1), nget(1), nhelp(1),
nprs(1), nrmdel(1), nsact(1), nunget(1), nwhat(1), psd(1),
sb2sccs(1), sbcsdiff(1), sbcsenv(1), sc2sbcs(1),
sbcsproj(1).
SBCS Release 1.2 Last change: 1 April 1994 19
Return to SBCS Commands manpage index
Copyright © 2003
Lucent Technologies