1 tools
!   11/01/80 tools.hlp - help file to explain the use of the tools VOS
A  set  of utilities which provide powerful text processing capabilities
as well as other capabilities.  A typical invocation is:

tool arguments [<inputfile] [>outputfile] [?errorfile]

Upon invocation, three I/O connections  are  established  for  the  tool,
termed  standard  input, standard output, and errout.  If no redirection
has been specified in the command line, these connections are all to the
user's terminal.  The arguments are specific to each  tool.   Each  tool
will divulge the required arguments if invoked as

tool ?

A list of available tools may be had through the invocation of the
"HELP TOOL NAMES" command.  Further help for a particular tool may be had 
by using the "HELP TOOL toolname" or the `man' command.

2 Names
Tools available on VAX/VMS

alist   - generate paginated listing of source archive
ar      - archive file maintainer 
args    - use standard input as arguements for command
asplit  - salvage garbaged archive files

cat     - concatenate and print text files 
ccnt    - character count
cd      - change working directory
ch      - make changes in text files 
cmp     - compare two files 
comm    - print lines common to two files
convrt  - convert pip listing files to LIST carriage control
cpress  - compress input files
crt     - copy files to terminal
crypt   - crypt and decrypt standard input

d       - directory lister for ODS-2 directories
date    - print the date
dc      - desk calculator
detab   - convert tabs to spaces
dspc    - display all characters in a file

e       - optimized version of ed
echo    - echo command line arguments 
ed      - text editor 
entab   - convert spaces to tabs and spaces
exist   - check for the existence of a file
expand  - uncompress input files

fb      - search blocks of lines for text patterns
fc      - fortran compiler
field   - manipulate fields of data
find    - search a file for a pattern 
form    - generate form letter

incl    - expand included files 
intro   - list on-line documentation
isam    - generate index for pseudo-indexed-sequential access

kill    - kill a running process
kwic    - make keyword in context index

lam     - laminate files
lcnt    - line count
ld      - loader
list    - directory lister for ODS-2 directories
ll      - print line lengths
lpr     - queue files to printer
ls      - list contents of directory

macro   - process macro definitions 
mail    - send mail
malfix  - fix up old mail files for MSG
man     - run off section of users manual
mcol    - multicolumn formatting
msg     - manipulate message files
msplit  - salvage garbaged message files
mv      - move (or rename) a file

os      - overstrike - convert backspaces into multiple lines

pack    - pack words into columns
pl      - print specified lines/pages of a file
postmn  - see if user has mail
pr      - paginate files to standard output
ps      - list process status information
pstat   - determine status of a particular process
pwd     - print working directory

rat4    - ratfor preprocessor
rc      - ratfor compile
resolve - resolve mail users
resume  - resume a suspended process
rev     - reverse lines
rm      - remove files
roff    - format text 
ruler   - display ruler on terminal screen

sched   - repetitive invocation of a command
sedit   - stream editor
sh      - shell (command line interpreter)
sleep   - cause process to suspend itself for a period of time
sndmsg  - send mail to other users
sort    - sort and/or merge text files 
spell   - find spelling errors
split   - split a file into pieces
suspnd  - suspend a running process

tail    - print last lines of a file
tee     -  copy input to standard output and named files
timer   - time execution of a process
tr      - character transliteration 
tsort   - topologically sort symbols

uniq    - strip adjacent repeated lines from a file
unrot   - unrotate lines rotated by kwic
users   - list valid mail system users

wc      - count lines, words and characters
wcnt    - (character) word count

2 alist
       alist - generate paginated listing of source archive

SYNOPSIS
       alist file ...

DESCRIPTION
       alist  generates a paginated listing of archive files.  A table
       of contents with the relative page number  in  the  listing  is
       displayed first, with each element of the archive file starting
       on a new page.  alist considers each line which starts with the
       string  "#-h-"  to  be  the  beginning  of a new entry, so that
       nested archives will be  handled  reasonably.  The  listing  is
       displayed  on  standard  output,  and  may be piped into lpr to
       queue to the printer.

FILES

SEE ALSO
       pr - print files

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 ar
       ar - archive file maintainer

SYNOPSIS
       ar {dpstux}[v/1] arcname [file] ...

DESCRIPTION
       Ar  collects  sets  of  arbitrary  files  into one big file and
       maintains that file as an 'archive'.  Files  can  be  extracted
       from  the  archive,  new  ones  can  be  added, old ones can be
       deleted or replaced by updated versions,  and  data  about  the
       contents can be listed.
       
       If  a  minus  sign  ('-') is given as a file name, further file
       names are read from the standard input, one file name per line.
       
       Files that are to be added to an archive must  exist  as  files
       with  the name given.  Files that are extracted from an archive
       will be put onto files with the  name  given.  Files  that  are
       added  to archives can, of course, be archive files themselves.
       There is no (theoretical) limit to the number of files that can
       be nested this way. Thus AR provides the utility  necessary  to
       maintain tree-structured file directories.
       
       AR is invoked by the command line
       
                 AR command archname [optional filenames]
       
       where 'command' is any one of 'uxtpds', optionally concatenated
       with  'v'  or  '1', specifying what operation to perform on the
       archive file named 'archname'. The possible commands are:
       
                 u - Update named archive by replacing existing  files
                 or adding new ones at end. If the 'v' option is used,
                 file  names will be printed on the standard output as
                 files are written to the new archived file.
                 
                 x - Extract named files from archive.  Put onto  file
                 of  the  same  name. If the 'v' option is added, file
                 names will be printed on the standard output as files
                 are extracted.
                 
                 d - Delete named  files  from  archive.  If  the  'v'
                 option  is  used,  file  names will be printed on the
                 standard output as they are deleted from the archive.
                 
                 p - Print named files on standard output.  Using  the
                 'v'  option  will  cause the file name to precede the
                 file.
                 
                 t - Print table of archive  contents.  Normally,  the
                 table  will  contain  only  the file name. If the 'v'
                 option is used,  the  table  will  also  contain  the
                 file's  length,  type,  and  date  and  time  of last
                 change. By default,  if  the  standard  output  is  a
                 terminal,  ar  will  pack  five names per line in the
                 non-verbose mode.  If  the  optional  '1'  option  is
                 used,  the output is force to single column, which is
                 the default is standard output  is  not  a  terminal.
                 For example,
                 
                 ar t archive
                 
                 might generate the following output:
                 
                 a               b               c               d
                 
                 whereas
                 
                 ar t1 archive
                 
                 would generate
                 
                 a
                 b
                 c
                 d
                 
                 
                 s  -  Salvage.  This command may be used to recover a
                 damaged  archive   whose  character  counts  do   not
                 reflect the correct number of characters in the file.
                 The  's' command extracts all files from the archive,
                 ignoring characters counts,  date  and  time  stamps,
                 etc.  on  the  archive  header  lines; it simply uses
                 '#-h-, which begins each archive member, and the file
                 name which follows it. The files are then replaced in
                 the archive, with corrected character  counts.  Thus,
                 the  's' flag is useful for salvaging the contents of
                 'alien'  archive  files  and   for   saving   damaged
                 archives.  It  does not work on nested archives (i.e.
                 archives within archives).
                 
                 v - Verbose.  This command may be concatenated to any
                 of the above commands, and will cause the archiver to
                 print additional information, generally  file  names,
                 on  the standard output. Its specific action for each
                 command has already been described.
       
       The optional filenames in the command line  specify  individual
       files  that  may  participate  in  the  action. If no files are
       named, the action is done on ALL files in the archive,  but  if
       any  files  are  explicitly  named, they are the ONLY ones that
       take  part  in   the   action.   (The   'd'   command   is   an
       exception--files  may  be  deleted  only  by  specifying  their
       names.)

FILES
       A file 'arctemp' is created and subsequently deleted  for  each
       run.

SEE ALSO
       The Unix commands 'ar' and 'ls' in the Unix manual

DIAGNOSTICS
       archive not in proper format
                 The  basic  problem  is  that  archive  didn't find a
                 header line where one was expected.  Typical  reasons
                 include  misspelling the file name, using an existing
                 file (not in archive format) on a creation  run,  and
                 referencing  an  archive  file that has been modified
                 directly (say with the editor).
       
       delete by name only
                 For user protection, files are allowed to be  deleted
                 from an archive only by specifying each file name.
       
       duplicate file name
                 A  file  was  listed  more than once when calling the
                 archiver
       
       fatal errors-archive not altered
                 This message is generated whenever one or more of the
                 other errors have been detected.  An archive is never
                 altered unless EVERYTHING has run properly.
       
       too many file names
                 At the present the user may call the archiver with no
                 more than 25 files at a time.
       
       usage:  ar [dptuxsv] arcname [files]
                 The command line passed to the archiver is in  error.
                 Possibly  the  command  is wrong or the archived file
                 name has not been given.
       
       'filename': can't add
                 The file specified by  'filename'  doesn't  exist  or
                 can't be opened (e. g. is locked).
                 
       'filename': can't create
                 The  archiver  could not generate a local file by the
                 name of 'filename'.  Probably the archiver's internal
                 file buffer space has been exceeded.
                 
       'filename': not in archive
                 The archiver could not locate the file  specified  by
                 'filename' in the archived file.
                 

AUTHORS
       Original  code  from  Kernighan and Plauger's 'Software Tools',
       with modifications by Debbie Scherrer.

BUGS/DEFICIENCIES
       On some systems only text files can be archived.
       
       When the update and print commands  are  used,  the  files  are
       updated  or  printed  in  the order they appear on the archived
       file, NOT the order listed on the command line.
       
       The 's' salvage command works only on unnested archives.
       
       The Unix archiver allows files to be positioned in the archive,
       rather than simply added at the end as AR does. This is done by
       adding the following commands:
                 
                 m - Move specified files to end of archive
                 
                 ma posname - Move specified files to  position  after
                 file 'posname'
                 
                 mb  posname - Move specified files to position before
                 file 'posname'
                 
                 r - Replace specified  files  and  place  at  end  of
                 archive
                 
                 ra  posname  -  Replace  files  and  place after file
                 'posname'
                 
                 rb posname - Replace  files  and  place  before  file
                 'posname'
       
       There are some discrepancies between the Unix version of AR and
       this  version.   Unix uses 'r'--replace instead of 'u'--update.
       Unix also requires the user to specify  an  additional  command
       'n' when creating a new archive.                                 -4-                                  

2 args
        args - use standard input as arguments for command
        
     SYNOPSIS
        
        args [-v] tool [arguments]
        
     DESCRIPTION
        
        args reads the standard input file and concatenates the words found
        there  onto  the arguments passed to args.  It then spawns the tool
        "tool" with those arguments.  The first argument to args which does
        not start with a "-" is taken to be the name  of  the  tool  to  be
        invoked.   args  uses  the  same  search  path as the shell, and if
        "tool" is a script file, a  copy  of  the  shell  will  be  spawned
        reading  that  file  for  its  commands.   The optional -v argument
        causes args to display the final  command  line  on  ERROUT  before
        spawning the sub-process.
        
        The  most common use of args is as a form of argument explosion, as
        in the following example:
        
             Suppose the user wishes to delete all  files  which  have  the
             string   "tst"   somewhere  in  the  filename.   This  may  be
             accomplished with the following shell command line:

             % ls tst | args rm -v

             All of the files matching the pattern "tst"  will  be  fed  to
             args,  which  will  concatenate  the  names  onto rm's command
             line.  rm will then be spawned, and will  print  the  name  of
             each file as it is deleted.
             
        If  the  information found on standard input is so voluminous as to
        cause the argument string to be too  large,  the  command  line  is
        displayed  on ERROUT and the process is NOT spawned.  This prevents
        the user from being destroyed by his/her indescretion.
        
     FILES

        none

     SEE ALSO

        sh - command line interpreter (for search path rules)

     AUTHOR

        args was written by Joe Sventek

     BUGS/DEFICIENCIES

        If the arguments to be passed to "tool" on the  args  command  line
        are to include io redirection, they must be escaped with an @ as in
        the following example:

             % ls %a | args cat "@>alist"

        The  redirections  must  be  escaped, since args will open alist as
        it's standard output, rather that handing the string >alist to cat.
        It is also necessary to surround the escaped io redirection  string
        in  quotes,  since  the  shell  does  something special with @[<>?]
        strings.

2 asplit
        asplit - salvage garbaged archive files
        
     SYNOPSIS
        
        asplit <file [-tstring] [-v]
        
     DESCRIPTION
        
        asplit  reads  the standard input file, looking for lines beginning
        with the archive header flag (#-h-).  Upon locating  such  a  line,
        the next word after the header is used to generate a file name, and
        all  lines  read up to the next pseudo-header line are written onto
        that file.  When generating the  file  name,  only  the  characters
        found  before a left parenthesis are used, if one is found.  If the
        -t switch is used, the string appended to the  -t  is  appended  to
        each  file  name before the file is opened, thus permitting a fixed
        tag string to be formatted into the file name.  If the -v option is
        specified, the name of each file is reported on  ERROUT  as  it  is
        opened.  Any  lines  found  at the beginning of the file before the
        first pseudo-header line is copied to standard output.
        
        asplit is commonly used  to  salvage  an  archive  which  has  been
        garbaged,  or  to  take  a  monster fortran source program file and
        break it up into subroutines. A script file (breakup) may be  found
        on  the  tools binary directory which will cause each subprogram of
        the form "subroutine snarf" or "... function snarf" to be placed on
        a file of the name  "snarf.qq".   The  only  side  effect  of  this
        transformation is that the source will be in lower case, and may be
        remedied by modifying the file breakup.
        
     FILES
        
        none
        
     SEE ALSO
        
        ar  -  file archiver: the -s switch does essentially the same thing
        as asplit, except that it tries to rebuild the source file as a new
        archive, which does not always work in pathological cases.
        
     AUTHOR
        
        asplit was written by Joe Sventek
        
     BUGS/DEFICIENCIES

2 cat
       cat -- concatenate and print text files

SYNOPSIS
       CAT [file1] [file2]...

DESCRIPTION
       Cat  reads  each file in sequence and writes it on the standard
       output. Thus

            CAT file

       prints the file, and

            CAT file1 file2 >file3

       concatenates the first two files and places the result  on  the
       third.

       If no argument or '-' is given, cat reads the standard input.

FILES
       None

SEE ALSO
       The "Software Tools" book, p. 77.
       The UNIX tools CAT, PR, CP

DIAGNOSTICS
       A  message  is  printed  if  a  file  cannot be opened; further
       processing is terminated.

AUTHORS

       Dennis Hall, Debbie Scherrer and Wen-Sue Gee.

BUGS
       Using the same file for output  as  well  as  input  may  cause
       strange results.

2 ccnt
       ccnt - character count

SYNOPSIS
       ccnt [file ...]

DESCRIPTION
       Ccnt  counts  characters  in  the  named  file(s). Newlines are
       counted as characters. If no file  name  or  the  file  '-'  is
       given, standard input will be read.

FILES

SEE ALSO
       wcnt; lcnt; the Unix command 'wc'

DIAGNOSTICS
       A message is printed if an input file cannot be opened; further
       processing is terminated.

AUTHORS

       Original  from  Kernighan  and Plauger's 'Software Tools', with
       minor modifications by Debbie Scherrer.

BUGS

2 cd
       cd - change working directory

SYNOPSIS

       cd directory

DESCRIPTION

       cd changes the working directory to directory.

       Since  a  new  process  is  created to execute each command, cd
       would be ineffective if it were written as  a  normal  command.
       It is therefore recognized and executed by the shell.

       The forms of the directory on RSX-11M is

                                /ddnn/ggg,mmm
                                  /ggg,mmm
                               ddnn:[ggg,mmm]
                                  [ggg,mmm]

SEE ALSO

       pwd - print working directory

2 ch
       ch - make changes in text files

SYNOPSIS
       ch [-ax] [expr ...] fromexpr [toexpr]

DESCRIPTION
       ch  copies  each  line  of  the  standard input to the standard
       output, globally substituting the  text  pattern  "toexpr"  for
       "fromexpr"  on  each  line  that  satisfies  matching  criteria
       defined by the leading expressions "expr" and the switches.  (A
       text  pattern  is  a  subset of a "regular expression"--see the
       "ed" writeup  for  a  complete  description.)   Three  possible
       courses  of  action are taken depending upon the number of text
       patterns(n) found in the command line:

       n=1  The text pattern is assumed to be "fromexpr" with  a  null
            "toexpr"; it is equivalent to the ed command
                      g/fromexpr/s///g
       n=2  The  first  text  pattern  is  "fromexpr",  the  second is
            "toexpr"; it is equivalent to the ed command
                      g/fromexpr/s//toexpr/g
       n>=3 The (n-1)th pattern is "fromexpr", the nth is "toexpr" and
            patterns 1...n-2 are used  to  determine  the  lines  upon
            which  to  perform  the substitution.  The default is that
            any  line  which  matches  any  one  of  the  n-2  leading
            expressions are eligible for substitution.  If the -a flag
            is  specified,  only  lines  which  match  all n-2 leading
            expressions in any order are eligible.  If the -x flag  is
            specified,   all  lines  which  don't  satisfy  the  above
            criteria are eligible. (See the writeup on find  for  more
            information.)  In particular, if n=3,
                      ch expr from to
            is equivalent to the ed command
                      g/expr/s/from/to/g
                      ch -x expr from to
            is equivalent to the ed command
                      x/expr/s/from/to/g

       The substitution string "toexpr" may be a string of replacement
       characters,  null  to  effect a deletion, or it may include the
       special "ditto" character "&" to put back the "fromexpr" string
       and thus effect an insertion.  If a deletion  is  desired  with
       the  multiple  leading  tag expressions, a "toexpr" of "" -i.e.
       quotes around an empty string may be used.
       
       A text pattern consists of the following elements:
       
       c      literal character 
       ?      any character except newline 
       %      beginning of line 
       $      end of line (null string before newline) 
       [...]  character class (any one of these characters) 
       [!...] negated character class (all but these characters) 
       *      closure (zero or more occurrences of previous pattern) 
       +      anchored closure (one or more occurrences of previous pattern)
       @c     escaped character (e.g., @%, @[, @*) 
       
       Any special meaning of characters in a  text  pattern  is  lost
       when escaped, inside [...], or for:
       
       %         not at beginning 
       $         not at end 
       *         at beginning 
       +         at beginning
       
       A  character  class  consists  of zero or more of the following
       elements, surrounded by [ and ]:
       
       c         literal character 
       a-b       range of characters (digits, lower or upper case) 
       !         negated character class if at beginning 
       @c        escaped character (@! @- @@ @]) 
       
       Special meaning of characters in a character class is lost when
       escaped or for
       
       !         not at beginning 
       -         at beginning or end 
       
       An escape sequence consists of the character @  followed  by  a
       single character:
       
       @n        newline 
       @t        tab 
       @c        c (including @@) 
       
       For a complete description, see "Software Tools" pages 135-154.
       Care should  be taken when using the characters % $ [ ] ! * + @
       and any shell characters in  the  text  pattern.  It  is  often
       necessary to enclose the entire substitution pattern in quotes.

FILES
       None

SEE ALSO
       The UNIX tool GRES
       The tools find and ed

DIAGNOSTICS
       An error message is printed if the pattern given is illegal.

AUTHORS
       'CH'  was originally implemented on BKY by Debbie Scherrer from
       Kernighan and Plauger's "Software Tools".   Major modifications
       were performed by Joe Sventek.

BUGS/DEFICIENCIES
       A minus sign(dash[-]) may not start an expression.

2 cmp
       cmp - compare two files

SYNOPSIS
       cmp file1 file2

DESCRIPTION
       File1 is compared line-by-line with file2. If any lines differ,
       cmp  announces the line number and prints each file's offending
       line.

FILES
       None

SEE ALSO
       comm
       The UNIX commands cmp, diff, and comm

DIAGNOSTICS
       If the end of one file is reached before the end of the  other,
       a message is printed.

AUTHORS
       Acquired  from  "Software Tools" by Kernighan and Plauger, with
       minor modifications made by Debbie Scherrer.

BUGS

       If either file is binary, spurious results should be expected.

       Cmp cannot handle offset lines:  line  n  of  file1  is  simply
       compared to line n of file2.
       
       Trailing blanks are significant, which will cause some lines to
       appear similar to the user which are actually different.

2 comm
       comm - print lines common to two files

SYNOPSIS
       comm [-123] file1 file2

DESCRIPTION
       Comm  reads  file1  and  file2,  which  should  be  sorted, and
       produces a three column output: lines only in file1, lines only
       in file2, and lines in both files. The filename '-'  means  the
       standard  input.   If  there  is  only one file argument, file2
       refers to the standard input.
       
       The optional arguments -1, -2, and -3 specify the  printing  of
       only  the  corresponding  column.  Thus comm -3 prints only the
       lines common to both files, and comm -12 prints lines which are
       in either file, but not in both. The default is -123.

FILES
       None

SEE ALSO
       The tool 'cmp'; the Unix tool 'diff'.

DIAGNOSTICS
       A message is printed if an input file cannot be opened.

AUTHORS

       Debbie Scherrer

BUGS
       The flags used by this tool are the reverse of  those  used  by
       the  Unix  'comm'.   In  Unix,  the  flags 1, 2, and 3 suppress
       printing of the corresponding column. Kernighan, on page 126 of
       'Software Tools' suggests the version used above.

2 convrt
       convrt - convert pip listing files to LIST carriage control

SYNOPSIS
       convrt [<infile] [>outfile]

DESCRIPTION
       Convrt  reads  the  standard  input file, converts records with
       embedded carriage control, and copies them to  standard  output
       in LIST carriage control.  This utility is handy for converting
       listing files created by pip, dmp, flx, etc.  For example
       
       % pip temp.=[1,1]/fu
       % convrt <temp >001001.lst
       
       causes  the  full  directory  listing  of [1,1] to be placed on
       001001.lst in a form that can  be  edited  by  edi  or  ed,  or
       manipulated by any of the software tools.

FILES
       None

SEE ALSO
       None

DIAGNOSTICS
       None

AUTHORS

       Joe Sventek

BUGS
       None to date.

2 cpress
       cpress - compress input files

SYNOPSIS
       cpress [file ...]

DESCRIPTION
       Cpress  compresses  runs  of  repeated  characters in the input
       files. The output file can eventually be expanded with the tool
       'expand'.
       
       If no input files are given, or the filename '-' appears, input
       will be from the standard input.

FILES

SEE ALSO
       expand

DIAGNOSTICS
       A message is printed if an input file cannot be opened; further
       processing is terminated.

AUTHORS

       From Kernighan & Plauger's 'Software Tools', with modifications
       by Debbie Scherrer.

BUGS

2 crt
       crt - copy files to terminal

SYNOPSIS
       crt [-n] [file ...]

DESCRIPTION
       CRT  is  similar  to  'cat'  except that it prints only n lines
       (default 22) at a time. After each set of  lines  are  printed,
       crt  will  wait  for  instructions  from  the  user.  Hitting a
       carriage-return will cause the next n lines to appear,  hitting
       a 'q' (quit) will cause crt to skip over to the next input file
       (if  any),  and hitting an end-of-file character will cause crt
       to stop immediately.
       
       If no files are specified, or if the  filename  '-'  is  given,
       lines will be read from the standard input.
       
       The flag -n may be given, where n specifies the number of lines
       desired at a time.
       
       Crt  will  stop  at  the end of each file (except the last), as
       well as after each n lines.

FILES

SEE ALSO
       cat

DIAGNOSTICS
       A message is printed if an input file cannot be opened; further
       processing is terminated.

AUTHORS

       Debbie Scherrer

BUGS

2 crypt
       crypt - crypt and decrypt standard input

SYNOPSIS
       crypt key

DESCRIPTION
       Crypt encrypts characters on the standard input by using 'key'.
       The file can eventually be decrypted by running it back through
       crypt  with  the same key. Double encryption (encrypting a file
       with first one key and then another) is allowable, but on  some
       systems  the decryption must be done in the exact reverse order
       as encryption was done.
       
       The encryption algorithm used by 'crypt' is not  a  complicated
       one, so users requiring a great degree of protection should not
       rely on this tool.

FILES

SEE ALSO

DIAGNOSTICS

AUTHORS

       Original  from  Kernighan  &  Plauger's  'Software Tools', with
       modifications  by  Debbie  Scherrer.   (NOTE:    the   original
       encryption algorithm has been altered slightly.)

BUGS
       On  IAS and VMS systems, double encryption must be decrypted in
       the exact reverse order as the encryption.

2 d
   d - directory lister for structure level II directories
   
SYNOPSIS
   
   d [-1drtv] [pathname] ...
   
DESCRIPTION
   
   d  is  an  optimized  version  of ls for ODS-2 directories.  A
   further restriction on d is that the directory arguments  must
   be  in  pathname  format,  as opposed to ls, which permits DEC
   filespecs as well as the path equivalent.  The writeup for  ls
   may be consulted for the meanings of the switches.
   
FILES
   
   
AUTHOR
   
   d  was  originally  written  by  Joe Sventek, with substantial
   enhancements by Dave Martin.
   
SEE ALSO
   
   ls - portable directory lister

2 date
       date - print the date

SYNOPSIS
       date

DESCRIPTION
       The current date and time are printed in the format:
       
                             dd-mmm-yy hh:mm:ss

FILES
       None

SEE ALSO
       The Unix command 'date'

DIAGNOSTICS
       None

AUTHORS

       Debbie Scherrer

BUGS

2 dc
   dc - desk calculator

SYNOPSIS
   dc [files ...]

DESCRIPTION
   DC  evaluates  integer  expressions from the source files, one
   expression per input line. If no input files are given, or the
   filename '-' is specified, dc reads from the standard input.
   
   Ordinarily  dc  operates   on   decimal   integer   arithmetic
   expressions, but the user may specify an input base and output
   base other than decimal.
   
   Expressions   may   be   simple   arithmetic   expressions  or
   replacement expressions. The values of simple expressions  are
   written   on   standard   output   when  they  are  evaluated.
   Replacement expressions are used to hold temporary values, and
   are not automatically printed.
   
   A simple expression is a normal  arithmetic  expression  using
   numbers,  variables, parentheses, and the following operators,
   listed in order of precedence:
        +  -          unary plus and negation operators.  These may  
                          only appear at the start of a simple
                          expression or after a "("
        
        **            exponentiation
        
        *   /   %     multiply, divide, modulo (remainder)
        
        +   -         add, subtract
        
        == !=         relations - equals, not equal to,
        >  >=         greater than, greater than or equal to,
        <  <=         less than, less than or equal to
                       (!=, ^=, ~= all treated as "not equal")
        
        !             unary logical not (also ~ and ^)
        
        |   &         logical or, and
        
   The logical operators !  |  &  and  the  relational  operators
   result in the values 1 for true and 0 for false.
   
   A replacement expression is:

                      name = simple expression

   where  'name' is a character string of (virtually) any length,
   starting with a letter and  consisting  of  only  letters  and
   digits.  (The  characters a-f should not be considered letters
   when   operating   in   hexadecimal   mode.)   Variables   are
   automatically  declared  when they first appear to the left of
   an "="  sign,  and  they  should  not  be  used  in  a  simple
   expression until they have been declared.
   
   Radix Control
        Radix control is available in 2 ways:
        1)  There  are  default  radix  values for both input and
        output which may be changed  by  setting  the  predefined
        variables   'ibase'  (input  base)  and  'obase'  (output
        base).  (Radix 10 is always used to evaluate and/or print
        radix-defining expressions.) For example,

                  ibase = 2
                  obase = 16

        would  accept  input  in  binary  and  print  results  in
        hexadecimal.
        
        2)   The  radix  of  individual numbers may be explicitly
        given  by  following  the  number  with   an   underscore
        character and then the desired radix. For example,

                                 100_16

        would specify the hex number 100 (256 in decimal).

EXAMPLES

                  10 + (-64 / 2**4)
   would print the answer "6"

                  temp = 101_2
                  temp == 5
   would print the answer "1" (true)
   
                  ibase = 16
                  obase = 2
                  1a + f
   would print the answer "101001"

                  ibase = 16
                  numa = 100_10
                  numb = 100
                  numa + numb
   would print the answer "356"

FILES
   None

SEE ALSO
   macro, the UNIX M4 macro package
   The UNIX tools dc and bc

DIAGNOSTICS
   arith evaluation stack overflow
      arithmetic  expressions  have  been  nested too deeply. The
      size of the stack is set by the MAXSTACK definition in  the
      source code.
      
   number error
      an  input  number  has  a  number/character bigger than the
      current radix

   expression error
      invalid arithmetic expression

AUTHOR
   Philip H. Scherrer (Stanford U.)

BUGS/DEFICIENCIES
   Dc only works with integers
   
   The maximum value allowed depends on the host machine  and  is
   the largest Fortran integer

2 detab
       detab - convert tabs to spaces

SYNOPSIS
       detab [<t1>...] [+<n>] [file...]

DESCRIPTION
       Detab converts tab characters (control-i) to equivalent strings
       of  blanks.  Tab  stops  are  indicated  by <t1>... (default 8,
       16, ...), while +<n> indicates tab  stops  every  <n>  columns.
       Thus the command
       
          detab 5 21 +5
       
       supplies blanks for tabs terminating at column positions 5, 21,
       26, etc. If no files are specified, the standard input is read.
       An isolated minus sign also indicates the standard input.

SEE ALSO
       entab; lpr

AUTHORS

       Original  from  Kernighan  &  Plauger's  'Software Tools', with
       modifications by Dennis Hall and Debbie Scherrer.

BUGS
       None to date.

2 dspc
   dspc - display all characters in a file

SYNOPSIS
   dspc [files ...]

DESCRIPTION
   Dspc  copies the named files to the standard output, replacing
   control characters by "^c", where c  is  the  ascii  character
   used  to  enter  the  control  character  when  depressing the
   "control" key on most terminals.  More  precisely,  c  is  the
   ascii  character  whose value is 100 (octal) plus the value of
   the control character.

   Control characters are  those  ascii  characters  with  values
   between 0 and 31, inclusive.  Newline characters are displayed
   as usual, however.

   If  no filenames are given, or the name '-' is specified, show
   will read from the standard input.

SEE ALSO
   cat, page

AUTHORS
   David Hanson and friends (U. of Arizona)

2 e
   e - optimized version of ed using virtual memory
   
SYNOPSIS
   
   e [-] [-pprompt] [file]
   
DESCRIPTION
   
   e  is  an optimized version of ed for VAX/VMS.  In addition to
   the enhanced  response  characteristics  due  to  the  use  of
   virtual  memory,  several  additional  features are available.
   They are:

     1. There is a terse help command, invoked via `h'.
     2. One can cause the current contents of the  buffer  to  be
        roffed  by  issuing  the "typeset" command via `t'.  This
        causes roff to be spawned, formatting the buffer contents
        to the terminal.  The buffer contents are  not  affected.
        If  more  sophisticated  use of roff is necessary, or the
        user desires to spawn something other than roff, see  the
        ed writeup for the `@' command.
     3. A  command  is  available  to see how much of the virtual
        memory array space has been used via `%'.   If  the  user
        exhausts  the  array  space  with  many  changes,  simply
        writing the file followed by the enter command will cause
        garbage collection to occur.

   For information on the other commands to e, consult the manual
   entry for ed.
   
FILES
   
   
AUTHOR
   
   The extra features of e above those of  ed  are  due  to  Dave
   Martin.
   
SEE ALSO
   
   ed - text editor

2 echo
       echo - echo command line arguments

SYNOPSIS
       echo [arg ...]

DESCRIPTION
       Echo  writes  its  arguments in order as a line on the standard
       output  file.  It  is  useful  for   producing   messages   and
       diagnostics in command files.

FILES
       None

SEE ALSO
       The Unix command 'echo' in the Unix manual

DIAGNOSTICS
       None

AUTHORS
       Debbie Scherrer

BUGS/DEFICIENCIES

2 ed
       ed - text editor

SYNOPSIS
       ed [-] [-pstring] [file]

DESCRIPTION
       Ed  is a text editor. If the 'file' argument is given, the file
       is read into ed's buffer so that it can be edited and its  name
       is remembered for possible future use. Ed operates on a copy of
       any file it is editing; changes made in the copy have no effect
       on the file until a w (write) command is given.
       
       The  optional '-' suppresses the printing of line counts by the
       e (edit), r (read), and w (write) commands.
       
       The -p flag may be used to specify  ed's  prompt  string.   The
       default is ": ".  If prompting is not desired, a bare -p in the
       command line will turn it off.
       
       Ed accepts commands from script files as well as a terminal. To
       do  this, invoke ed and substitute the script file name for the
       standard input, as follows -
       
                        ed [file] <script
       
       Commands to ed have a simple and regular structure: zero , one,
       or two line addresses followed by a single  character  command,
       possibly  followed by parameters to the command.  The structure
       is:
       
               [line],[line]command <parameters>
       
       The '[line]' specifies a line number or address in the  buffer.
       Every  command  which requires addresses has default addresses,
       so the addresses can often be omitted.
       
       Line addresses may be formed from the following components:
       
       
           17           an integer number 
           .            the current line 
           $            the last line in the buffer 
           .+n          "n" lines past the current line 
           .-n          "n" lines before the current line 
           /<pattern>/  a forward context search 
           \<pattern>\  a backward context search 
       
       Line numbers may  be  separated  by  commas  or  semicolons;  a
       semicolon  sets the current line to the previous address before
       the next address is interpreted.  This feature can be  used  to
       determine  the  starting  line for forward and backward context
       searches ("/" and "\").
       
       
                            REGULAR EXPRESSIONS 
       
       Ed includes some additional capabilities such as the ability to
       search for patterns that  match  classes  of  characters,  that
       match  patterns only at particular positions on a line, or that
       match  text  of  indefinite  length.   These   pattern-seaching
       capabilities   include  a  class  of  patterns  called  regular
       expressions. Regular  expressions  are  used  in  addresses  to
       specify  lines  and  in the s command to specify a portion of a
       line which is to be replaced. To be able to express these  more
       general    patterns,    some    special    characters   (called
       metacharacters) are used. The regular expressions allowed by ed
       are constructed as follows:
       
       1.  An ordinary character (not one of those discussed below) is
       a regular expression and matches that character.
       
       2.  A percent "%" at the  beginning  of  a  regular  expression
       matches the empty string at the beginning of a line.
       
       3.   A  dollar  sign  "$"  at  the  end of a regular expression
       matches the null character at the end of a line.
       
       4.  A question mark "?" matches any character except a  newline
       character.
       
       5.   A  regular  expression followed by an asterisk "*" matches
       any number of adjacent  occurrences  (including  zero)  of  the
       regular expression it follows.
       
       6.   A regular expression followed by a plus "+" matches one or
       more adjacent occurrences of the regular expression it  follows
       (anchored closure).
       
       7.  A  string  of characters enclosed in square brackets "[ ] "
       matches any  character  in  the  string  but  no  others.   If,
       however,  the  first  character of the string is an exclamation
       point "!" the regular expression matches any  character  except
       the characters in the string (and the newline).
       
       8.   The  concatenation  of  regular  expressions  is a regular
       expression which  matches  the  concatenation  of  the  strings
       matched by the components of the regular expression.
       
       9.  The null regular expression standing alone is equivalent to
       the last regular expression encountered.
       
       If  it  is  desired  to  use  one  of  the  regular  expression
       metacharacters as an ordinary character, that character may  be
       escaped by preceding it with an atsign "@".

                                  COMMANDS 
       
       Following  is  a  list  of  ed commands.  Default addresses are
       shown in parentheses:
       
       (.)a
       <text>
       .
            The append command reads the given  text  and  appends  it
            after  the  addressed  line.  '.' is left on the last line
            input, if there were any, otherwise at the addressed line.
       
       (.)b[+/./-][<screensize>]
            The browse command is a shorthand command to print  out  a
            screenful of data.  It has three basic forms, any of which
            may  have  a  number("screensize")  appended  to  it.  The
            default screensize is 23.  The  b-  form  will  print  the
            screen  of  text  preceding  (and including) the addressed
            line; b. prints the screen centered on the addressed line;
            and b or b+ prints the current line and the  screen  after
            it.   "."  is  left  at  the  last  line  printed.   If  a
            screensize is specified, it becomes the default screensize
            for the rest of  the  editing  session  or  until  changed
            again.
       
       (.,.)c
       <text>
       .
            The  change  command  deletes  the  addressed  lines, then
            accepts input text which replaces  these  lines.   '.'  is
            left  at the last line input, if there were any, otherwise
            at the first line not deleted.
       
       (.,.)d
            The delete command deletes the addressed  lines  from  the
            buffer.  The  line  originally AFTER the last line deleted
            becomes the current line; however, if  the  lines  deleted
            were  originally at the end, the new last line becomes the
            current line.
       
       e filename
            The edit command causes the entire contents of the  buffer
            to  be  deleted and then the named file to be read in. '.'
            is set to the last line of the buffer. The number of lines
            read is typed. 'Filename' is remembered for  possible  use
            as  a default file name in a subsequent r or w command. If
            changes have been made to the current file since the  last
            write  command,  the user will be asked to repeat the edit
            command.
            
       f filename
            The filename command prints the currently remembered  file
            name.  If  'filename'  is  given, the currently remembered
            file name is changed to 'filename'.
       
       (1,$)g/regular expression/command
            In the global command, the given command is  executed  for
            every  line  which  matches  the given regular expression.
            Multiple commands may be executed by  placing  each  on  a
            preceding line and terminated each command except the last
            with an atsign '@'.
       
       (.)i
       <text>
       .
            The  insert  command  inserts  the  given  text BEFORE the
            addressed line. '.' is left at the last line input, or  if
            there  were  none,  at  the  addressed  line. This command
            differs from the a command only in the placement of text.
       
       (.,.+1)j
            The join command joins the specified lines into one  line.
            '.'  is  left  at the new line created by the join. If the
            join  would  result  in  a  line   longer   than   MAXLINE
            characters,  an  error is reported and no changes are made
            to the file. A trailing p or l may be given  on  the  join
            command to cause the merged line to be printed or listed.
       
       (.,.)l
            The list command prints the addressed lines, expanding all
            ASCII characters with values between 1 and 31 (^A - ^_) as
            the  appropriate  two character digraph, ^(character). '.'
            is left at the last line listed.  The  l  command  may  be
            placed  on  the same line after any other command to cause
            listing of the last line affected by the command.
       
       (.,.)m<address>
            The move command repositions the addressed lines after the
            line specified by <address>. The last of the  moved  lines
            becomes the current line.
       
       (.,.)p
            The print command prints the addressed lines.  '.' is left
            at  the  last line printed. The p command may be placed on
            the same line after any other command to cause printing of
            the last line affected by the command.
       
       q
            The quit command causes ed to exit. No automatic write  of
            the file is done. If changes have been made to the current
            file  since the last write command, the user will be asked
            to repeat the quit command.
       
       (.)r filename
            The read  command  reads  in  the  given  file  after  the
            addressed  line.  If no file name is given, the remembered
            file name is used (see e and f commands).  The  remembered
            file  name  is  not changed. Address '0' is legal for this
            command and causes the file to be read in at the beginning
            of the buffer. If the read is successful,  the  number  of
            lines  read is typed. '.' is left at the last line read in
            from the file.
       
       (.,.)s/regular expression/replacement/       or,
       (.,.)s/regular expression/replacement/g
            The substitute command searches each addressed line for an
            occurrence of the specified regular  expression.  On  each
            line  in  which  a match is found, the first occurrence of
            the expression is replaced by the  replacement  specified.
            If  the  global  replacement indicator g appears after the
            command, all occurrences of  the  regular  expression  are
            replaced. Any character other than space or newline may be
            used  instead  of  the  slash  '/'  to delimit the regular
            expression and replacement. A question mark '?' is printed
            if the substitution fails on all addressed lines.  '.'  is
            left at the last line substituted.
            
            An  ampersand '&' appearing in the replacement is replaced
            by  the  string  matching  the  regular  expression.  (The
            special  meaning  of '&' in this context may be suppressed
            by preceding it by '@'.)
            
            Lines may be split or merged by using the symbol  '@n'  to
            stand for the newline character at the end of a line.
       
       
       (1,$)w filename
            The  write  command  writes  the  addressed lines onto the
            given file. If the file does not exist, it is created. The
            remembered file name is not changed. If no  file  name  is
            given,  the  remembered file name is used (see the e and f
            commands). '.'  is  left  unchanged.  If  the  command  is
            successful, the number of lines written is typed.
       
       (1,$)x/regular expression/command
            The  except  command  is  the  same  as the global command
            except that the command is executed for every line  except
            those matching the regular expression.
            
       (.)=
            The  line  number  of  the addressed line is typed. '.' is
            left unchanged.
       
       # comment
            The remainder of the line after the "#" is a  comment  and
            ignored  by  the  editor.   This  allows  ed scripts to be
            commented for future enlightenment.
       
       @shell command
            The remainder of the line after the "@"  is  sent  to  the
            shell  as a command.  If there is nothing else on the line
            but a bare "@", the shell  will  be  spawned,  allowing  a
            number of commands to be performed; when that shell quits,
            the  terminal  is  returned  to  the  editor.  "." is left
            unchanged.
       
       (.+1)<carriage return>
            An address alone on a line causes the addressed line to be
            printed. A blank line alone is  equivalent  to  '.+1'  and
            thus  is  useful  for  stepping  through text. A minus '-'
            followed by a carriage return is equivalent to '.-1'.

                       SUMMARY OF SPECIAL CHARACTERS 
       
       The following are special characters used by the editor:
       
 Character       Usage
 ---------       -----
       
    ?            Matches any character (except newline)
       
    %            Indicates beginning of line
       
    $            Indicates end of line or end of file
       
    [...]        Character class (any one of these characters)
       
    [!...]       Negated character class (any character except these
                 characters)
       
    *            Closure  (zero  or  more  occurrences   of   previous
       pattern)
       
    +            Anchored closure (one or more occurrences)
       
    @            Escaped character (e.g. @%, @[, @*)
       
    &            Ditto, i.e. whatever was matched
       
    c1-c2        Range of characters between c1 and c2
       
    @n           Specifies the newline character at the end of a line
       
    @t           Specifies a tab character
       

FILES
       A  temporary  file  is  used to hold the text being edited. Two
       other temporary files, known as $1  and  $2,  may  be  used  as
       parameters  for  the r, w, and @ commands.  For example, if the
       current date and time are  desired  at  the  top  of  the  text
       buffer, perform the following:
       
            : @date >$1
            : 0r $1
            
       As  another example, if the user wishes to make a copy of lines
       1,5 after the last line in the buffer, do the following:
       
            : 1,5w $1
            : $r $1
            

SEE ALSO
       The Unix command "ed" in the Unix manual 
       The software tools tutorial "Edit"
       "Edit is for Beginners" by David A. Mosher (available from 
             UC Berkeley Computer Science Library) 
       "Edit:  A Tutorial" (also available from the 
             UC Berkeley Computer Science Library) 
       "A Tutorial Introduction to the ED Text Editor" by B. W. Kernighan 
             (UC Berkeley Computer Science Library) 
       Kernighan and Plauger's "Software Tools", pages 163-217 

DIAGNOSTICS
       The error message "?" is printed whenever an edit command fails
       or is not understood.

AUTHORS
       Original code by Kernighan and Plauger  with  modifications  by
       Debbie Scherrer, Dennis Hall and Joe Sventek.

BUGS/DEFICIENCIES
       At  the  present  time  the  editor  is  still  in  a  somewhat
       experimental version. It has not been overlayed yet,  nor  have
       any  real  attempts  been  made  to improve its efficiency. For
       these reasons, the field length needed for  execution  is  high
       and the files being edited are limited to 1000(VMS-5000) lines.
       The  line  limit  applies to all lines read in and subsequently
       changed. For instance, a 600 line file with 401  changed  lines
       would  exceed  ed's  buffer  space.  This problem can be partly
       alleviated by writing (w command) and  re-editing  (e  command)
       the file after a lot of lines have been changed.
       
       There  are several discrepancies between this editor and Unix's
       ed. These include:
       
            1.  Unix uses 'v' instead of 'x' for the except command.
            
            2.  Unix uses '^' instead of '%' for the beginning-of-line
            character.
            
            3.  Unix uses '.' instead of '?' to indicate  a  match  of
            any character.
            
            4.  Unix uses  '^' instead of '!' to indicate exclusion of
            a character class.
            
            5.  Unix uses '\' instead of '@' for the escape character.
            
            6.   Unix  uses  '?'  instead of '\' to delimit a backward
            search pattern.
            
            7.  The Unix 'r' command uses the last line of  the  file,
            instead of the current line, as the default address.
            
            8.   The  Unix  editor  prints  the  number of characters,
            rather than lines read or written when dealing with files.
            
            
       Because of the  nature  of  the  editor's  IO,  it  is  usually
       impossible  to  properly  print  an  altered  line whenever its
       newline character has been deleted or a new one inserted.  Line
       numbering and counts may also become erratic, although the file
       itself  is  actually correct. This problem can be alleviated by
       writing (w command) and re-editing (e command) the  file  after
       tampering with any newline characters.

2 entab
       entab - convert spaces to tabs and spaces

SYNOPSIS
       entab [<t1> ...] [+<n>] [file ...]

DESCRIPTION
       Entab   replaces   strings   of  blanks  with  equivalent  tabs
       (control-i) and blanks. It  can  be  used  to  read  files  and
       produce typewriter-like text, reducing file size. Tab stops are
       indicated by <t1>   ...   (default  8,  16,  ...),  while  +<n>
       indicates tab stops every <n> columns. Thus the command
       
          entab 5 21 +5
       
       would insert tab stops at columns 5, 21, 26, etc. If  no  files
       are  specified,  the  standard input is read. An isolated minus
       sign also indicates the standard input.

SEE ALSO
       detab; lpr

AUTHORS

       Original from Kernighan  &  Plauger's  'Software  Tools',  with
       modifications by Dennis Hall

BUGS
       None to date.

2 exist
       exist - check for the existence of a file

SYNOPSIS
       exist file

DESCRIPTION
       exist  attempts  to  open  the  named  file  at READ access. If
       successful, it closes the file and returns the value  of  1  in
       the  DCL  symbol $STATUS. Common uses are for system-wide login
       files for the invocation of the user's login.com file as in the
       following:

       $ exist:==$sys_tools:exist
       $ exist login.com
       $ if $STATUS.eq.1 then @login

FILES

SEE ALSO

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 expand
       expand - uncompress input files

SYNOPSIS
       expand [file ...]

DESCRIPTION
       Expand  expands  files previously compressed by 'cpress'. If no
       input files are given, or if the filename  '-'  appears,  input
       will be read from the standard input.

FILES

SEE ALSO
       cpress

DIAGNOSTICS
       A message is printed if an input file cannot be opened; further
       processing is terminated.

AUTHORS

       Original  from  Kernighan  &  Plauger's  'Software Tools', with
       minor modifications by Debbie Scherrer.

BUGS

2 fb
       fb - search blocks of lines for text patterns

SYNOPSIS
       fb [-acx] [-ln] [-sexpr [-sexpr]] expr [expr ...]

DESCRIPTION
       "Fb"  (find block) searches blocks or groups of lines in a file
       for text patterns. It is similar to 'find'  except  that  if  a
       pattern  is  found,  the  entire  block  of  lines is copied to
       standard output, rather than  simply  the  line  in  which  the
       pattern  occurred.  Thus  it  is  useful  for searching mailing
       lists, bibliographies, and similar files  where  several  lines
       are grouped together to form cohesive units.
       
       The  search patterns may be any regular expression as described
       in the 'ed' and 'find' writeups.
       
       "Fb" assumes the blocks of lines are separated by an empty line
       or a line containing only blanks. When "fb" is  called  without
       any options, standard input is read and each line is checked to
       see  if  it  matches  any  of  the regular expressions given as
       arguments. If any  matches  are  found,  the  entire  block  is
       printed on standard output.
       
       Other options include:
       
         -a      Only  print  the block if ALL the arguments are found
                 within it
                 
         -x      Only print the block if none  of  the  arguments  are
                 found within it
                 
         -c      Only  print  a  COUNT  of  the number of blocks found
                 which match/don't match the expressions
                 
         -sexpr  Use 'expr' as the block separator (instead of a blank
                 or empty line).  "Expr" can be a  regular  expression
                 just as the search arguments can.
                 
                 If two "-sexpr" arguments are given, the first one is
                 considered  to  be  the  pattern which starts a block
                 (e.g. -ssubroutine) and the second is considered  the
                 pattern which ends a block (e.g. -send).
                 
         -ln     prints  only the first 'n' lines of the block; if the
                 block contains less than  'n'  lines,  the  block  is
                 padded out with blank lines.
       
       Care should  be  taken  when using the characters % $ [ ] ! * @
       and any shell characters in  the  text  pattern.  It  is  often
       necessary to enclose the entire substitution pattern in quotes.

FILES
       A  scratch  file  ("fbt")  is  used if the internal line buffer
       becomes full.

SEE ALSO
       find, ed
       For  a  complete  description  of  regular   expressions,   see
       "Software Tools" pages 135-154.

DIAGNOSTICS
       Error messages are given if:
          a)  One of the patterns given is illegal
          b)  Too many separators are given (2 are allowed)
          c)   The  maximum  number  of expressions is exceeded (9 are
          allowed)
          d)  There are problems opening the scratch  file  (when  the
          block line buffer fills up).
          
       If  the  following  messages  show  up, something is dreadfully
       wrong:
          a)  "Illegal default separator"
          b)  "Block buffer overflow"

AUTHORS
       Debbie Scherrer (Lawrence Berkeley Laboratory)

BUGS
       An expression may not start with a minus sign (-).
       
       Regular expressions can not span line boundaries.

2 fc
        fc - fortran compiler
        
     SYNOPSIS
        
        fc [-c] [-v] [-o] file ...
        
     DESCRIPTION
        
        fc  is  the  fortran compiler callable from the software tools
        shell.  It accepts the following types of arguments:
        
        1. Files whose names end in '.f' are  assumed  to  be  fortran
           source  programs.    They are compiled, and the object file
           is left on a file whose name is that  of  the  source  with
           '.obj' substituted for '.f'.
           
        2. Other  arguments  (except  for the flags listed in 3 below)
           are assumed to be either loader  flags,  or  object  files,
           typically  created  by  an earlier fc run.  These programs,
           together with the results of any compilations,  are  loaded
           (in the order given) to produce an executable program.
           
        3. Three flags which affect the actions of the compiler are:
           
           -c suppress  the  loading  phase,  as  does any compilation
              error in any routine
           -v verbose option; prints name of file as it is compiled at
              the terminal
           -o generates a fortran listing for 'file.f' on 'file.l'
        
     SEE ALSO
        
        rc, the  ratfor  compiler,  which  provides  a  more  pleasant
        programming dialect and environment
        ld,  the  loader, for descriptions of loader flags and process
        naming conventions
        
     AUTHOR
        
        Joe Sventek wrote the interface of fc to the  DEC  Fortran  4+
        compiler.
        
     BUGS
        
        none to date

2 field
   field - manipulate fields of data

SYNOPSIS
   field [-t[c] | fieldlist] outputformat [file ...]

DESCRIPTION
   Feild  is used to manipulate data kept in formatted fields. It
   selects data from certain fields of the input files and copies
   it to certain places in the standard output.
   
   The 'fieldlist' parameter is used to describe the  interesting
   columns  on the input file. Fields are specified by naming the
   columns in which they occur (e.g.  5-10)  or  the  columns  in
   which  they start and an indication of their length (e.g. 3+2,
   meaning a field which starts in column 3 and spans 2 columns).
   When specifying more than one field, separate the  specs  with
   commas (e.g. 5-10,16,72+8) Fields may overlap, and need not be
   in ascending numerical order (e.g. 1-25,10,3 is OK).
   
   If input fields do not fall in certain columns, but rather are
   separated  by  some  character  (such  as a blank or a comma),
   describe the fields by using the  '-tc'  flag,  replacing  'c'
   with  the  appropriate  separator  (a  tab  character  is  the
   default).
   
   Once fields have been described with either the '-tc' flag  or
   a   fieldlist,   they   can  be  arranged  on  output  by  the
   'outputformat' argument. This argument is actually  a  picture
   of  what  the  output line should look like. Fields from input
   are referred to as $1, $2, $3, etc., referring to  the  first,
   second,  third,  etc.  fields  that  were  specified. (Up to 9
   fields are allowed, plus the argument $0 which refers  to  the
   whole  line.) These $n symbols are placed in the output format
   wherever that field  should  appear,  surrounded  by  whatever
   characters desired. For example, an outputformat of:
                             "$2 somewords $1"
   would produce an output line such as:
                           field2 somewords field1
   
   If  no  input  files  are specified, or if the filename '-' is
   found, field will read from the standard input.

DIAGNOSTICS
   illegal field specification
        The  fieldlist  specification  was  in  error,   probably
        because  it  contained  letters  or  some  other  illegal
        characters

SEE ALSO
   sedit

AUTHORS
   David Hanson and friends (U. of Arizona)

2 find
       find - search a file for text patterns

SYNOPSIS
       find [-acx] expr [expr ...]

DESCRIPTION
       find  searches  the  standard input file for lines matching the
       text patterns "expr"  (up  to  9  patterns  may  be  specified)
       according  to the matching criterion specified by the switches.
       (A text pattern is a subset of a "regular expression"--see  the
       writeup   on   "ed"  for  a  complete  description  of  regular
       expressions.)  Unless the -c option is specified, each matching
       line is copied to the standard output.
       
       By default, any line which matches any one of  the  expressions
       is  considered  a  matching line.  If the -a flag is specified,
       only lines  which  match  all  expressions  in  any  order  are
       considered  to  match.   If the -x flag is specified, all lines
       which don't satisfy the above criteria are considered  matching
       lines.   And  finally,  if the -c option is specified, matching
       lines are counted instead  of  being  copied  to  the  standard
       output, and the final count is written to the standard output.
       
       A text pattern consists of the following elements:
       
       c      literal character 
       ?      any character except newline 
       %      beginning of line 
       $      end of line (null string before newline) 
       [...]  character class (any one of these characters) 
       [!...] negated character class (all but these characters) 
       *      closure (zero or more occurrences of previous pattern) 
       +      anchored closure (one or more occurrences of previous pattern)
       @c     escaped character (e.g., @%, @[, @*) 
       
       Any  special  meaning  of  characters in a text pattern is lost
       when escaped, inside [...], or for:
       
       %         not at beginning 
       $         not at end 
       *         at beginning 
       +         at beginning 
       
       A character class consists of zero or  more  of  the  following
       elements, surrounded by [ and ]:
       
       c         literal character, including [ 
       a-b       range of characters (digits, lower or upper case) 
       !         negated character class if at beginning 
       @c        escaped character (@! @- @@ @]) 

       Special meaning of characters in a character class is lost when
       escaped or for
       
       !         not at beginning 
       -         at beginning or end 
       
       An  escape  sequence  consists of the character @ followed by a
       single character:
       
       @n        newline 
       @t        tab 
       @c        c (including @@) 
       
       For a complete description, see "Software Tools" pages 135-154.
       Care should be taken when using the characters % $ [ ] ! * +  @
       and  any  shell  characters  in  the  text pattern. It is often
       necessary to enclose the entire substitution pattern in quotes.

FILES
       None

SEE ALSO
       tr, ed, ch and the UNIX grep command.

DIAGNOSTICS
       An error message is printed if one of  the  patterns  given  is
       illegal.

AUTHORS
       Originally  from  Kernighan  & Plauger's "Software Tools", with
       major modifications by Joe Sventek.

BUGS
       An expression may not start with a minus sign(-).
       
       A very complex escape scheme must be used  when  not  operating
       inside  the shell on BKY.  This is because BKY only accepts the
       CDC character set in command arguments (see /*/doc/guide).

2 form
       FORM -- produces form letter by prompting user for information

SYNOPSIS
       form [-c] [+c] [file ...]

DESCRIPTION
       
       Form  reads input files and writes them to the standard output.
       Any time it encounters  some  characters  surrounded  by  angle
       brackets  ('<'  and  '>')  it  prints  the  string  between the
       characters as a prompt to the user.  It  then  reads  from  the
       standard  input and replaces the bracketed string with what was
       read.
       
       Normally only one line of input is accepted from  the  standard
       input.   However,  a  response  can  be continued on succeeding
       lines by terminating each line to be continued with  an  atsign
       ('@').
       
       The prompts inside the file may also span line boundaries if so
       desired (no atsign is needed in this case).
       
       The  user's  answers  to  prompts  are remembered, so duplicate
       prompts are replaced without repeating the prompt to the user.
       
       If the standard input is not a terminal, no prompts are issued.
       
       The '-c' flag may  be  used  to  reset  the  initial  character
       signalling a prompt. The character 'c' then replaces the '<'.
       
       The '+c' flag may be used to reset the terminating character of
       a prompt. The character 'c' then replaces '>'.

FILES
       The user's terminal is opened both at READ and at WRITE access.

SEE ALSO
       The Unix form-letter tool

DIAGNOSTICS
       If  an  input  file  cannot be opened, a message is printed and
       execution is terminated.
       
       A message is also printed if either the prompt or the  response
       is too long for the tool's internal buffer.
       

AUTHORS

       Debbie Scherrer

BUGS

2 incl
       incl - expand included files

SYNOPSIS
       incl [file] ...

DESCRIPTION
       Include   copies  the  input  files  to  the  standard  output.
       Whenever an input line begins with
       
                              include filename 
       
       the entire contents of filename will be copied to the  standard
       output.  If no input files are specified, the standard input is
       copied. An included file may include further includes. Multiple
       input files are allowed. Include is used to bring in  much-used
       routines, common declarations or definitions, thus insuring use
       of the same version by all programs.

FILES
       none

SEE ALSO
       Kernighan and Plauger's "Software Tools", pages 74-77.
       The software tools "ratfor" tutorial

DIAGNOSTICS
       includes nested too deeply
             The depth of included files allowed is dependent upon the
             maximum  number  of  open files allowed.  It is generally
             MAXFILES - 4.
       filename:  can't open
             File could not be located or  maximum  number  of  opened
             files was exceeded.

AUTHORS
       Original  code  by  Kernighan  and Plauger in "Software Tools",
       with modifications by Ardith Kenney.

BUGS/DEFICIENCIES
       The depth of included  files  allowed  is  dependent  upon  the
       maximum  number of open files allowed by the implementor of the
       primitives.

2 intro
       intro - list on-line documentation

SYNOPSIS
       intro

DESCRIPTION
       Intro  lists  the tools for which user documents are available.
       These documents can then be accessed via the tool 'man'.

FILES
       Currently, this tool  is  implemented  as  a  script  file.  It
       accesses the archive file containing the user documentation.

SEE ALSO
       man; the Unix tool 'help'

DIAGNOSTICS
       None

AUTHORS

       Dennis Hall

BUGS

2 isam
       isam - generate index for pseudo-indexed-sequential access

SYNOPSIS
       isam [-d<dif>] [-w<width>] [-j<l/r>]

DESCRIPTION
       isam is used to generate an index for a text file such that the
       index  may be used later to permit indexed-sequential access to
       the file. isam reads every `dif'th line (default is 1) from the
       standard input, noting its disk address with a call  to  markl.
       It  uses  getwrd to retrieve the first "word" from the line and
       uses this as the primary key to the record.  This key  is  then
       output  to  standard output in a field `width' wide (default is
       25) and justified according to the -j  switch  (default  left).
       The  two-word  address  from  markl  is  then output as decimal
       integers before the index record is flushed.

FILES

SEE ALSO
       spell - spelling error finder; uses an isam-generated index

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 kill
       kill - kill a running process

SYNOPSIS
       kill processid [processid ...]

DESCRIPTION
       KILL  kills  the  processes specified by the processid's in the
       command line.  The processid's are those provided by the  shell
       when it spawns a background process.

FILES
       None

SEE ALSO
       sh - shell (command line interpreter)

DIAGNOSTICS
       if  the  process  specified by the processid does not exist, an
       error message will be displayed on error output.

AUTHOR
       Joe Sventek (VAX)

BUGS/DEFICIENCIES
       

2 kwic
       kwic - make keyword in context index

SYNOPSIS
       kwic [file ...]

DESCRIPTION
       Kwic  rotates  lines  from the input files so that each word in
       the sentence appears at the beginning of a line, with a special
       character marking the original position of the end of the line.
       The output from kwic is typically sorted with 'sort'  and  then
       unrotated with 'unrot' to produce a keyword-in-context index.
       
       If  no  input  files are given, or if the filename '-' appears,
       lines will be read from standard input.

FILES

SEE ALSO
       unrot; sort

DIAGNOSTICS
       A message is printed if an input file cannot be opened; further
       processing is terminated.

AUTHORS

       Original from Kernighan and Plauger's  'Software  Tools',  with
       modifications by Debbie Scherrer.

BUGS

2 lam
   lam - laminate files

SYNOPSIS
   lam -string | files...

DESCRIPTION
   Lam laminates the named files to the standard output. That is,
   the first output line is the result of concatenating the first
   lines  of  each  file,  and  so on. If the files are different
   lengths, null lines are used for  the  missing  lines  in  the
   shorter files.

   The  "-string"  arguments  are  used  to place strings in each
   output line.  Each "string" is placed in the output  lines  at
   the point it appears in the argument list.  For example,

      lam -file1: foo1 "-, file2:" foo2

   results in output lines that look like

      file1: a line from foo1, file2: a line from foo2

   The  escape sequences described in find (and change) are valid
   in "string" arguments.  Thus

      lam foo1 -@n foo2

   results in the lines from foo1 and foo2 being interleaved.

   Files and string specifications may appear in any order in the
   argument list.

   If no file  arguments  are  given,  or  if  the  file  "-"  is
   specified, lam reads the standard input.

FILES
   None

SEE ALSO
   comm, tail

DIAGNOSTICS
   too many arguments
      The  maximum  number  of command line arguments allowed has
      been exceeded. It is set by the MAXARGS definition  in  the
      source code.

   too many strings
      The max number of characters in a string has been exceeded.
      It is set by the MAXBUF definition in the source code.

   output buffer exceeded
      The size of the output line buffer has been exceeded. It is
      set by the MAXOBUF definition in the source code.

AUTHORS
   David Hanson and friends (U. of Arizona)

BUGS/DEFICIENCES

2 lcnt
       lcnt - line count

SYNOPSIS
       lcnt [file ...]

DESCRIPTION
       Lcnt  counts  the  number  of  lines of text in the named input
       files, or the standard input if  no  files  are  given  or  the
       filename  '-'  appears.  A  line  is  zero  or  more characters
       terminated by a NEWLINE marker.
       
       Lcnt could also be implemented as a shell script file:
       
                               tr '!@n' | ccnt

FILES

SEE ALSO
       ccnt; wcnt; the Unix command 'wc'

DIAGNOSTICS
       A message is printed if an input  file  could  not  be  opened;
       processing is terminated.

AUTHORS

       Original  from  Kernighan  and Plauger's 'Software Tools', with
       modifications by Debbie Scherrer.

BUGS

2 ld
        ld - loader
        
     SYNOPSIS
        
        ld [-l[libname]] [-ptaskname] name ...
        
     DESCRIPTION
        
        ld  links  together  the  named  modules  in  the order given,
        searches the system libraries to resolve global references and
        generates an executable process.
        
        ld understands two flags:
        
        -l signifies that the filename concatenated to the flag  is  a
           library  name.   -l  alone  stands  for  the  ratfor system
           library, rlib.  The default extension for a library file is
           '.olb'.   A  library  is  searched   when   its   name   is
           encountered, so the placement of -l is significant.  If the
           ratfor  system  library  is not explicitly mentioned, it is
           searched after all  other  files  have  been  linked.   The
           fortran system library is searched at the very end.
           
        -p signifies that the file name concatenated to the flag is to
           be  the process name.  If this option is not specified, the
           process name is determined in one of two ways:
           
           1. The first non-library file name (eg. roff.o)  is  found,
              and   the   file's   extension  is  replaced  by  '.tsk'
              (roff.tsk).  This is then the resulting process name.
              
           2. Failing  1  (implying  that  all  files  listed  in  the
              argument  list  are  libraries),  the  process  image is
              placed on  the  file  a.out,  overwriting  the  previous
              contents of that file.
              
     AUTHOR
        
        Joe Sventek wrote the interface of ld to the DEC task builder.
        
     BUGS
        
        The creation of the process on a.out is not yet implemented.

2 list
   list - directory lister for structure level II directories
   
SYNOPSIS
   
   list [-1drtv] [pathname] ...
   
DESCRIPTION
   
   list  is  an optimized version of ls for ODS-2 directories.  A
   further restriction on list is that  the  directory  arguments
   must  be  in  pathname format, as opposed to ls, which permits
   DEC filespecs as well as the path equivalent.  The writeup for
   ls may be consulted for the meanings of the switches.
   
FILES
   
   
AUTHOR
   
   list was originally written by Joe Sventek,  with  substantial
   enhancements by Dave Martin.
   
SEE ALSO
   
   ls - portable directory lister

2 ll
   ll - print line lengths

SYNOPSIS
   ll files...

DESCRIPTION
   Ll prints the lengths of the shortest and longest lines in the
   named  files.   The  name  "-"  may  be  used  to refer to the
   standard input.  If no files are given, ll reads the  standard
   input.
   
   NEWLINE  characters are not counted as part of the length of a
   line.

FILES
   None

DIAGNOSTICS
   A message is issued if a named file could not be opened.

AUTHORS
   David Hanson and friends (U. of Arizona)

2 lpr
       lpr - queue file to printer

SYNOPSIS
       lpr [-n] [-l] [-v] [-c<num of copies>] [file]...

DESCRIPTION
       lpr  takes  the  named  files  (or  standard  input if none are
       specified) and queues copies  of  them  to  the  printer.   All
       overstriking  and  underlining in the documents which have been
       achieved  via  backspaces  are  converted  to  the  appropriate
       overstrike  lines  to drive the printer.  The switches have the
       following meaning:

         -n narrow paper queue.  These files are queued to the printer
            with forms=1.
         -l label queue.  These files are queued to the  printer  with
            forms=6.
         -v verbose.   The  job  number  of  the  print  job  will  be
            displayed on the screen at the successful queueing of  the
            file.
        -cn number  of copies.  The number of copies of the file to be
            queued may be specified this way.  The default is 1 copy.

       The default  behavior  of  lpr  is  to  queue  the  files  with
       forms=0.   In  all cases, the print queue to which the symbiont
       messages are directed is sys$print.  If  you  do  not  maintain
       this  queue,  you  will have to modify the source code for lpr.
       The routine to change is lpr.w/lpr.r/dispoz.q.

FILES

SEE ALSO

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 ls
        ls - list contents of directory
        
     SYNOPSIS
        
        ls [-1dnrtv] [pathname] ...
        
     DESCRIPTION
        
        ls  lists  information  about  each  file  argument.   When no
        argument is given, the default directory is listed.  The  file
        arguments  may  include  any  of the legal regular expressions
        described in the man entry for  the  editor,  with  the  added
        feature  that  the  comparisons  will  be case insensitive. By
        default, the files are listed in the order in which  they  are
        found in the directory.  There are six options:
        
        -1 force single column output to the terminal.  The default is
           multi-column output to the terminal, single to a disk file.
        -h print a header at the top of verbose listings
        -n sort the directory by name
        -v list in verbose format
        -t sort by time modified (oldest first)
        -r reverse the sense of the sort
           
        As an example of usage of ls, the following command will cause
        all  of the files which contain the string tst anywhere in the
        file name to be deleted:
        
           % ls tst | args rm
        
     FILES
        
        lstemp1, lstemp2
        
     AUTHOR
        
        Joe Sventek wrote ls.
        
     SEE ALSO
        
        ed - text editor for description of regular expressions
        args - argument exploder

2 macro
       macro - process macro definitions

SYNOPSIS
       macro [file] ...

DESCRIPTION
       Macro  reads  the  source  file(s) and writes onto the standard
       output a new file with the macro definitions  deleted  and  the
       macro references expanded.  If no file names are specified, the
       standard input is read.
       
       Macros are generally used to extend some underlying language to
       perform  a translation from one language to another; that is, a
       macro processor allows one to define symbolic constants so that
       subsequent occurrences of the  constant  are  replaced  by  the
       defining string of characters. The general format is:
       
                       define(name,replacement text) 
       
       All  subsequent  occurrences  of  "name"  in  the  file will be
       replaced by "replacement text".  Blanks are significant and may
       occur only inside the replacement text. Upper  and  lower  case
       letters   are  also  significant.  Nesting  of  definitions  is
       allowed, as is recursion. The definition may be more  than  one
       line long.
       
       An elementary example of a macro is:
       
                               define(EOF,-1) 
       
       Thereafter,  all  occurrences  of  "EOF"  in  the file would be
       replaced by "-1".
       
       Macros with arguments may also be specified.  Any occurrence in
       the replacement text of "$n", where n is between 1 and 9,  will
       be  replaced  by  the  nth  argument when the macro is actually
       called.  For example,
       
                define(copen,$3 = open($1,$2)
                             if ($3 == ERR)
                                  call cant($1))
       
       would define a macro which, when called by  "copen(name,  READ,
       fd)" would expand into:
       
                fd = open(name,READ)
                if (fd == ERR)
                     call cant(name)
       
       If  a  macro  definition  asks  for  an  argument  that  wasn't
       supplied, the "$n" will be ignored.
       
       Macros  can  be  nested,  and  any  macros  encountered  during
       argument  collection  are expanded immediately--unless they are
       surrounded by brackets "[]".  That is, any input surrounded  by
       [ and  ]  is  left absolutely alone, except that one level of [
       and ] is stripped off. Thus it is possible to write  the  macro
       "d" as
       
                         define(d,[define($1,$2)]) 
       
       The  replacement  text  for  "d",  protected by the brackets is
       literally "define($1,$2)" so one could say
       
                                  d(a,bc) 
       
       and be assured that "a" would be defined to be  "bc".  Brackets
       must also be used when it is desired to redefine an identifier:
       
                                define(x,y) 
                                define(x,z) 
       
       would define "y" in the second line, instead of redefining "x".
       To avoid redefining "y", the operation must be expressed as
       
                                 define(x,y)
                                 define([x],z)
       
       The  macro processor also includes a conditional test, with the
       built-in function "ifelse".  The input
       
                              ifelse(a,b,c,d) 
       
       compares "a" and "b" as character strings.   If  they  are  the
       same, "c" is pushed back onto the input; if they differ, "d" is
       pushed back.  As a simple example,
       
                   define(compare,[ifelse($1,$2,yes,no)]) 
       
       defines  "compare"  as  a two-argument macro returning "yes" if
       its arguments are the same, and  "no"  if  they  are  not.  The
       brackets prevent the "ifelse" from being evaluated too soon.
       
       Another  built-in  function  available  is  "incr".   "incr(x)"
       converts the string "x" to  a  number,  adds  one  to  it,  and
       returns  that  as its replacement text (as a character string).
       "x" had better be numeric, or the results may be  undesireable.
       "incr" can be used for tasks like
       
                   define(MAXCARD,80)
                   define(MAXLINE,[incr(MAXCARD)])

       which makes two parameters with values 80 and 81.
       
       The third built-in function available in the macro processor is
       a function to take substrings of strings.
       
                              substr(s, m, n) 
       
       produces  the  substring  of  "s"  which starts at position "m"
       (with origin one), of length "n".  If "n"  is  omitted  or  too
       big,  the  rest  of  the string is used, while if "m" is out of
       range the result is a null string. For example,
       
                             substr(abc, 2, 1) 
       
       results in "b",
       
                               substr(abc, 2) 
       
       results in "bc", and
       
                               substr(abc,4) 
       
       is empty.
       
       
       The last built-in function available in the macro processor  is
       one to perform simple arithmetic functions:
       
                         arith(operand1,op,operand2)
       
       where  the  operation  specified  by  'op'  may  be  + (add), -
       (subtract), * (multiply), or / (divide). Negative  numbers  are
       not handled yet. Thus,
       
                           define(add,[arith($1,+,$2)])
                           add(5,3)
       
       would produce the result '8'.
       
       As  a  final example, here is a macro which computes the length
       of a character string:
       
           define(len,[ifelse($1,,0,[incr(len(substr($1,2)))])]) 
       
       Note the recursion, which is perfectly permissible.  The  outer
       layer  of brackets prevents all evaluation as the definition is
       being copied into an internal table.  The inner layer  prevents
       the "incr" construction from being done as the arguments of the
       "ifelse"  are  collected.  The value of a macro call "len(abc)"
       would be 3.

FILES
       None

SEE ALSO
       Kernighan and Plauger's "Software Tools", pages 251-283 

DIAGNOSTICS
       arg stack overflow
           The maximum number of total arguments  has  been  exceeded.
           Currently this is 100.
           
       call stack overflow
           The  maximum  level  of  nesting  of  definitions  has been
           exceeded. Currently this is 130.
           
       EOF in string
           An end-of-file has  been  encountered  before  a  bracketed
           string has been terminated.
           
       evaluation stack overflow
           The  total  number  of characters for name, definition, and
           arguments has been exceeded.  Currently this is 500.
           
       unexpected EOF
           An end-of-file was reached before the macro definition  was
           terminated.
           
       filename: cant open
           For  some  reason,  the file specified could not be opened.
           This is an unlikely error to occur; if it does show  up  it
           probably  indicates a problem with the low-level primitives
           being used by the system.

AUTHORS
       From "Software Tools" by  Kernighan  and  Plauger,  with  minor
       modifications by Debbie Scherrer.

BUGS/DEFICIENCIES
       There   can   be   no   space  between  the  "define"  and  the
       left-parenthesis following it.
       
       Keywords (e.g. define, ifelse, etc.) in the input file must  be
       surrounded   by   brackets   if   they   are   not  part  of  a
       macro--otherwise they will be stripped out  by  the  processor.
       Likewise,  if  brackets  are desired anywhere in the input file
       other than in a macro, they  must  be  surrounded  by  brackets
       themselves.
       
       The  error  messages  generated  by  the  ratfor  compiler when
       processing macros do not seem to show  up  in  this  processor.
       Examples  are "definition too long", "missing comma in define",
       and "non-alphanumeric name".

2 mail
        mail - utility for sending mail to local users
        
     SYNOPSIS
        
        mail [+r] [+e] [+llistfile] ... [addressee] ...
        
     DESCRIPTION
        
        mail  is  a  tool  designed  to allow the user to send mail to
        fellow users of any system which supports the  software  tools
        shell.  It operates as follows:
        
             The addressees specified in the command line and in any
             mailing  list  files specified are validated.  If there
             were any valid users, the standard input is read up  to
             an  end-of-file and then mailed to each valid user with
             an  appropriate  postmark.  (Note:  if  one  wishes  to
             terminate  the  mail  session without sending any mail,
             type a line consisting of only the letter q [for  quit]
             during  the  input  of  mail.)  Mailing  list files are
             specified with the +l switch in the command line.   The
             structure  of  the  mailing  list  files  is  described
             below.  The +r switch indicates to mail that  the  user
             wishes  to  be  notified  as the mail is posted to each
             addressee ('posted' implying that  the  mail  has  been
             appended  successfully  to  the addressee's mail file).
             The names of valid  users  may  be  obtained  by  prior
             invocation  of  the  users  command.   The +e flag will
             cause the editor "ed" to be invoked, allowing the  user
             to perform complex mail composition.

        The  mailing  list  files  have  a very simple structure: user
        names separated by blanks and tabs, with  as  many  users  per
        line  as  desired.   A  pound sign (#) appearing anywhere on a
        line indicates the start of a comment field, and the  rest  of
        the  line  is  ignored by mail.  This allows the user complete
        flexibility  in   commenting   her/his   mailing   lists   for
        informational purposes.

        Broadcast  mailings  are  supported,  also.   One  must merely
        specify all as an addressee in the command line.

     FILES

        mymail - file for storage of each users mail
        mbox - file for storage of saved mail
        three temporary files are used by mail

     SEE ALSO

        users - a program to list users on current host
        postmn - a program which notifies user of existence of mail
        msg - the utility for reading and sorting one's mail

     AUTHOR

        mail was written by Joe Sventek

     BUGS/DEFICIENCIES

2 malfix
       malfix - fix up old mail files for MSG

SYNOPSIS
       malfix <infile >outfile

DESCRIPTION
       malfix exists solely to convert mail files created with the old
       software  tools mail utility into the format necessary for MSG.
       The suggested scenario for fixing up your mbox file (the  place
       where MAIL used to save your mail) is as follows:

            cat mymail >>mbox
            cat ~bin/mymail >mymail
            rename mbox. ombox.
            malfix <ombox >mbox

       Now  run  MSG  on the mbox file to make sure everything went OK
       (of course it did, but let's be safe.)  Then the ombox file may
       be deleted.

FILES

SEE ALSO
       msg - message file editor

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 man
       man - run off section of users manual

SYNOPSIS
       man [toolname] ...

DESCRIPTION
       Man locates and prints a section of the users manual describing
       the  use  of  a particular tool. If no arguments are specified,
       all of manual entries are printed out.

FILES
       Accesses the file containing user documents.

SEE ALSO
       The tool 'intro'; the Unix command 'man'

DIAGNOSTICS
       A message is printed if the tool specified by 'toolname' cannot
       be located.

AUTHORS

       Dennis Hall

2 mcol
   mcol - multicolumn formatting

SYNOPSIS
   mcol [-cn] [-ln] [-wn] [-gn] [-dn] [file ...]

DESCRIPTION
   Mcol  reads  the named files and formats them into multicolumn
   output on the standard output. If the filename "-"  is  given,
   or no files are specified, the standard input is read.
   
   The options are as follows.

   -cn  Format the output into "n" columns.  Default is 2.

   -ln  Set  the  output  page  size  to  "n".  Mcol produces its
        output in pages, but does not  place  separators  between
        the   pages   on  the  assumption  that  some  subsequent
        processor will do that. (The default page length is 55.)

   -wn  Set the column width to  "n"  characters.   Lines  longer
        than  "n"  characters  are truncated. (The default column
        width is 60.)

   -gn  Set the "gutter" width to "n".  The gutter is  the  white
        space between columns. (The default gutter width is 8.)

   -dn  Assume  output  is  to  be printed on a display terminal.
        The column size is set to "n"  characters  and  the  page
        size  is  set  to  24  lines.   The number of columns and
        gutter width are  computed  to  maximize  the  amount  of
        information  on a single screen. If "n" is omitted, 10 is
        used, which is useful for displaying lists of file names.

FILES
   None

SEE ALSO

DIAGNOSTICS
   invalid column count
   invalid page size
   invalid column width
   invalid gutter width
      The value of one of the option flags is invalid or  exceeds
      the limitations of mcol.

   ignoring invalid flag
      A  command argument option flag was given which mcol didn't
      recognize.

   insufficient buffer space
      Mcol could not buffer an entire page.  This is usually  the
      result  of  options  that specify a large page size or many
      columns. The buffer size is set by the MAXBUF definition in
      the source code.

   too many lines
      The number of lines per page times the  number  of  columns
      exceeded  mcol's  line  buffer space. The maximum number of
      lines allowed is set by the MAXPTR definition in the source
      code.

BUGS/DEFICIENCIES

AUTHORS
   Original by David Hanson and friends  (U.  of  Arizona),  with
   modifications by Debbie Scherrer (LBL).

2 msg
        MSG - utility for manipulating message files
        
     SYNOPSIS
        
        msg [-f[n]] [-p[n]] [file]
        
     DESCRIPTION
        
        MSG  is a message file editor.  The message files which it can work
        on are those used by the utility SNDMSG, as well as  files  created
        by  MSG.   There are two files in a user's home directory which are
        used by SNDMSG and MSG -  mymail  and  mbox.   If  MSG  is  invoked
        without  a  file argument, MSG will initially read mymail.  mbox is
        the file where the messages from mymail are saved by default.   The
        -f  switch  is used to change the number of fill characters written
        to  the  terminal  whenever  a  carriage-return,line-feed  pair  is
        written.  The -p switch can be used to change the page size (number
        of  lines  per  screenful)  for  MSG  to  use  when displaying long
        output.  The default is 22 lines.
        
        A primer is available, and may be  had  by  the  execution  of  the
        following shell script:
        
        % msgprim
        
        This  will  cause  a copy of the primer to be displayed on standard
        output.  In order to obtain the  test  message  file  used  in  the
        primer, execution of the following shell script:
        
        % msgtest
        
        will  cause  the test message file to be copied to standard output.
        In order to run the test yourself,  the  following  shell  commands
        should suffice
        
        % msgtest >test.msg ; msg test.msg
        
     FILES

        mymail - messages sent using the SNDMSG utility reside here.
        mbox - default file for saving messages from mymail.
        one scratch file is used by MSG.

     SEE ALSO

        SNDMSG - the utility for sending mail to other users
        msplit - the utility for salvaging message files

     AUTHOR
        MSG was written by Joe Sventek

     BUGS/DEFICIENCIES

2 msplit
        msplit - utility for salvaging message files
        
     SYNOPSIS
        
        msplit <file [-v] [root]
        
     DESCRIPTION
        
        msplit  reads  the  standard  input file, which presumably has more
        messages on it than msg can handle, and splits  it  up  into  files
        which  contain  a  fixed number of messages.  The files created are
        named rootaa, rootab, ..., where root defaults to "tmsg" if none is
        specified on the command line.   If  the  -v  (verbose)  option  is
        selected,  then  the name of each file is displayed on ERROUT as it
        is  created.   The  user  should  immediately  use  msg  on   these
        temporaries  to  place  the  messages  in  appropriate  files.   In
        particular, the input file to msplit should be  overwritten,  since
        it is too large already.
        
     FILES

        none

     SEE ALSO

        msg - the utility for reading and sorting one's mail

     AUTHOR

        msplit was written by Joe Sventek

     BUGS/DEFICIENCIES

2 mv
       mv - move (or rename) a file

SYNOPSIS
       mv file1 file2

DESCRIPTION
       Mv changes the name of file1 to file2. If file2 already exists,
       it  is  removed  before  file1 is renamed. On networks or other
       systems where a simple rename is impossible, mv copies the file
       and then deletes the original.

FILES
       None

SEE ALSO
       The Unix command 'mv'

DIAGNOSTICS
       A message is printed if file1 does not exist.

AUTHORS

       Joe Sventek, Debbie Scherrer

BUGS

2 os
       os - overstrike - convert backspaces into multiple lines

SYNOPSIS
       os [file ...]

DESCRIPTION
       Os (overstrike) looks for backspaces in the files specified and
       generates a sequence of print lines with carriage control codes
       to reproduce the effect of the backspaces.
       
       If  no  files  are given, or the filename '-' appears, input is
       taken from the standard input.

FILES

SEE ALSO
       lpr

DIAGNOSTICS
       A message is printed if an input file cannot be opened; further
       processing is terminated.

AUTHORS

       Original from Kernighan  &  Plauger's  'Software  Tools',  with
       modifications by Debbie Scherrer.

BUGS

2 pack
       pack - pack words into columns

SYNOPSIS
       pack

DESCRIPTION
       pack  takes the words (groups of characters separated by blanks
       or tabs) found on  the  standard  input  and  outputs  them  to
       standard  output  in five columns, 16 spaces wide, ordered from
       left to right.  The characters used to achieve  the  separation
       of  columns are TAB characters, such that those terminals which
       support hardware tabs can be driven efficiently.

FILES

SEE ALSO

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 pl
   pl - print specified lines/pages in a file

SYNOPSIS
   pl [-pn] numbers [file ...]

DESCRIPTION
   Pl  prints the specified lines from each of the named files on
   the standard output.  If no files are given, or  if  the  name
   "-" is specified, pl reads the standard input.

   The  "numbers" argument is a list of line numbers separated by
   commas, e.g.

      pl 4,5,26,55 foo bazrat

   prints lines 4, 5, 26, and 55 in file "foo" and "bazrat".  The
   line numbers may be given in any order. Repeated numbers cause
   the specified lines to be printed once for each occurrence  of
   the  line  number.  Line number ranges can also be given, e.g.
   4-15.

   The "-p" option causes pl to print pages instead of lines, and
   the numbers refer to page numbers.  If an integer follows  the
   "-p",  it  is  taken  as  the  page  size;  the default is 23.
   Repeated numbers cause the specified pages to be printed  once
   for each occurrence of the page number.

DIAGNOSTICS
   bad page size
        Invalid page size specified after '-p' flag
   bad number
        Invalid number given as argument
   bad range
        Invalid range given as argument
   too many numbers
        Number  of  lines/pages  specified overflowed the buffer.
        Maximum number of lines is  determined  by  the  MAXLINES
        definition in the source code.
   ignoring invalid argument
        An invalid flag was specified.   Processing continues.

AUTHORS
   David Hanson and friends (U. of Arizona)

BUGS/DEFICIENCIES
   There  is  a limit to the size of pages which can be buffered.
   This is set by the MAXBUF definition in the source code.

2 postmn
        postmn - report the presence of mail
        
     SYNOPSIS
        
        postmn
        
     DESCRIPTION
        
        postmn looks to see if the requestor has received any mail.  If so,
        it reports that fact upon the standard output file with the comment
        "You have new mail".
        
     FILES
        
        Uses the file address in the mail directory to determine the user's
        home directory.
        
     SEE ALSO
        
        mail - utility for sending mail
        msg - utility for reading and filing mail
        resolve - utility for querying the mail database about users
        users - utility for listing valid mail users
        
     AUTHOR
        
        postmn was written by Joe Sventek
        
     BUGS/DEFICIENCIES

2 pr
   print - paginate files to standard output

SYNOPSIS
   pr [-ln] [file ...]

DESCRIPTION
   Pr  paginates the named files to standard output. Each file is
   printed as a sequence of pages.  Each page is 66  lines  long,
   including  a  6-line  header  and  3-line  footer.  The header
   includes the file  name,  possibly  the  date,  and  the  page
   number.
   
   If  the file '-' is specified, or no file names are given, the
   standard input is read.
   
   Option flags include:
         -ln   Sets the page length to 'n'. Default  page  length
              is 66.

SEE ALSO
   os, detab, mcol, format, cat

DIAGNOSTICS
   ignoring invalid argument
      An option flag was specified which pr did not understand
      
   A message is printed if an input file could not be opened

AUTHORS
   Original  from  the  Kernighan-Plauger  'Software Tools' book,
   with modifications by David Hanson and friends (U. of Arizona)
   and Debbie Scherrer (LBL)

BUGS/DEFICIENCES
   The header and trailer spacing can be  modified  by  adjusting
   the  MARGIN1,  MARGIN2,  and BMARGIN definitions in the source
   code.

2 ps
       ps - list process status information

SYNOPSIS
       ps [-ax] [-tttname] [-uusername]

DESCRIPTION
       ps  lists  information concerning processes in the system.  The
       processes are listed in order by process  id,  with  all  child
       processes  appearing  in  heirarchical  order immediately below
       their respective parents.  The default is to list all processes
       active at the invoking  terminal.   The  switches  cause  other
       information to be displayed as follows:

           -a list information on processes associated with all logged
              in terminals on the system
           -x list information on all processes in the system
       -tname list   information  on  all  processes  associated  with
              terminals which contain the pattern `name'.
       -uname list information on all processes owned by  users  whose
              names contain the pattern `name'.

       The display consists of the following information:

         1. The terminal name
         2. The owning user name
         3. The process name
         4. The process id
         5. The total elapsed CPU time of the process
         6. The  de-noised  image  name which the process is running -
            i.e. all of the device and directory information, as  well
            as  the  extension  and  version number have been removed.
            This field being  blank  indicates  that  the  process  is
            running DCL and the user is thinking.

FILES

SEE ALSO
       who - who is on the system

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 pstat
       pstat - determine status of process

SYNOPSIS
       pstat processid [processid ...]

DESCRIPTION
       PSTAT  determines  the  status  of  processes  specified by the
       processid's in the command line.  It returns either  active  or
       completed for each process.  The processid's are those returned
       by the shell when a background process is spawned.

FILES
       None

SEE ALSO
       sh - shell (command line interpreter)

DIAGNOSTICS
       

AUTHOR
       Joe Sventek (VAX)

BUGS/DEFICIENCIES
       

2 pwd
       pwd - print working directory name on standard output

SYNOPSIS

       pwd [-l]

DESCRIPTION

       pwd  prints  the  pathname  of  the  working  (current default)
       directory. If the -l switch is  present,  the  current  working
       directory  is printed out in the local parlance. This path name
       is of the form

       /device/directory

       For example,

                                 /dp00/105,1

       is equivalent to

                                dp00:[105,1]

       on RSX and IAS machines.

SEE ALSO

       cwd - change working directory

2 rat4
       rat4 - Ratfor preprocessor

SYNOPSIS
       rat4 [files ...] >outfile

DESCRIPTION
       rat4  translates  the  ratfor  programs in the named files
       into Fortran. If no input files are given, or the filename
       '-' appears, the standard input will be read.
       
       A  file  containing   general   purpose   software   tools
       definitions   (e.g.  EOF,  NEWLINE,  EOS,  etc.)  will  be
       automatically opened and processed before any of the files
       specified are read.

       Syntax:
       
       Ratfor has the following syntax:
           prog:   stmt
                   prog stmt
           stmt:   if (expr) stmt
                   if (expr) stmt else stmt
                   while (expr) stmt
                   repeat (expr) stmt
                   repeat stmt until (expr)
                   for (init expr; test expr; incr expr) stmt
                   do expr stmt
                   do n expr stmt
                   break
                   break n
                   next
                   next n
                   return (expr)
                   switch (expr)
                     {
                     case expr:  stmt
                     ....
                     default: stmt
                     }
                   digits stmt
                   { prog }  or  [ prog ]
                   anything unrecognizable (i.e. fortran)
       
       where  'stmt'  is  any  Fortran  or  Ratfor  statement.  A
       statement is terminated by an end-of-line or a semicolon.

       Character Translation:

       The following character translations are performed:
            <       .lt.
            <=      .le.
            ==      .eq.
            !=      .ne.         ^=      .ne.         ~=      .ne.
            >=      .ge.
            >       .gt.
            |       .or.
            &       .and.
            !       .not.        ^       .not.        ~       .not.

       Included files:
       
       The statement
       
                      include file        or
                      include "file"
       
       will  insert  the  contents of the specified file into the
       ratfor input in place of the 'include'  statement.  Quotes
       must  surround  the  file  name  if it contains characters
       other than alphanumerics, underscores, or dots.

       Macro Definitions:
       
       The statement
       
                      define(name,replacement text)
       
       defines 'name' as a macro which will be replaced with  the
       indicated  text when encountered in the source files.  Any
       occurrences of the strings '$n' in the  replacement  text,
       where  1 <= n <= 9, will be replaced with the nth argument
       when the macro is actually invoked.  For example:
       
                      define(bump, $1 = $1 + 1)
       
       will cause the source line
       
                      bump(i)
       
       to be expanded into
       
                      i = i + 1
       
       The names of macros may contain letters,  digits,  periods
       and  underline  characters,  but  must start with a letter
       (e.g. B.FLAG).  Upper case is not equivalent to lower case
       in macro names.
       The replacement text is copied directly  into  the  lookup
       table  with  no  intepretation  of  the  arguments,  which
       differs from the procedure  used  in  the  macro  utility.
       This  "deferred  evaluation" has the effect of eliminating
       the need for quoting strings to get them through the macro
       processor  unchanged.   A  side  effect  of  the  deferred
       evaluation  is that defined names cannot be forced through
       the processor - i.e.  the  string  define  will  never  be
       output  from  the preprocessor. The inequivalence of upper
       and lower case in macro names may be used in this case  to
       force  the  name of a user defined macro onto the output -
       i.e. if the user has defined  a  macro  named  mymac,  the
       replacement  text  may  contain the string MYMAC, which is
       not defined, and will pass through the processor.
       
       In addition to define,  four  other  built-in  macros  are
       provided:
       
        arith(x,op,y)   performs    the    "integer"   arithmetic
                        specified by  op  (+,-,*,/)  on  the  two
                        numeric  operands  and returns the result
                        as its replacement.
        incr(x)         converts the string x to a  number,  adds
                        one  to  it, and returns the value as its
                        replacement (as a character string).
        ifelse(a,b,c,d) compares a and b as character strings; if
                        they are the same, c is pushed back  onto
                        the input, else d is pushed back.
        substr(s,m,n)   produces  the substring of s which starts
                        at  position  m  (with  origin  one),  of
                        length  n.   If  n is omitted or too big,
                        the rest of the string is used, while  if
                        m  is  out  of range the result is a null
                        string.
       
       Note: the statement
       
                      define name text
       
       may also be used, but will not  always  perform  correctly
       for  macros  with  parameters  or  multi-line  replacement
       text.   It  is  suggested  that  the  functional  form  be
       preferred.
       
       Conditional Preprocessing:
       
       The statements
       
                      ifdef(macro,text)
                      ifnotdef(macro,text)
       
       conditionalize  the  preprocessing  upon whether the macro
       has been previously defined or not.
       
       
       String Data Types:
       
       The statements
       
                 string name "character string"          or
                 string name(size) "character string"
                 
       declare 'name' to be a  character  array  long  enough  to
       accomodate the ascii codes for the given character string,
       one  per  array  element. The array is then filled by data
       statements. The last word of 'name' is initialized to  the
       symbolic parameter EOS, and indicates the end of a string.
       EOS  must  be  defined  either in the standard definitions
       file or by the user. If a size is given, name is  declared
       to  be  a  character  array of 'size' elements. If several
       string declarations appear  consecutively,  the  generated
       declarations   for   the  arrays  will  precede  the  data
       statements that  initialize  them.  Escape  sequences  are
       recognized  in string declarations, such that @n maps into
       the NEWLINE character and @t maps into the TAB  character.
       @c  for any other character simply maps into the character
       c.  In particular, to embed an atsign '@' in a string, one
       must type '@@'.

       String Literals:
       
       Conversion  of  in-line  quoted   strings   to   hollerith
       constants is performed in the following manner:
       
            "str"         nHstr     
            'str'         nHstr
         (where 'n' is the number of characters in str)
       String literals can be continued across line boundaries by
       ending  the  line  to  be continued with an underline. The
       underline is not included as part of the literal.  Leading
       blanks and tabs on the next line are ignored.

       Integer Constants:
       
       Integer  constants  in  bases  other  than  decimal may be
       specified as n%dddd...  where  'n'  is  a  decimal  number
       indicating the base and 'dddd...' are digits in that base.
       For  bases  >  10,  letters  are  used for digits above 9.
       Examples include:  8%77 (=63),  16%2ff  (=767),  2%0010011
       (=19).  The  number is converted to the equivalent decimal
       value using multiplication; this may cause  sign  problems
       if the number has too many digits.

       Lines and Continuation:
       
       Input  is  free-format;  that  is,  statements  may appear
       anywhere on a line. Lines ending with a comma, +, -, or  *
       are assumed to be continued on the next line. An exception
       to this rule is within a condition; the line is assumed to
       be  continued  if  the condition does not fit on one line.
       Explicit continuation is indicated by ending a  line  with
       an underline character (_). The underline character is not
       copied to the output file.

       Comments:
       
       Comments are preceded by '#' signs and may appear anywhere
       in the code.

       Literal (unprocessed) Lines:
       
       Lines  can  be passed through rat4 without being processed
       by preceding and following the blocks of lines with a line
       containing only a '%'. The '%' lines will not be copied to
       standard output.

CHANGES
       This ratfor preprocessor differs  from  the  original  (as
       released by Kernighan and Plauger) in the following ways:
       
       The code has been rewritten and reorganized for clarity.
       
       A  hash  table  has been added for increased efficiency in
       searching the definitions list.
       
       The 'string' data type has been included.
       
       The define processor has been augmented to support  macros
       with arguments.
       
       Conditional  preprocessing  upon  the  definition (or lack
       therof) of a symbol has been included.

       Many extraneous gotos have been avoided.
       
       Some blanks have been included in the output for increased
       readability.
       
       Multi-level  'break'  and  'next'  statements  have   been
       included.
       
       The Fortran 'DO' is allowed, as well as the ratfor one.
       
       The  capability  of  specifying integer constants in bases
       other than decimal has been added.
       
       Underscores and dots have been allowed in defined names.
       
       The 'define' syntax has been expanded to include the form:
                           define name value
       
       The 'return(value)' feature has been added.
       
       Quoted file names following 'include' statements have been
       added to allow for special characters in file names.
       
       A toggle for allowing lines to pass  through  un-processed
       has been added.
       
       The 'switch' control statement has been included.
       
       Continuation lines have been implemented.
       
       Brackets have been allowed to replace braces.

FILES
       A   generalized   definition   file   (e.g.  'ratdef')  is
       automatically opened and read.

SEE ALSO
       Kernighan and Plauger's "Software Tools" 
       Kernighan's "RATFOR - A Preprocessor for a Rational Fortran" 
       The Unix command rc in the Unix Manual 
       The tools 'incl' and 'macro'

DIAGNOSTICS
       (The errors marked with asterisk '*' are fatal; all others
       are simply warning messages.)

       * arg stack overflow
            The argument stack for the macro processor  has  been
            exceeded.  The size of the stack is determined by the
            symbol ARGSIZE in the file macsym.
       * buffer overflow
            One    of   the   preprocessor's   internal   buffers
            overflowed, possibly, but  not  necessarily,  because
            the  string  buffers  were  exceeded.  The definition
            SBUFSIZE in the preprocessor symbols file  determines
            the size of the string buffers.
       * call stack overflow
            The  call  stack  (used  to store call frames) in the
            macro processor has been  exceeded.   The  definition
            CALLSIZE  in  the  file macsym determines the size of
            this stack.
       can't open standard definitions file
            The special file containing  general  purpose  ratfor
            definitions  could not be opened, possibly because it
            did not exist or the user did not have access to  the
            directory on which it resides.
       can't open include
            File  to  be  included could not be located, the user
            did not have privilege to  access  it,  or  the  file
            could  not be opened due to some problem in the local
            primitives.
       * definition too long
            The number of characters in the name  to  be  defined
            exceeded  Ratfor's  internal  array size. The size is
            defined by the MAXTOK definition in the  preprocessor
            symbols file.
       * EOF in string
            The  macro  processor  detected an EOF in the current
            input file while evaluating a macro.
       * evaluation stack overflow
            The evaluation stack for the macro processor has been
            exceeded. This stack's  size  is  determined  by  the
            symbol EVALSIZE in the file macsym.
       * for clause too long
            The  internal buffer used to hold the clauses for the
            'for' statement was exceeded. Size of this buffer  is
            determined   by   the  MAXFORSTK  definition  in  the
            preprocessor symbols file.
       * getdef is confused
            There were horrendous  problems  when  attempting  to
            access the definition table
       illegal break
            Break did not occur inside a valid "while", "for", or
            "repeat" loop
       illegal else
            Else clause probably did not follow an "if" clause
       illegal next
            "Next"  did  not occur inside a valid "for", "while",
            or "repeat" loop
       illegal right brace
            A right brace was found without a matching left brace
       includes nested too deeply
            There is a limit to the level of nesting of  included
            files.  It  is  dependent  upon the maximum number of
            opened files allowed at a time, and  is  set  by  the
            NFILES definition in the preprocessor symbols file.
       invalid for clause
            The  "for"  clause  did  not  contain  a  valid init,
            condition, and/or increment section
       invalid string size
            The string format 'string name(size) "..."' was used,
            but the size was given improperly.
       * missing comma in define
            Definitions  of  the  form  'define(name,defn)'  must
            include the comma as a separator.
       missing function name
            There was an error in declaring a function
       missing left paren
            A  parenthesis  was  expected,  probably  in  an "if"
            statement, but not found
       missing parenthesis in condition
            A right parenthesis was expected, probably in an "if"
            statement, but not found
       missing quote
            A quoted string was not terminated by a quote
       missing right paren
            A right parenthesis was expected  in  a  Fortran  (as
            opposed to Ratfor) statement but not found
       missing string token
            No  array  name  was  given  when  declaring a string
            variable
       * non-alphanumeric name
            Definitions may contain only alphanumeric characters,
            dots, and underscores.
       * stack overflow in parser
            Statements were nested at too deep a level. The stack
            depth is  set  by  the  MAXSTACK  definition  in  the
            preprocessor symbols file.
       token too long
            A token (word) in the source code was too long to fit
            into  one  of  Ratfor's  internal arrays. The maximum
            size  is  set  by  the  MAXTOK  definition   in   the
            preprocessor symbols file.
       * too many characters pushed back
            The  source  code  has  illegally  specified a Ratfor
            command, or has used a Ratfor keyword in  an  illegal
            manner,  and  the  parser has attempted but failed to
            make sense out of it The size of the push-back buffer
            is set by BUFSIZE in the preprocessor symbols file.
       too many definitions
            Ratfor's internal  arrays  could  not  hold  all  the
            definitions.  The  size  of  the  definition table is
            determined by the MAXTBL and  MAXPTR  definitions  in
            the preprocessor symbols file.
       unbalanced parentheses
            Unbalanced  parentheses  detected  in  a  Fortran (as
            opposed to Ratfor) statement
       unexpected brace or EOF
            A brace occurred after a  Fortran  (but  not  Ratfor)
            statement  or  an  end-of-file was reached before the
            end of a statement
       unexpected EOF
            An end-of-file was reached before all braces had been
            accounted for.  This is usually caused  by  unmatched
            braces somewhere deep in the source code.
       warning:  possible label conflict
            This  message  is printed when the user has labeled a
            statement with a  label  in  the  23000-23999  range.
            Ratfor  statements  are  assigned in this range and a
            user-defined one may conflict with a Ratfor-generated
            one.
       "file":  cannot open
            Ratfor could not open an input file specified by  the
            user on the command line.

AUTHORS
       Original  by B. Kernighan and P. J. Plauger, with rewrites
       and enhancements  by  David  Hanson  and  friends  (U.  of
       Arizona),   Joe  Sventek  and  Debbie  Scherrer  (Lawrence
       Berkeley Laboratory).

BUGS/DEFICIENCIES
       
       The line numbers given in error messages are NOT  correct.
       They indicate only a general area in which to look for the
       error.
       
       Missing  parentheses or braces may cause erratic behavior,
       including a  read-past-eof  message.   Eventually   Ratfor
       should  be  taught to terminate parentheses/brace checking
       at the end of each subroutine.
       
       Extraneous  'continue'  statements  are  generated  within
       Fortran 'do' statements.
       
       There  is  no way to explicitly cause a statement to begin
       in column 6 (i.e. a Fortran continued statement), although
       implicit continuation is performed.

2 rc
        rc - ratfor compiler
        
     SYNOPSIS
        
        rc [-c] [-r] [-f] [-v] [-o] file ...
        
     DESCRIPTION
        
        rc  is the ratfor compiler.  It accepts the following types of
        arguments:
        
        1. Files whose names end in '.r'  are  assumed  to  be  ratfor
           source  programs;  they  are  preprocessed into fortran and
           compiled.  The preprocessed file for name.r  is  placed  on
           name.f  and  the  compiled object code appears on name.obj.
           The name.f file is removed  unless  -f  is  specified  (see
           below).
           
        2. Five flags which affect the actions of the compiler are:
           
           -c suppress the loading phase, as does any preprocessing or
              compilation error
           -r ratfor only; don't compile fortran; implies -f and -c
           -f save  fortran  intermediate files; usually for debugging
              purposes
           -v verbose option; prints  name  of  each  file  as  it  is
              preprocessed  and prints name of each '.f' file as it is
              compiled
           -o generates fortran listing for name.f on name.l
              
        3. Files whose names end in '.f' are  assumed  to  be  fortran
           source  programs,  and  are  compiled.  Other arguments are
           assumed to be loader  flags,  or  object  files,  typically
           created  by an earlier rc or fc run.  These files, together
           with the results of any compilations, are loaded to produce
           an executable process.
           
     SEE ALSO
        
        rat4,  the  ratfor  preprocessor,  for  descriptions  of   the
        language  and  for  a  more  general  way  of  performing  the
        preprocessing.
        fc, the fortran compiler
        ld,  the  loader,  for  loader  flags   and   process   naming
        conventions
        
     AUTHOR
        
        Joe Sventek wrote the interface of rc to rat4, fc, and ld.
        
     BUGS
        none to date

2 resolve
       resolve - resolve mail system user names

SYNOPSIS
       resolve expression [expression ...]

DESCRIPTION
       resolve  searches the mail database for lines matching the text
       pattern "expression". (Valid text patterns are the same as  for
       find.)   Resolve  will display on the standard output all lines
       which match any one of the given expressions.

FILES

SEE ALSO
       find - search a file for text patterns
       mail - software tools mail facility
       users - list users to whom mail may be sent

DIAGNOSTICS
       None

AUTHOR
       Joe Sventek

BUGS/DEFICIENCIES

2 resume
       resume - resume a suspended process

SYNOPSIS
       resume processid [processid ...]

DESCRIPTION
       RESUME  resumes a suspended process which has been suspended by
       the utility suspnd.  The processid's are returned by the  shell
       when a background process is spawned.

FILES
       None

SEE ALSO
       suspnd - suspend a running process
       sh - shell (command line interpreter)

DIAGNOSTICS
       If  the  process  cannot  be  resumed, an error message will be
       displayed on the error output.

AUTHOR
       Joe Sventek (VAX)

BUGS/DEFICIENCIES
       
2 rev
   rev - reverse lines

SYNOPSIS
   rev [files ...]

DESCRIPTION
   Rev  copies  the named files to the standard output, reversing
   the order of the characters in every line.
   
   If no files are given, or the filename '-' is  specified,  rev
   reads from the standard input.

AUTHORS
   David Hanson and friends (U. of Arizona)

2 rm
       rm - remove files

SYNOPSIS
       rm name ...

DESCRIPTION
       Rm removes the files specified.

FILES

SEE ALSO
       The Unix command 'rm'

DIAGNOSTICS
       A message is printed if the file could not be removed.

AUTHORS

       Joe Sventek (DEC machines); Debbie Scherrer (CDC machines)

BUGS

2 roff
       roff -- format text

SYNOPSIS
       roff  [+n] [-n] [-s] [-pon] [name ... ]

DESCRIPTION
       'Roff'  formats  text  according to 'request lines' embedded in
       the text of the given file names. If nonexistent file names are
       encountered they are ignored. The optional flag arguments mean:

              +n Start printing at the first page with number 'n'.

              -n Stop printing at the first page numbered higher  than
                 'n'.

              -s Stop  before  each  page, including the first (useful
                 for paper manipulation). The prompt "Position  paper,
                 then  hit  CR  to continue" is given just once before
                 the first page.

            -pon Move the entire document 'n'  spaces  (default=0)  to
                 the right ('page offset').

       Input   consists   of  intermixed  text  lines,  which  contain
       information to be formatted, and request lines,  which  contain
       instructions  about how to format the text lines. Request lines
       begin with a distinguishing  'control  character',  normally  a
       period.    Lines  having  leading  spaces  are  output  without
       modification.  Strings of embedded spaces are retained so  that
       the  output  line  will contain at least as many spaces between
       words as the input line.

       Output lines may be 'filled' without regard to  the  format  of
       the  input  text lines. Right justification of filled lines may
       be turned on and off through the use of  the  '.ju'  and  '.nj'
       request lines. Line 'breaks' may result from the use of certain
       request  lines,  or by the appearance of an empty input line or
       an input line beginning with a space.

       Normally, at least one space is placed between the last word of
       a line and the first word of the next.   This  feature  may  be
       suppressed  by  issuing  the  '.bs'  request  line,  which will
       suppress the space between the last word of the  previous  line
       and  the  first word of the following line.  All other words in
       the following line are treated in the usual manner.

       The capabilities of roff are specified in the attached 'Request
       Summary'. Numerical values are denoted there by 'n', titles  by
       't',  and  single characters by 'c'. Numbers denoted 'n' may be
       signed + or -, in which case they signify relative changes to a
       quantity; otherwise they signify an absolute  setting.  Missing
       'n'  fields are ordinarily taken to be 1, missing 't' fields to
       be empty, and 'c' fields to shut off  the  appropriate  special
       interpretation.

       Running  titles may appear at the top and bottom of every page.
       The head and foot for this writeup was set by:

            .he 'ROFF'07/26/78'ROFF'
            .fo ''-#-

       A title line consists of a line with three distinct fields: the
       first is text to be placed flush  with  the  left  margin,  the
       second centered, and the third flush with the right margin. The
       first   non-blank  character  in  the  title  is  used  as  the
       'delimiter' to separate the three fields. Any '#' characters in
       a title are replaced by the current page number.

FILES
       None

SEE ALSO
       The "Software Tools" book, pages 219-250.
       The "UNIX Programmer's Manual", ROFF(I) and NROFF(I)/TROFF(I).
       The 'nroff' and 'troff' user's manuals by  Joseph  F.  Ossanna,
       Bell Laboratories, Murray Hill, New Jersey.

DIAGNOSTICS
       None

AUTHORS
       This  tool  was  obtained  from  the  book  "Software Tools" by
       Kernighan  and  Plauger;  it  was  initially  adapted  to   BKY
       (including  the  '-n',  '+n',  '-s' and '-pon' flags) by Debbie
       Scherrer. Minor additions were made by  Donn  Davy  and  Dennis
       Hall.  Roff  was  originally  prepared for installation by Brad
       Heckman. Substantial enhancements were added by Joe Sventek.

BUGS/DEFICIENCIES
       The '.bs' directive does not always work at the end  of  filled
       lines.

REQUEST SUMMARY

Request Initial Default Break Meaning

.bd n           n=1     no    Boldface the next 'n' lines.
.bp n     n=1   n=+1    yes   Begin new page and number it 'n'.
.br                     yes   The filling of the current line is stopped.
.bs n           n=1     no    Suppress blanks between words on adjacent lines.
.cc c     c=.   c=.     no    Control character becomes 'c'.
.ce n           n=1     yes   Center the next 'n' input lines without filling.
.ef t     t=''  t=''    no    Foots on even pages are 't'.
.eh t     t=''  t=''    no    Heads on even pages are 't'.
.fi       yes           yes   Begin filling output lines.
.fo t     t=''  t=''    no    All foot titles are 't'.
.he t     t=''  t=''    no    All head titles are 't'.
.in n     n=0   n=0     yes   Set left margin to column 'n+1'.
.ju             yes     no    Right justify filled lines.
.ls n     n=1   n=1     no    Line spacing set to 'n' lines per output line.
.m1 n     n=3   n=1     no    Put 'n' blank lines between top of page and head.
.m2 n     n=2   n=1     no    Put 'n' blank lines between head and text.
.m3 n     n=2   n=1     no    Put 'n' blank lines between text and foot.
.m4 n     n=3   n=1     no    Put 'n' blnk lns between foot and bottom of page.
.ne n           n=0     y/n   Begin new page if 'n' lines won't fit on output.
                              Break if need to start new page; don't if not.
.nf       no            yes   Stop filling output lines.
.nj       no            no    Do not right justify filled lines.
.of t     t=''  t=''    no    Foots on odd pages are 't'.
.oh t     t=''  t=''    no    Heads on odd pages are 't'.
.pl n     n=66  n=66    no    Total page length is 'n' lines.
.po n     n=0   n=0     no    Page offset; precede all lines by 'n' spaces.
.rm n     n=65  n=65    no    Set right margin to column 'n'.
.sp n           n=1     yes   Insert 'n' blank lines, except at top of page.
.ti n           n=0     yes   Temporarily indent next output line 'n' spaces.
.ul n           n=1     no    Underline the next 'n' lines.

2 ruler
       ruler - display ruler on terminal screen

SYNOPSIS
       ruler [n]

DESCRIPTION
       ruler  displays  a  ruler  on the terminal.  This is especially
       useful when  using  field  or  other  utilities  which  require
       knowledge  of  the  column positions of portions of the screen.
       The optional numeric argument indicates  how  many  columns  to
       format in the ruler.

FILES

SEE ALSO
       field - utility for field manipulation
       sort - file sorter

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 sched
       sched - a way to repetitively invoke a command

SYNOPSIS
       sched [-r<repetitions>] [-t<seconds>] "shell command"

DESCRIPTION
       sched  causes  the  command  typed in quotes to be repetitively
       invoked. The defaults are to invoke the command  once,  and  to
       wait  1  second  before each invocation.  This utility is quite
       nice for statistics gathering, since sched may be  run  in  the
       background,  with  the diagnostic output being appended to some
       log file.  For example:
       
       % sched -r360 -t10 "ps -a >>ps.log"&
       
       would cause ps to run and append its output to ps.log every  10
       seconds  for  the next hour.  The resulting log file could then
       be edited to find out the  most  heavily  used  utilities,  the
       average number of processes per user, etc.

FILES

SEE ALSO
       sleep - cause process to suspend itself for a period of time

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 sedit
   sedit - stream editor

SYNOPSIS
   sedit [-n] {[-e script | -f sfile]... | script} [file]...

DESCRIPTION
   Sedit  copies  the  named  input files to the standard output,
   performing editing as directed by sedit commands  in  "script"
   or in "sfile". The -e flag indicates that the next argument is
   to be interpreted as an sedit command (see below). The -f flag
   indicates  that  the  next  argument  is the name of a file in
   which sedit commands appear  one  per  line.  The  -e  and  -f
   arguments may be intermixed in any order. The order of command
   execution is the order in which commands are read. If no -e or
   -f  flags  are  given,  the first argument is used as an sedit
   command. Normally, sedit writes each  line  of  input  to  the
   output  after  editing;  the -n option suppresses this action.
   As a result, the only output  is  that  resulting  from  sedit
   commands.

   When  the  first  argument  not  in  the  scope  of  a flag is
   encountered, it and all  succeeding  arguments  are  taken  as
   input  files.  If  no  files  are given, or if the name "-" is
   specified, the standard input is read.

   Sedit commands have the general form

      line1 [, line2] command arguments

   A line number (line1 or line2) is either a decimal number that
   refers to a specific  input  line  (input  lines  are  counted
   cumulatively across files), a "$" that refers to the last line
   of input, or a /pattern/ where pattern is a regular expression
   (as  in  edit).  Line number 0 may be used to specify commands
   that should be executed before any input is read.

   A command with no line numbers is applied  to  every  line  of
   input. A command with one line number is applied to every line
   of input that matches the line number. A command with two line
   numbers  is  applied to every line of input beginning with the
   first line that matches  line1  through  the  next  line  that
   matches  line2.   Thereafter, the process is repeated, looking
   again for a line that matches line1.

   Sedit accepts the following commands.   Each  command  may  be
   used  with  0,  1, or 2 line numbers. The a, c, and i commands
   may not appear in command line scripts.

   a
   <text>
   .
      Append.  The <text> is placed  on  the  output  after  each
      selected  line.  The <text> does not change the line number
      nor is it subject to subsequent sedit commands.

   c
   <text>
   .
      Change.  The selected  lines  are  deleted  and  <text>  is
      placed  on  the  output in their place. The <text> does not
      change the line number nor  is  it  subject  to  subsequent
      sedit commands.

   d
      Delete.  The selected lines are deleted.

   i
   <text>
   .
      Insert.   The  <text>  is  placed on the output before each
      selected line.  The <text> does not change the line  number
      nor is it subject to subsequent sedit commands.

   p
      Print.   The  selected  lines  are  printed on the standard
      output.

   r file
      Read file.  The contents of "file" are placed on the output
      after each selected line exactly as if  the  contents  were
      given  as  <text>  in  an  a command.  The new lines do not
      change the line number nor are they subject  to  subsequent
      sedit commands.

   s/pat/new/gp
      Substitute.    The  leftmost  occurrences  of  pat  in  the
      selected lines is changed to new. If g  is  specified,  all
      occurrences  are changed.  If p is specified, the resulting
      line is printed.

   w file
      Write file.  The selected lines  are  appended  to  "file".
      Files mentioned in w commands are created before processing
      begins.  The  limit  on the number of w commands depends on
      the number of files that can be opened at the same time.

   =
      Print line number.  The current line number is  printed  on
      the output as a line.

   Text  appended  by a, c, or r commands is placed on the output
   in the same order as the execution of  the  commands.  Similar
   comments apply to text inserted by i commands.

   Sedit  can  accomodate  commands  totaling  approximately 5000
   characters (including <text> arguments), and lines up  to  120
   characters in length.

SEE ALSO
   edit, change, find, tr

DIAGNOSTICS
   In  addition  to  the usual error messages resulting from file
   access failure, sedit issues the following messages preceeding
   by the offending command line.

   bad line numbers
      indicates that the line number expressions are invalid.

   invalid command
      indicates  that  the  command  preceeding  the  message  is
      illegal.  This message is issued for a, i, or c commands if
      they appear in command string scripts.

   too many commands
      indicates exhaustion of space to hold commands. The size of
      the command buffer is determined by the  MAXBUF  definition
      in the source code.

AUTHOR
   Chris Fraser (U. of Arizona)

BUGS/DEFICIENCIES
   The '$' indicator for end-of-file doesn't always work.

2 sh
       sh - shell (command line interpreter)

SYNOPSIS
       sh [-vnx] [name [arg1 .. [arg9]]].

DESCRIPTION
       Sh  is  a command line interpreter: it reads lines typed by the
       user and interprets them as requests to execute other programs.
       
       
       Commands.
       In simplest form, a command line consists of the  command  name
       followed by arguments to the command, all separated by spaces:
                         command arg1 arg2 ... argn
       The  shell  splits  up  the command name and the arguments into
       separate strings. Then a file  with  name  command  is  sought;
       command  may  be a path name to specify any file in the system.
       If command is found, it is brought into  memory  and  executed.
       The  arguments  collected  by  the  shell are accessible to the
       command. When the command is finished, the  shell  resumes  its
       own  execution  and  indicates  its readiness to accept another
       command by typing a prompt character.
       
       If file command cannot be found in  the  current  directory  or
       through  its  pathname,  the  shell  searches a specific system
       directory of commands intended to be available to sh  users  in
       general.
       
       An example of a simple command is:
                                  sort list
       which  would look for the tool 'sort' in the current directory,
       then in the system directory, and then  sort  the  contents  of
       file 'list', printing the output at the user's terminal.
       
       Some  characters  on  the command line have special meanings to
       the shell (these are discussed below). The character '@' may be
       included anywhere in the command line to  cause  the  following
       character  to lose any special meaning it may have to the shell
       (to be 'escaped'). Sequences of characters enclosed  in  double
       (") or single (') quotes are also taken literally.
       
       
       Standard I/O
       Shell  programs  in  general  have  open  three standard files:
       'input', 'output', and 'error output'. All three  are  assigned
       to  the  user's  terminal  unless  redirected  by  the  special
       arguments '<', '>', '?', '>>', '??', (and sometimes '-').
       
       An argument of the form '<name' causes the file  'name'  to  be
       used as the standard input file of the associated command.
       
       An  argument  of the form '>name' causes file 'name' to be used
       as the standard output.
       
       An argument of the form '?name' causes the file  'name'  to  be
       used as the standard error output.
       
       Arguments of the form '>>name' or '??name' cause program output
       to  be  appended  to 'name' for standard output or error output
       respectively. If 'name' does not exist, it will be created.
       
       Most tools have the capability  to  read  their  input  from  a
       series  of  files.  In  this  case, the list of files overrides
       reading from standard input. However, many of the  tools  allow
       the  user  to  read from both a list of files and from input by
       specifying the filename '-' for standard input. For example,
                             roff file1 - file2
       would read its input  from  'file1',  then  from  the  standard
       input, then from 'file2'.
       
       
       Filters and Pipes.
       The  output  from  one  command may be directed to the input of
       another. A sequence of commands separated by vertical bars  (|)
       or  carets  ('^') causes the shell to arrange that the standard
       output of each command be delivered to the  standard  input  of
       the next command in sequence. Thus in the command line:
                           sort list | uniq | crt
       'sort'  sorts the contents of file 'list'; its output is passed
       to 'uniq', which strips out duplicate lines.  The  output  from
       'uniq'  is  then  input  to 'crt', which prepares the lines for
       viewing on the user's crt terminal.
       
       The vertical bar is called a 'pipe'. Programs such  as  'sort',
       'uniq', and 'crt', which copy standard input to standard output
       (making some changes along the way) are called 'filters'.
       
       
       Command separators
       Commands  need  not  be on different lines; instead they may be
       separated by semicolons:
                                ar t file; ed
       The above command will first list the contents of the  archived
       file 'file', then enter the editor.
       
       The  shell  also  allows  commands  to be grouped together with
       parentheses, where the group can then be used as a filter.  For
       example,
                    (date; cat chocolate) | comm vanilla
       writes first the date and then the file 'chocolate' to standard
       output,  which  is  then  read  as  input  by 'comm'. This tool
       compares the results with existing file 'vanilla' to see  which
       lines the two files have in common.
       
       Multitasking
       On  many systems the shell also allows processes to be executed
       in the background. If a command is followed by '&',  the  shell
       will not wait for the command to finish before prompting again;
       instead,  it  is ready immediately to accept a new command. For
       instance,
                           rat4 ambrose >george &
       preprocesses  the  file  'ambrose',  putting  the   output   on
       'george'.  No  matter how long the compilation takes, the shell
       returns immediately. The identification number of  the  process
       running  that  command  is  printed. This identification may be
       used to wait for the completion of the command or to  terminate
       it.
       
       The  '&'  may  be used several times in a line. Parentheses and
       pipes are also allowed (within the same background process).
       
       
       Script files.
       The shell itself is a command, and may be  called  recursively,
       either  implicitly  or explicitly. This is primarily useful for
       executing  files  containing  lines  of  shell  commands.   For
       instance,  suppose you had a file named 'nbrcount' which looked
       like this:
                      echo 'Counting strings of digits'
                      tr <program 0-9 9 | tr !9 | ccnt
       These commands count all the digit strings  in  'program'.  You
       could have the shell execute the commands by typing:
                                 sh nbrcount
       The  shell  will  also  execute  script  files  implicitly. For
       example, giving the command
                                  nbrcount
       would cause the  shell  to  notice  that  the  file  'nbrcount'
       contained  text  rather  than  executable code. The shell would
       then execute itself again, using 'nbrcount' as its input.
       
       Arguments may also be passed to script files. In script  files,
       character  sequences  of  the  form  '$n',  where  n is a digit
       between 1 and 9, are  replaced  by  the  nth  argument  to  the
       invocation  of  the  shell.  For  instance,  suppose  the  file
       'private' contained the following commands:
                      cat $1 $2 $3 | crypt key >$4
                      ar u loveletters $4
       Then, executing the command
                        private Dan John Harold fair
       would merge the files  'Dan',  'John',  and  'Harold',  encrypt
       them, and store them away in an archive under the name 'fair'.
       
       Script  files  may  be  used  as filters in pipelines just like
       regular commands.
       
       Script files sometimes require in-line data to be available  to
       them.  A  special  input  redirection  notation "<<" is used to
       achieve this effect. For example, the editor normally takes its
       commands from the  standard  input.  However,  within  a  shell
       procedure commands could be embedded this way:
       
                           ed file <<!
                           editing requests
                           !
       
       The  lines between <<! and ! are called a 'here' document; they
       are read by the shell and made available as the standard input.
       The character '!' is arbitrary, the document  being  terminated
       by a line that consists of whatever character followed the <<.
       
       
       
       Shell Flags.
       The shell accepts several special arguments when it is invoked.
       The  argument  -v asks the shell to print each line of a script
       file as it is read as input. For instance,
                sh -v private Jasmine Irma Jennifer twostars
       would print each line of the script file 'private' as  soon  as
       it is read by the shell.
       
       The argument -x is similar to the -v above except that commands
       are printed right before they are executed. These commands will
       be  printed  in  the  actual  format  the  system  expects when
       attempting to execute the program.
       
       The argument -n suppresses execution of the command entirely.
       
       The argument -c causes the remaining arguments to  be  executed
       as a shell command.
       
       
       Termination.
       The  shell  may  be  left by typing an end-of-file or by typing
       'logout' as a command.
       
       
FILES
       Scratch  files  are  created  for  pipelines  and  for   'here'
       documents.

SEE ALSO
       The Unix command 'sh'
       The  Bell  system  Technical  Journal,  vol. 57, no. 6, part 2,
       July-Aug 1978
       

DIAGNOSTICS
       The error message 'syntax error'  appears  whenever  a  command
       line cannot be understood.
       'Invalid  command'  is  printed  whenever  a  command cannot be
       located in the various directories searched.
       
       The message 'cannot spawn process' appears if the shell  cannot
       cause the system to execute the command desired.

AUTHORS

       Dennis Hall, Joe Sventek, Debbie Scherrer

BUGS
       If  a  user  wants  to  escape  a  shell special character that
       appears as the first character of an argument, he  must  escape
       it with quotes rather than an '@' sign.

2 sleep
       sleep - cause process to suspend itself for a period of time

SYNOPSIS
       sleep n

DESCRIPTION
       sleep  causes  the  process to suspend itself for the indicated
       number of seconds.  This  facility  is  generally  useful  when
       sending  formatted  output  to a high-quality terminal, and you
       need time to change the paper from  the  time  you  invoke  the
       command until it starts printing on the good paper.

FILES

SEE ALSO
       sched - a way to repetitively invoke a command

DIAGNOSTICS

AUTHORS
       Joe Sventek

BUGS

2 sndmsg
        SNDMSG - utility for sending mail to other users
        
     SYNOPSIS
        
        sndmsg
        
     DESCRIPTION
        
        SNDMSG  is the utility used to send mail to other users of the mail
        system. The user is prompted for all of the necessary input in  the
        following manner:

          1. The list of To addresses.
          2. The list of Cc (carbon copy) addresses
          3. The subject of the message
          4. The body of the message

        The  responses  to  the  To  and  Cc  prompts consist of user-names
        separated by commas.  If it is necessary to continue  the  list  of
        addresses  onto  another line, a comma typed at the end of the line
        causes SNDMSG to prompt for another  line  of  addresses.   If  the
        string  `all'  is typed as an address, all users of the mail system
        will receive a copy of the message.  If  the  address  consists  of
        `<name',  a  file  `name' will be opened and its contents used as a
        mailing list.  The structure of mailing list files differs from the
        address lists (a feature soon to be  removed).   The  mailing  list
        files  should  consist  of  names separated by blanks or tabs.  A #
        symbol signals the start of a comment in the mailing list file, and
        the rest of the line is ignored.

        The subject field may be a string of any length and  content.   The
        user  is  prompted  concerning use of the text editor ed to compose
        the body of the message.  If the editor  is  not  used,  everything
        typed  up  to  an end-of-file on the standard input is taken as the
        body of the message.  In this mode, a line consisting of

        q

        will cause the sndmsg session to be terminated,  with  no  messages
        sent.

     FILES

        three scratch files are used by SNDMSG.

     SEE ALSO

        MSG - the message editor
        ED - the text editor

     AUTHOR

        SNDMSG was written by Joe Sventek

     BUGS/DEFICIENCIES

2 sort
       sort - sort and/or merge text files
       
SYNOPSIS

       sort [-bdfimr] [+sn] [file] ...
       
DESCRIPTION
       
       Sort sorts lines of all the named files together and writes the
       result on the standard output.  The name '-' means the standard
       input.   The standard input is also used if no input file names
       are given. Thus sort may be used as a filter.
       
       The sort key is an entire line. Default ordering is  alphabetic
       by  characters  as  they  are  represented in ASCII format. The
       ordering is affected by the following flags,  one  or  more  of
       which may appear.
       
        -b Leading blanks  are not included in keys.
           
        -d 'Dictionary'  order:  only  letters,  digits and blanks are
           significant in comparisons.
           
        -f Fold all letters to a single case.
           
        -i Ignore all nonprinting nonblank characters.
           
        -m Merge only, the input files are already sorted.
           
        -r Reverse the sense of the sort
           
       +sn Sort according to the subfield starting on column n
           
       
FILES
       
       A series  of  scratch  files  are  generated  and  subsequently
       deleted.  Presently  the  files  are named "STn" where "n" is a
       sequence number.
       
SEE ALSO
       
       The Unix command "sort" in the Unix User's Manual.
       
DIAGNOSTICS
       
       A message is printed if a file cannot be located.
       
AUTHORS
       
       Original design from Kernighan and Plauger's "Software Tools", 
       with modifications by  Debbie  Scherrer.   The  external  merge
       phase of sort was completely rewritten by Joe Sventek.
       
BUGS
       
       The  merge  phase  is  performed  with  a  polyphase merge/sort
       algorithm,  which  requires  an  end-of-run  delimiter  on  the
       scratch  files.  The one chosen is a bare ^D(ASCII code 4) on a
       line.  If this is in conflict with your data files, the  symbol
       CTRLD in sortsym should be redefined and sort built again.
       
       Eventually  all  the  Unix  "sort" flags should be implemented.
       These include:
            sort [-mubdfinrtx] [+pos] [-pos] [-o file] [file] ...
       
       The additional flags are:
       
            n  An initial numeric string, consisting of optional minus
       sign, digits and optionally included decimal point,  is  sorted
       by arithmetic value.
       
                 tx Tab character between fields is x.
       
            +pos -pos  Selected  parts  of the line, specified by +pos
       and -pos, may be used as sort  keys.   Pos  has  the  form  m.n
       optionally followed by one or more of the flags bdfinr, where m
       specifies  a number of fields to skip, n a number of characters
       to skip further into the next field, and the  flags  specify  a
       special ordering  rule  for the key.  A missing . n is taken to
       be 0.  +pos denotes the beginning of the key; -pos denotes  the
       first  position  after the key (end of line by default).  Later
       keys are compared only when all  earlier  keys  compare  equal.
       Note:  The first field of a line is numbered zero.
       
       When  no  tab character has been specified, a field consists of
       nonblanks and any preceding blanks.  Under the -b flag, leading
       blanks are excluded from a field.  When  a  tab  character  has
       been specified, fields are strings separated by tab characters.
       
       Lines  that  otherwise compare equal are ordered with all bytes
       significant.
       
            -o The next argument is the name of an output file to  use
       instead  of  the standard output.  This file may be the same as
       one of the inputs, except under the merge flag -m. {Note--it is
       not clear why this flag is needed.]
       
            -u Suppress all but one in each set  of  contiguous  equal
       lines.  Ignored bytes and bytes outside keys do not participate
       in this comparison.

2 spell
       spell - find spelling errors

SYNOPSIS
       spell [file] ...

DESCRIPTION
       Spell  copies  the  named  files (or standard input if none are
       specified) to standard output while looking up each word  in  a
       dictionary.   If  any spelling errors are found in a particular
       line, an additional line will be printed immediately  following
       the line with asterisks (*) beneath the offending words.

FILES
       dict - a dictionary file
       dictdx - the index generated by isam for the dictionary

SEE ALSO
       isam - generate an index for pseudo-indexed-sequential access
       ospell  -  the  script  pipeline  suggested in K&P for spelling
       errors

DIAGNOSTICS

AUTHORS

       Joe Sventek

BUGS

2 split
       split - split a file into pieces

SYNOPSIS
       split [-n] [file [name] ]

DESCRIPTION
       Split reads file and writes it in n-line pieces (default 1000),
       as  many  as necessary, onto a set of output files. The name of
       the  output  file  is  name  with  aa  appended,  and   so   on
       lexicographically. If no output name is given, x is default.
       
       If  no input file is given, or if - is given in its stead, then
       the standard input file is used.

FILES

SEE ALSO
       The Unix command 'split'

DIAGNOSTICS
       A message is printed if the input file could not be opened.

AUTHORS

       Debbie Scherrer

BUGS

2 suspnd
       suspnd - suspend a running process

SYNOPSIS
       suspnd processid [processid ...]

DESCRIPTION
       SUSPND  suspends running processes specified by the processid's
       in the command line.  The processid's are those returned by the
       shell when it spawns a background process.

FILES
       None

SEE ALSO
       sh - shell (command line interpreter)
       resume - resume a suspended process

DIAGNOSTICS
       if the  process  cannot  be  suspended,  an  error  message  is
       displayed on error output.

AUTHOR
       Joe Sventek (VAX)

BUGS/DEFICIENCIES
       

2 tail
   tail - print last lines of a file

SYNOPSIS
   tail [-n] [file....]

DESCRIPTION
   Tail  prints  the last "n" lines of the indicated file. If 'n'
   is omitted, the last 23 lines are printed.
   
   If "file" is omitted or is "-", tail reads the standard input.

SEE ALSO
   split

AUTHORS
   David Hanson and friends (U. of Arizona)

BUGS/DEFICIENCIES
   An internal buffer of MAXBUF characters is kept. If the  value
   of "n" would require buffering more characters than the buffer
   can  hold, tail prints the last MAXBUF characters of the file.
   In this case, the first line of output may not  be  an  entire
   line.  MAXBUF  is a definition in the source code which may be
   adjusted.

2 tee
       tee -  copy input to standard output and named files

SYNOPSIS
       tee [file ...]

DESCRIPTION
       Tee  copies the standard input to the standard output and makes
       copies in the named files.

FILES

SEE ALSO
       The tool 'cat'; the tool 'crt'; the Unix command 'tee'

DIAGNOSTICS
       A message is printed if the input file cannot be opened.

AUTHORS

       Debbie Scherrer

BUGS

2 timer
       timer - time execution of a process

SYNOPSIS
       timer [-v] "command [arguments]"

DESCRIPTION
       timer spawns a subprocess performing the requested command, and
       displays  the  CPU  time and wall time which elapsed during the
       execution of the command on the standard output.  The  -v  flag
       causes  timer  to  display  other  system-dependent  quantities
       concerning the subprocess  performing  the  requested  command.
       The  command  specified  is  searched for using the same search
       path as the shell.

FILES
       None

SEE ALSO
       The UNIX programmer's manual, time(I)
       sh - shell (command line interpreter)

DIAGNOSTICS
       <command> is an invalid image or script file name
            The requested command could not be found in  the  searched
            directories.
       Error in spawning <command>
            The  requested  image  or script file was located, but the
            process to perform the command could not be spawned.

AUTHOR
       Joe Sventek(VAX)

BUGS/DEFICIENCIES

2 tr
       tr - character transliteration

SYNOPSIS
       tr <infile >outfile from [to]

DESCRIPTION
       "TR"  copies  the  standard  input  to the standard output with
       substitution  or  deletion  of  selected   characters.    Input
       characters  found  in  "FROM" are mapped into the corresponding
       characters of "TO". Ranges of characters may  be  specified  by
       separating  the extremes by a dash. For example, a-z stands for
       the string of characters whose ascii codes run from character a
       through character z.
       
       If the number of characters in "FROM" is the same as in "TO", a
       one to one corresponding translation will be performed  on  all
       occurrences  of  the  characters  in  "FROM".  If the number of
       characters in "FROM" is more than in "TO", the  implication  is
       that  the last character in the "TO" string is to be replicated
       as often as necessary to make a string as long  as  the  "FROM"
       string,  and that this replicated character should be collapsed
       into only one.  If the "TO" string is missing  or  empty,  "TR"
       will take this condition as a request to delete all occurrences
       of characters in the "FROM" string.

       "TR" differs from the tool "CH" since it deals only with single
       characters  or  ranges  of  characters,  while  "CH" deals with
       character strings.  For example  tr xy yx  would change all x's
       into y's and all y's into x's, whereas ch xy yx change all  the
       patterns "xy" into "yx".

       One  of the most common functions of "TR" is to translate upper
       case letters to lower case, and vice versa.  Thus,
       
                                 tr A-Z a-z 
       
       would map all upper  case  letters  to  lower  case.  Users  of
       systems  which cannot pass both upper and lower case characters
       on a command line should remember to  include  the  appropriate
       escape flags.

FILES
       None

SEE ALSO
       Tools "find" and "ch". 
       The "Software Tools" book, p.51-61. 
       The "UNIX Programmer's Manual", p. TR(I). 

DIAGNOSTICS
       "usage: translit from to."
            The command line passed to transit is in error.
       "from: too large."
            The  string for "from" is too large.  Current limit is 100
            characters including E0S.
       "to: too large."
            The string for "to" is too large.  Current  limit  is  100
            characters including EOS.

AUTHORS
       Original  code  from Kernighan and Plaugers's "Software Tools",
       with modifications by Debbie Scherrer.

BUGS/DEFICIENCIES

2 tsort
   tsort - topologically sort symbols

SYNOPSIS
   tsort [files ...]

DESCRIPTION
   Tsort  topologically  sorts the symbols in the named files. If
   no files are specified, or the filename '-'  is  given,  tsort
   reads the standard input.
   
   A  symbol  is considered any string of characters delimited by
   blanks or tabs.
   
   Each line of the input is assumed to be of the form

      a b c ...

   which states that a precedes b, a precedes c, and so on.  Note
   that there is nothing implied about the ordering of b and c. A
   line  consisting  of  a  single  symbol simply "declares" that
   symbol without specifying any ordering relations about it. The
   output is a topologically sorted  list  of  symbols,  one  per
   line.

   For  example,  suppose  you  have  trouble  getting  up in the
   morning because you can't quite remember what actions have  to
   be  performed  in  which  order. However, you do know that the
   first action in the following list precedes all others on  the
   line:
   
        set_alarm   turn_off_alarm
        wake_up    get_out_of_bed    turn_off_alarm
        set_alarm     wake_up
   
   Using tsort to sort the above list would produce the following
   set of actions for getting out of bed:
   
        set_alarm
        wake_up
        turn_off_alarm
        get_out_of_bed

DIAGNOSTICS
   circular
      The  input  specifies  a  graph  that contains at least one
      cycle.

   out of storage
      The input is too large.  The  size  of  tsort's  buffer  is
      determined by the MAXBUF definition in the source code.

SEE ALSO
   sort

AUTHORS
   David Hanson and friends (U. of Arizona)

2 uniq
       uniq - strip adjacent repeated lines from a file

SYNOPSIS
       uniq [-c] [file ...]

DESCRIPTION
       Uniq  reads the input file(s), comparing adjacent lines. Second
       and succeeding  copies  of  repeated  lines  are  removed;  the
       remainder is written to standard output.
       
       If  the '-c' flag is given, each line is preceded by a count of
       the number of occurrences of that line.

FILES

SEE ALSO
       The tool 'comm'; the Unix command 'uniq'

DIAGNOSTICS
       A message is printed if an input  file  cannot  be  opened  and
       processing is terminated.

AUTHORS

       Originally  from Kernighan and Plauger's 'Software Tools', with
       modifications by Debbie Scherrer.

BUGS

2 unrot
       unrot - unrotate lines rotated by kwic

SYNOPSIS
       unrot [-n] [file ...]

DESCRIPTION
       Unrot  processes  the  rotated  output  of 'kwic' to generate a
       keyword-in-context index.
       
       The -n flag may be used to specify  the  width  of  the  output
       lines. The default is 80.
       
       If no input files are given, or the filename '-' appears, lines
       will be read from standard input.

FILES

SEE ALSO
       kwic; sort

DIAGNOSTICS
       A message is printed if an input file cannot be opened; further
       processing is terminated.

AUTHORS

       Original  from  Kernighan  and Plauger's 'Software Tools', with
       modifications by Debbie Scherrer.

BUGS

2 users
        users - list valid mail users
        
     SYNOPSIS
        
        users [-1]
        
     DESCRIPTION
        
        users  lists  the  valid user name to which mail may be sent on the
        standard output.  If the standard output has been redirected  to  a
        file  or  pipeline,  the  names  are  listed  one per line.  If the
        standard output is to a terminal, then the names are listed in five
        columns across the terminal, sorted  alphabetically  from  left  to
        right.   If  single-column  output  is  desired, the -1 switch will
        force a single column to the terminal.  The output of users may  be
        edited and used as a mailing list file for the utility sndmsg.
        
     FILES
        
        users  uses  the file "address" in the mail directory to obtain the
        names of valid users of the mail system.
        
     SEE ALSO
        
        sndmsg - utility to send mail
        msg - utility for reading and filing mail
        postmn - utility to check for the existence of mail
        resolve - utility to query information concering mail users
        
     AUTHOR
        
        users was written by Joe Sventek
        
     BUGS/DEFICIENCIES

2 wc
   wc - count lines, words, and characters in files

SYNOPSIS
   wc [-lwc] files...

DESCRIPTION
   Wc  prints  the  number of lines, words, and characters in the
   named files. The filename "-" specifies the standard input.  A
   total is also printed.  A "word" is any sequence of characters
   delimited by white space.

   The  options  -l,  -w, and -c specify, respectively, that only
   the line, word, or character count be printed.  For example,

      wc -lc foo

   prints the number of lines and characters in "foo".

   If no files are given, wc reads its  standard  input  and  the
   total count is suppressed.

DIAGNOSTICS
   name: can't open
        Printed  when  an  input file can't be opened; processing
        ceases

AUTHORS
   David Hanson and friends (U. of Arizona)

2 wcnt
       wcnt - (character) word count

SYNOPSIS
       wcnt [file ...]

DESCRIPTION
       Wcnt  counts  (character)  words  in the named files, or in the
       standard input if no name  appears.  A  word  is  a  string  of
       characters delimited by spaces, tabs, or newlines.
       
       Wcnt could also be implemented as a shell script file:
                      tr ' @t@n' '@n' | tr '!@n' | ccnt

FILES

SEE ALSO
       lcnt; ccnt; the Unix command 'wc'

DIAGNOSTICS
       A  message  is  printed  if  an input file could not be opened;
       further processing is terminated.

AUTHORS

       Original from Kernighan and Plauger's  'Software  Tools',  with
       modifications by Debbie Scherrer.

BUGS

2 who
       who - who is on the system

SYNOPSIS
       who [-htv] [am i]

DESCRIPTION
       Who  lists the name and terminal number for each current system
       user. The switches affect the format of the listing:

         -h Generate a line of column headers above the display.
         -t Print the total number of users at bottom of display.
         -v Generate  a  verbose  display,   with   system   dependent
            information constituting the verbose portion.

FILES

SEE ALSO
       The Unix command 'who'

DIAGNOSTICS

AUTHORS
       Joe Sventek (DEC machines); Sheldon Furst (CDC machines)

BUGS

2 xref
   xref - make a cross reference of symbols

SYNOPSIS
   xref [-f] [files ...]

DESCRIPTION
   Xref produces a cross-reference list of the symbols in each of
   the  named files on the standard output. Each symbol is listed
   followed by the numbers of the lines in which it  appears.  If
   no  files  are given, or the file "-" is specified, xref reads
   the standard input.

   A  symbol  is  defined  as  a  string  of   letters,   digits,
   underlines,  or  periods  that  begins  with a letter. Symbols
   exceeding an internal  limit  are  truncated.  This  limit  is
   determined by the MAXTOK definition in the source code, and is
   currently set to 15.

   Normally,   xref  treats  upper-  and  lower-case  letters  as
   different characters.  The -f option causes all letters to  be
   folded to lower-case.

DIAGNOSTICS
   out of storage
      The  file  contains  too  many symbols or references to fit
      within the current limitations of xref.  The  size  of  the
      buffer is determined by the MAXBUF definition in the source
      code.

AUTHORS
   David Hanson and friends (U. of Arizona)

BUGS/DEFICIENCIES
   There  should be a means of suppressing "junk" symbols such as
   "the", "a", etc.

