#-h- intro           5141  asc  02-apr-82 16:55:06  v1.1 (sw-tools v1.1)





NAME
    Intro - introduction to software tools primitives




















                    A (Not So) Primitive Document





                            Joseph Sventek
                Computer Science & Applied Mathematics
                     Lawrence Berkeley Laboratory
                         Berkeley, CA  94720





               A  complete  writeup  of  the syntax and
               semantics  of  the  primitive  functions
               upon   which   the  LBL  Software  Tools
               Virtual Operating System is based. 














Intro (2)                      11/17/80                      Intro (2)


Basic assumptions of the tools concerning data types:

     `character' is a signed integer data type of at  least  eight-bit
     accuracy.   The  internal representation of characters within the
     programs is the 7-bit ASCII code, with  EOS  being  traditionally
     defined  as  0  (NULL).   This  leaves  128  negative  values for
     special flags such as EOF, ERR etc.  Msg assumes that it can  use
     200(8)  (NULL  with  the  high  bit  set)  to pad NEWLINES in raw
     terminal I/O. 
     
     Integers and  characters  are  freely  assigned  to  each  other.
     Since  the  above  assumption  is  made, normal FORTRAN compilers
     should perform this without any side effects. 
     
     The data type `linepointer' should be  defined  as  an  intrinsic
     FORTRAN  data  type  large enough to hold the address of a record
     in  a  file.   No  arithmetic  or   assignments   are   done   on
     linepointers,  with  all activities on these entities embodied in
     the routines `note',  `seek',  `ptreq',  `ptrcpy',  `ptrtoc'  and
     `ctoptr'.   It  is also assumed that a defined symbol NULLPOINTER
     exists and is  different  from  any  possible  valid  linepointer
     value. 
     
     
Basic assumptions of the ratfor runtime system
     
     I/O  redirection  flags  are  interpreted  (and  removed from the
     argument list) before the tool's  main  routine  is  called.   In
     order  to  be  able  to pass arguments to the utility which start
     with the special characters  '<',  '>',  or  '?',  quoted  string
     arguments  are  not scanned when determining io redirection.  The
     primitives, as currently defined, only  handle  character  files,
     with  the exception that `gettyp' expects to be able to determine
     whether a file is BINARY or  ASCII.   It  is  expected  that  the
     primitives  will  be extended in the near future to handle ASCII,
     LOCAL and BINARY files unambiguously. 
     
     `getarg(0)' should return the  name  by  which  the  process  was
     invoked.   This  is  useful  if  your  system supports UNIX-style
     links, thus allowing an image to act differently  depending  upon
     which  alias  was  used  for  its  invocation.  None of the tools
     currently use this capability. 
     
     The first routine to be executed is named
     
     subroutine main
     
     It is assumed that all I/O redirection and command line  fetching
     have  been  completed  before `main' is called.  Upon completion,
     `main' simply  returns,  which  causes  a  return  to  the  Tools


                                 -1-


Intro (2)                      11/17/80                      Intro (2)


     runtime  system.  In order to implement this feature, `ld' is set
     up to extract a module from the  library  which  is  the  FORTRAN
     main program, and usually consists of the following lines:
     
     call initst
     call main
     call endst(OK)
     end
     
     If  such  library  extraction  is  not  possible on a system, the
     above four line routine will have to be added to each tool. 
     
     
Basic assumptions concerning RAW terminal I/O
     
     The routine `stmode'  is  supplied  to  permit  the  use  of  RAW
     terminal  I/O.   In actuality, three modes are defined, RAW, RARE
     and COOKED.  COOKED io implies that the system  applies  its  own
     semantics  concerning  the  control  characters  emitted  by  the
     terminal, and performs the echo of the characters for  the  user.
     RARE  and  RAW  assume  that  all reads are done a character at a
     time, with no echo.  RARE  io  assumes  that  there  are  certain
     control   characters   which   the   operating  system  will  not
     relinquish its control of.  These  probably  include  XON,  XOFF,
     terminal  interrupt characters, etc.  RARE is the mode of io used
     by all of the tools currently using RAW io,  since  they  usually
     only  wish  to  apply  their own semantics to the actual printing
     characters.  RAW io is handy  if  one  wishes  to  write  network
     control  programs over asynchronous lines in ratfor (Don't laugh,
     it's being done!).  With RAW io, it is assumed that the  terminal
     driver  is  totally  bypassed.   On many systems, this capability
     requires enormous privilege and other funky  resources,  so  none
     of the commonly available tools use it. 



















                                 -2-

#-h- amove           1416  asc  02-apr-82 16:55:08  v1.1 (sw-tools v1.1)


    Amove (2)                  18-Aug-81                       Amove (2)


    NAME
        Amove - move (rename) file1 to file2

    SYNOPSIS
        integer function amove(name1, name2)
        
        character name1(ARB), name2(ARB)

    DESCRIPTION
        `amove'  moves  the contents of the file specified by `name1' to
        the file specified by `name2'.  It is essentially a renaming  of
        the file. 
        
        Both  file names are character strings representing pathnames or
        filenames in whatever format is expected by the local  operating
        system.   The  names  are  passed as character arrays terminated
        with an EOS character. 
        
        The files need not be  opened  by  (connected  to)  the  running
        program to be renamed. 
        
        The function value returned is OK is successful or ERR if not. 

    IMPLEMENTATION
        `amove'  could  be easily implemented by opening the first file,
        creating the second,  copying the first to the second, and  then
        removing  the  first file.  Alternatively, if possible, it could
        be implemented with a native system call to rename the file. 

    SEE ALSO
        remove(2)

    DIAGNOSTICS
        If the rename fails for any reason, ERR  is  returned.   `name1'
        is removed only if the rename succeeds. 

















                                    -1-

#-h- assign          1448  asc  02-apr-82 16:55:09  v1.1 (sw-tools v1.1)


    Assign (2)                 18-Aug-81                      Assign (2)


    NAME
        Assign - open a file on the specified unit

    SYNOPSIS
        integer function assign(name, fd, access)
        
        character name(FILENAMESIZE)
        filedes fd
        integer access

    DESCRIPTION
        `assign'   is   the  equivalent  of  `open'  or  `create'  on  a
        particular ratfor I/O unit.  If a  file  is  currently  open  on
        `fd',  `assign'  closes  it first.  If `access' has the value of
        READ, `assign' then performs an `open' on  the  specified  unit.
        If  `access'  has  the  value  of  WRITE,  READWRITE  or APPEND,
        `assign'  performs  a  `create'  on  the  specified  unit.   The
        function   value  returned  is  either  the  value  of  `fd'  if
        successful, or ERR. 

    IMPLEMENTATION
        There has been much debate whether `assign' should still  be  in
        the  primitive  set.   The  only  tool  which  relies upon it is
        `sort', since is does  some  fairly  complex  file  manipulation
        during the external merge phase. 

    SEE ALSO
        open(2), create(2), close(2)

    DIAGNOSTICS
        If  the  file could not be opened or created for any reason, the
        value  ERR  is  returned.   In  this  case,  the  previous  file
        associated with `fd' remains closed. 



















                                    -1-

#-h- brdcst          1076  asc  02-apr-82 16:55:10  v1.1 (sw-tools v1.1)


    Brdcst (2)                 12-Mar-82                      Brdcst (2)


    NAME
        Brdcst - broadcast message to one or all terminals

    SYNOPSIS
        integer function brdcst(msg, dev)
        
        character msg(ARB), dev(ARB)
        
        return(OK/ERR)

    DESCRIPTION
        `brdcst'  broadcasts  the  message  in  `msg'  to  the  terminal
        specified by the `dev' argument.  If `dev' is the string  "all",
        the  message  is  broadcast  to  all  logged in terminals on the
        system. 

    IMPLEMENTATION
        `brdcst' is heavily dependent upon whether the operating  system
        supports  such  a  notion.   In  addition,  some systems support
        broadcasts only for very  privileged  users.   This  routine  is
        only  used  by  `sndmsg'  and  `mail'  to  notify  users of mail
        delivery, and can safely be implemented as a stub. 

    SEE ALSO
        trmlst(2)

    DIAGNOSTICS
        Returns ERR if the message cannot be broadcast. 
























                                    -1-

#-h- chmod           1147  asc  02-apr-82 16:55:11  v1.1 (sw-tools v1.1)


    Chmod (2)                  12-Mar-82                       Chmod (2)


    NAME
        Chmod - change protection mode on file

    SYNOPSIS
        integer function chmod( name, mode)
        
        character name(ARB)
        integer mode
        
        return(OK/ERR)

    DESCRIPTION
        `chmod'  attempts to change the protection on the file `name' to
        the value specified in `mode'.   It  returns  the  value  OK/ERR
        reflecting the degree of success in the operation. 

    IMPLEMENTATION
        The  only  current  use of `chmod' is in the `rm' tool using the
        `-f' flag.  In that situation, `mode' is passed  as  an  integer
        of  all  ones.  Before `chmod' can become generally useful, some
        system-independent way of specifying the protection  on  a  file
        needs  to  be  devised.   It is totally permissible to implement
        this as a stub always returning the value ERR. 

    SEE ALSO
        rm(1)

    DIAGNOSTICS
        Return  a  value  of  ERR  if  the  mode  change  could  not  be
        performed. 






















                                    -1-

#-h- closdr           713  asc  02-apr-82 16:55:12  v1.1 (sw-tools v1.1)


    Closdr (2)                 18-Aug-81                      Closdr (2)


    NAME
        Closdr - close an opened directory

    SYNOPSIS
        subroutine closdr(fd)
        
        filedes fd

    DESCRIPTION
        `closdr'  closes  the  directory  that  is  currently opened and
        associated  with  the  internal  descriptor  `fd',   which   was
        returned by the `opendr' function. 

    IMPLEMENTATION

    SEE ALSO
        opendr(2)

    DIAGNOSTICS
        If  `fd'  is an invalid descriptor, or if no opened directory is
        currently associated with `fd', `closdr' returns with  no  error
        message. 






























                                    -1-

#-h- close           1214  asc  02-apr-82 16:55:13  v1.1 (sw-tools v1.1)


    Close (2)                  18-Aug-81                       Close (2)


    NAME
        Close - close (detach) a file

    SYNOPSIS
        subroutine close(fd)
        
        filedes fd

    DESCRIPTION
        `close'  closes  the  connection  between a file and the running
        program.   Any  write  buffers  are  flushed  and  the  file  is
        rewound. 
        
        `fd'  is  an internal file descriptor as returned from an `open'
        or `create' call. 
        

    IMPLEMENTATION
        `close' breaks the connection between the  program  and  a  file
        accessed  via  `open'  or  `create'.   If  necessary, the file's
        write buffer is flushed and the end of the  file  is  marked  so
        that  subsequent  reads  will  find  an EOF.  If a file has been
        opened  multiple  times  (that  is,  more  than   one   internal
        descriptor  has  been  assigned  to  a file), care is taken that
        multiple closes will not damage the file. 

    SEE ALSO
        open(2), create(2)

    DIAGNOSTICS
        If  the  file  descriptor  is  in  error,  the  routine   simply
        returns. 




















                                    -1-

#-h- create          1628  asc  02-apr-82 16:55:14  v1.1 (sw-tools v1.1)


    Create (2)                 20-Aug-81                      Create (2)


    NAME
        Create - create a new file (or overwrite an existing one)

    SYNOPSIS
        filedes function create( name, access)
        
        character name(ARB)
        integer access

    DESCRIPTION
        `create'  creates  a  new file from within a running program and
        connects  the  external  name  of  the  file  to   an   internal
        identifier   which  is  then  usable  in  subsequent  subroutine
        calls.  If the file already exists,  the  old  version  will  be
        overwritten.   In  this  case,  the  file  should  be  truncated
        immediately by `create'. 
        
        `name'  is  a  character  string  representing  a  pathname   or
        filename  in  whatever  format  is  used  by the local operating
        system.  It is passed as a character array terminated by an  EOS
        character. 
        
        `access'  is a integer descriptor for the type of access desired
        - WRITE, READWRITE or APPEND. 
        
        The value returned is a  "filedes"  internal  descriptor  to  be
        used in subsequent I/O calls on this file. 

    IMPLEMENTATION
        `create'  is  similar to `open' except that `create' generates a
        new file if it does not already exist,  whereas  `open'  returns
        an error on such occasions. 

    SEE ALSO
        open(2), close(2)

    DIAGNOSTICS
        The  function returns ERR if the file could not be created or if
        there are already too many files open. 













                                    -1-

#-h- ctoptr           742  asc  02-apr-82 16:55:15  v1.1 (sw-tools v1.1)


    Ctoptr (2)                 20-Aug-81                      Ctoptr (2)


    NAME
        Ctoptr - convert character string into linepointer

    SYNOPSIS
        subroutine ctoptr(buf, i, ptr)
        
        character buf(ARB)
        integer i
        linepointer ptr

    DESCRIPTION
        `ctoptr'  converts  the characters starting at location `buf(i)'
        into a linepointer value and stores the value  in  the  variable
        `ptr'.   The  value  of  `i' is incremented to point to the next
        available location in `buf'. 

    IMPLEMENTATION

    SEE ALSO
        ptreq(2), ptrcpy(2), note(2), seek(2), ptrtoc(2)

    DIAGNOSTICS
        none





























                                    -1-

#-h- cwdir            987  asc  02-apr-82 16:55:15  v1.1 (sw-tools v1.1)


    Cwdir (2)                  20-Aug-81                       Cwdir (2)


    NAME
        Cwdir - change current working directory

    SYNOPSIS
        integer function cwdir(name)
        
        character name(FILENAMESIZE)

    DESCRIPTION
        `cwdir'  changes the current working directory to that specified
        by  `name'.   `name'  is  a  character  string  representing   a
        pathname  or  whatever format is expected by the local operating
        system.  `name' is passed as a character array terminated by  an
        EOS character. 
        
        The  return value is either OK or ERR depending upon the success
        of the operation.  If the operation fails, the  current  working
        directory should be restored to the previous value. 

    IMPLEMENTATION

    SEE ALSO
        gwdir(2)

    DIAGNOSTICS
        A value of ERR is returned if the operation is unsuccessful. 


























                                    -1-

#-h- delarg           848  asc  02-apr-82 16:55:16  v1.1 (sw-tools v1.1)


    Delarg (2)                 20-Aug-81                      Delarg (2)


    NAME
        Delarg - mask the existence of specified command line argument

    SYNOPSIS
        subroutine delarg(n)
        
        integer n

    DESCRIPTION
        `delarg'  masks  the  existence  of  the  command  line argument
        number `n' so that subsequent calls to `getarg' do not see it. 

    IMPLEMENTATION
        `delarg' works  in  conjunction  with  `getarg'.   It  generally
        re-orders   indices   to  an  array  holding  the  command  line
        arguments fetched by `makarg'.  `delarg' is currently only  used
        by the shell. 

    SEE ALSO
        getarg(2), initst(2)

    DIAGNOSTICS
        If argument `n' does not exist, `delarg' simply returns. 





























                                    -1-

#-h- enbint          1594  asc  02-apr-82 16:55:17  v1.1 (sw-tools v1.1)


    Enbint (2)                 20-Aug-81                      Enbint (2)


    NAME
        Enbint - enable trapping of terminal interrupts

    SYNOPSIS
        subroutine enbint

    DESCRIPTION
        `enbint'  is  used  by  the  shell  to trap interrupt characters
        typed by the user at the terminal.  `enbint' assumes that  there
        will  be  a routine named `intsrv' which will be called whenever
        a terminal interrupt  is  typed.   The  canonical  semantics  of
        `intsrv'  is  to  kill  all sub-processes of the current process
        and return.  This generally  results  in  the  return  of  error
        notifications  to `spawn', which returns the error to the shell,
        after which the shell prompts for another command. 

    IMPLEMENTATION
        `enbint' has been implemented on only  three  machines,  and  is
        not  very  well defined.  In all of the implementations to date,
        `enbint' checks to make sure that the caller is  the  top  shell
        in  the  process  tree  associated with the user.  This prevents
        `enbint' from being generally called from  other  programs.   It
        is  hoped  that  a firmer specification for this routine will be
        available in the near future. 
        
        If this routine is difficult to implement, it may be left  as  a
        stub. 

    SEE ALSO
        intsrv(2)

    DIAGNOSTICS
        If  the  enabling  of  the  interrupt  cannot  be performed, the
        current implementations simply return. 


















                                    -1-

#-h- endst            904  asc  02-apr-82 16:55:18  v1.1 (sw-tools v1.1)


    Endst (2)                  20-Aug-81                       Endst (2)


    NAME
        Endst  -  perform  system-dependent cleanup and terminate ratfor
        program

    SYNOPSIS
        subroutine endst(status)
        
        integer status

    DESCRIPTION
        `endst'  is  normally  implicitly   called   when   the   `main'
        subroutine  executes  a  return.  `endst' closes all open files,
        performs any necessary system-dependent cleanup  and  terminates
        the program's execution. 
        
        If  it  is  possible,  endst  should communicate the termination
        status (OK/ERR/CHILD_ABORTED) to the outside world. 
        
        `endst' is also called by `error' to terminate the program. 

    IMPLEMENTATION

    SEE ALSO
        close(2), initst(2)

    DIAGNOSTICS
        none

























                                    -1-

#-h- filnfo           719  asc  02-apr-82 16:55:19  v1.1 (sw-tools v1.1)


    Filnfo (2)                 20-Aug-81                      Filnfo (2)


    NAME
        Filnfo - determine filename and access on open unit

    SYNOPSIS
        integer function filnfo( fd, file, access)
        
        filedes fd
        integer access
        character file(FILENAMESIZE)

    DESCRIPTION
        `filnfo'  returns  the  name and access of the file open on `fd'
        to the user.  If the unit is open, `filnfo' returns  OK  as  its
        value, otherwise it returns ERR. 

    IMPLEMENTATION

    SEE ALSO

    DIAGNOSTICS
        If  the  file  specified  by `fd' is not open, a value of ERR is
        returned. 






























                                    -1-

#-h- gdraux          2644  asc  02-apr-82 16:55:20  v1.1 (sw-tools v1.1)


    Gdraux (2)                 20-Aug-81                      Gdraux (2)


    NAME
        Gdraux - get auxiliary information about a file

    SYNOPSIS
        subroutine gdraux( fd, file, aux, date, fmtstr)
        
        character file(FILENAMESIZE), aux(MAXLINE), date(TCOLWIDTH)
        character fmtstr(ARB)
        filedes fd

    DESCRIPTION
        `gdraux'  retrieves  auxiliary  information on a particular file
        in a directory.  `fd' is the directory descriptor returned  from
        an  `opendr'  call  and  `file'  is  a  filename returned from a
        `gdrprm' call.  The auxiliary information  is  returned  in  the
        character  array  `aux', while `date' receives a "sortable" date
        string of size (TCOLWIDTH-1) which can be used to sort files  by
        significant date. 

        The  information  placed into `aux' is dependent upon the format
        string passed in `fmtstr'.   The  format  string  specifies  the
        output information as follows:

         b size of file in blocks (normally 512 characters)

         c size of file in characters

         m modification date and time (dd-mmm-yy hh:mm:ss)

         n filename

         o file owner's username

         p protection codes

         t file type (asc|bin|dir)

        The  `b',  `c',  `n'  and  `o'  options accept an integer prefix
        which specifies the field width to be used. 

    IMPLEMENTATION
        This is admittedly a stop-gap measure until a  more  useful  and
        penetrating  primitive  is  devised  to  permit the retrieval of
        extra information about a file.  The  only  utility  which  uses
        `gdraux'  currently is `ls', the directory lister.  The sortable
        date field  can  be  anything  that  the  primitive  implementor
        desires,  but  it  is  strongly  suggested that it be a sortable
        version of whatever significant date the operating system  keeps
        on  the  file,  so  that  the  "-t"  flag in `ls' performs up to
        specification. 


                                    -1-


    Gdraux (2)                 20-Aug-81                      Gdraux (2)


    EXAMPLES
        The verbose option of `ls' uses the format string "17n p  m  6b  o".

    SEE ALSO
        opendr(2), gdrprm(2)

    DIAGNOSTICS
        If  the  auxiliary  information  cannot  be   obtained   for   a
        particular  file, a message to that effect is returned in `aux',
        and `date' is given a value such that it  will  sort  out  first
        when sorting by date. 









































                                    -2-

#-h- gdrprm          1239  asc  02-apr-82 16:55:21  v1.1 (sw-tools v1.1)


    Gdrprm (2)                 20-Aug-81                      Gdrprm (2)


    NAME
        Gdrprm - get next filename from directory

    SYNOPSIS
        integer function gdrprm( fd, file)
        
        character file(FILENAMESIZE)
        filedes fd

    DESCRIPTION
        `gdrprm'  retrieves  the  next sequential filename from the open
        directory associated with `fd' and places it  in  the  character
        array  `file' as an EOS-terminated string.  If there is an error
        reading the directory or no more filenames are contained in  the
        directory,  a  value  of  EOF  is  returned;  otherwise,  OK  is
        returned.  The filenames are  retrieved  sequentially,  with  no
        particular order (alphabetic, by date, etc.) guaranteed. 

    IMPLEMENTATION
        If  there  are  lots  of noise characters (version numbers, null
        extensions, etc.), these are often stripped  from  the  filename
        before it is returned. 

    SEE ALSO
        gdraux(2), opendr(2)

    DIAGNOSTICS
        A  value of EOF is returned whenever there are no more directory
        entries or an error reading the directory is detected. 























                                    -1-

#-h- getarg          2712  asc  02-apr-82 16:55:23  v1.1 (sw-tools v1.1)


    Getarg (2)                 20-Aug-81                      Getarg (2)


    NAME
        Getarg - get command line arguments

    SYNOPSIS
        integer function getarg( n, array, maxsiz)
        
        character array(maxsiz)
        integer n, maxsiz

    DESCRIPTION
        `getarg'  gets  command  arguments  from  the  command  line  or
        control card and copies the `n'th  command  line  argument  into
        the   character  array  `array',  terminating  it  with  an  EOS
        character.   `maxsiz'  is  passed  as  the  maximum  number   of
        characters  `array'  is prepared to deal with (including the EOS
        character);  `getarg' truncates the  argument  if  necessary  to
        fit  into  the  space provided.  The number or characters in the
        argument (not including the EOS character) is  returned  in  the
        functional  call.   If there are less than `n' arguments, EOF is
        returned.  Calling `getarg' with  `n'  having  the  value  of  0
        should  result  in the return of the name by which the image was
        invoked. 

    IMPLEMENTATION
        The  implementation  of  'getarg'  may  be  quite  different  on
        different  operating  systems.   Some  systems  allow only upper
        case (or lower case) on the command line; they may  limit  size;
        they  may  not  even  provide access at all without considerable
        contortions. 
        
        When implementing `getarg', the designer  should  keep  in  mind
        that  a `delarg' will also be needed.  One possible design would
        be to create  a  routine  `makarg',  which  would  pick  up  the
        arguments  from  the  system,  convert  them  to  ascii strings,
        handle any upper-lower case escape conventions, and  store  them
        in  an  array.  `getarg' could then access this array, stripping
        off any quoted strings surrounding the  arguments,  and  passing
        them  along  to the user.  `delarg' could also access this array
        when removing reference to arguments. 
        
        If  it  is  absolutely  impossible  to  pick  up  command   line
        arguments  from  the  system, `getarg' could be taught to prompt
        the user for them. 
        
        When the shell is implemented, `getarg'  (or  perhaps  `makarg')
        may  have  to  be  altered  to read arguments as passed from the
        shell. 

    SEE ALSO
        initst(2), delarg(2)


                                    -1-


    Getarg (2)                 20-Aug-81                      Getarg (2)


    DIAGNOSTICS
        none


















































                                    -2-

#-h- getch           1323  asc  02-apr-82 16:55:24  v1.1 (sw-tools v1.1)


    Getch (2)                  20-Aug-81                       Getch (2)


    NAME
        Getch - read character from file

    SYNOPSIS
        character function getch( c, fd)
        
        character c
        filedes fd

    DESCRIPTION
        `getch'  reads  the  next  character  from the file specified by
        `fd'.  The character is returned in ASCII  format  both  as  the
        functional  return  and  in  the parameter `c'.  If the end of a
        line has been encountered, NEWLINE is returned.  If the  end  of
        the file has been encountered, EOF is returned. 
        
        If  the  unit  `fd'  is  a RAW or RARE terminal unit, then getch
        actually gets the next  character  from  the  terminal  WITH  NO
        ECHO. 

    IMPLEMENTATION
        Interspersed  calls  to  `getch'  and `getlin' should interleave
        properly.  A common implementation  is  to  have  `getlin'  make
        repeated calls to `getch'. 
        
        If  the  input  file  is  not  ASCII, characters are mapped into
        their ASCII equivalent. 

    SEE ALSO
        getlin(2), putch(2), putlin(2), stmode(2)

    DIAGNOSTICS
        If an error occurs during the reading of  the  file,  the  value
        ERR is returned. 


















                                    -1-

#-h- getdir          1406  asc  02-apr-82 16:55:25  v1.1 (sw-tools v1.1)


    Getdir (2)                 26-Oct-81                      Getdir (2)


    NAME
        Getdir - get directory string for known Tools directory

    SYNOPSIS
        subroutine getdir( key, dtype, name)
        
        character name(FILENAMESIZE)
        integer key, dtype

    DESCRIPTION
        `getdir'  returns  the  directory  string  for  any of the known
        Tools directories.   The  directory  string  is  returned  as  a
        character  array  terminated by an EOS character.  The format of
        `name' is  determined  by  the  value  of  `dtype',  with  LOCAL
        generating  a string in local format, and PATH causes a pathname
        directory string to be returned.  The valid values of `key'  and
        their corresponding directories are:
                  
                  BINDIRECTORY   ~bin/
                  USRDIRECTORY   ~usr/
                  TMPDIRECTORY   ~tmp/
                  LPRDIRECTORY   ~lpr/
                  MSGDIRECTORY   ~msg/
                  MANDIRECTORY   ~man/
                  SRCDIRECTORY   ~src/
                  INCDIRECTORY   ~inc/
                  LIBDIRECTORY   ~lib/
        
        If an invalid key is specified, a null string is returned. 

    IMPLEMENTATION

    SEE ALSO

    DIAGNOSTICS
        If an invalid key is specified, a null string is returned. 
















                                    -1-

#-h- getlin          2493  asc  02-apr-82 16:55:26  v1.1 (sw-tools v1.1)


    Getlin (2)                 21-Aug-81                      Getlin (2)


    NAME
        Getlin - get next line from file

    SYNOPSIS
        integer function getlin( line, fd)
        
        character line(MAXLINE)
        filedes fd

    DESCRIPTION
        `getlin'  copies  the  next  line from the file specified by the
        internal  identifier  `fd'  into  the  character  array  `line'.
        Characters  are  copied  until  a  NEWLINE character is found or
        until MAXLINE-1 characters have  been  copied.   The  characters
        are  returned  with  the  character  array  terminated by an EOS
        character. 
        
        `getlin'  returns  EOF  when  it  encounters   an   end-of-file,
        otherwise   it  returns  the  line  length  (including  NEWLINE,
        excluding EOS). 
        
        Interspersed calls to `getlin' and  `getch'  are  permitted  and
        should work properly. 

    IMPLEMENTATION
        If  the  external representation of characters is not ASCII, the
        characters are mapped into their ASCII equivalents. 
        
        `getlin' assumes a maximum size (MAXLINE) of the  array  `line'.
        If  the  input  line exceeds the limit, only the first "limit-1"
        characters are returned, with the remainder of the  line  either
        being ignored or returned on the next `getlin' call. 
        
        A  common  implementation is to have `getlin' call getch until a
        NEWLINE character is found (or the buffer size  is  exceeded  or
        EOF is reached). 
        
        If  the underlying disk structure is record oriented (as opposed
        to stream oriented), it may be more efficient to  have  `getlin'
        get  the next record in the same way that `getch' does, to avoid
        the overhead of repeated calls to `getch'. 
        
        Use of  `getlin'  on  RAW  terminal  units  is  of  questionable
        utility,  since  the  repeated `getch' calls perform a READ WITH
        NO ECHO, and would only terminate when the user types  a  CTRL/J
        (LINEFEED)  character.   All  utilities  which  use RAW I/O have
        their own line gathering routines. 

    SEE ALSO
        getch(2), putch(2), putlin(2), stmode(2)


                                    -1-


    Getlin (2)                 21-Aug-81                      Getlin (2)


    DIAGNOSTICS
        none


















































                                    -2-

#-h- getnow          1580  asc  02-apr-82 16:55:28  v1.1 (sw-tools v1.1)


    Getnow (2)                 20-Aug-81                      Getnow (2)


    NAME
        Getnow - determine current date and time

    SYNOPSIS
        subroutine getnow (now)
        
        integer now (7)

    DESCRIPTION
        'Getnow'  is  used to query the operating system for the current
        date and time.  The  requested  information  is  returned  in  a
        seven-word integer array, where:
             
             word 1 contains the year (e.g. 1980);
             word 2 contains the month (e.g. 9);
             word 3 contains the day (e.g. 25);
             word 4 contains the hour (e.g. 13);
             word 5 contains the minute (e.g. 39);
             word 6 contains the second (e.g. 14);
             word 7 contains the millisecond (e.g. 397).
        
        The  information  returned  by  'getnow'  may  be  used as-is or
        further useful processing may be done by 'fmtdat' or 'wkday'. 

    IMPLEMENTATION
        Operating systems generally have some mechanism for  picking  up
        the current date and time.  If yours has one, use it. 
        
        Getnow  is  not  critical to the implementation of the tools and
        can be left as a stub if the operating system cannot supply  the
        needed information. 

    ARGUMENTS MODIFIED
        now

    BUGS/DEFICIENCIES
        Some  systems  cannot obtain all the time information described.
        Array elements that cannot be filled default to zero. 

    SEE ALSO
        fmtdat(3), wkday(3), date(1)











                                    -1-

#-h- gettyp          1889  asc  02-apr-82 16:55:29  v1.1 (sw-tools v1.1)


    Gettyp (2)                 20-Aug-81                      Gettyp (2)


    NAME
        Gettyp - get type of file

    SYNOPSIS
        integer function gettyp( fd, type)
        
        filedes fd
        integer type

    DESCRIPTION
        `gettyp'  determines  whether  the  file  opened on unit `fd' is
        ascii characters (ASCII), local characters (LOCAL, if  different
        from  ASCII)  or  binary(BINARY).   The  type is returned as the
        value of  the  function  and  as  the  value  of  the  parameter
        `type'.  If the file is empty or new, ASCII is returned. 
        
        `fd'  is the file identifier returned from an `open' or `create'
        call. 

    IMPLEMENTATION
        When a file is opened (via a call to  `open'  or  `create'),  an
        internal  flag  is  usually  set  which specifies the file type.
        `gettyp' then simply reads the flag.  The  file  type  may  have
        been  determined  by  locating system information about the file
        or by actually reading  part  of  it  and  making  a  reasonable
        guess. 
        
        `gettyp'  is  called  by  the archiver to store a file's type in
        the archiver header.  The shell also uses `gettyp' to  determine
        whether  a  command  verb  given by the user represents a script
        file or an image file.  If the verb corresponds to  a  character
        file,  the  shell  spawns  itself  with  the  file as input.  If
        `gettyp' cannot be implemented on a particular  system,  a  stub
        returning  BINARY  should  be  placed in the library, which will
        force the user to execute script files in the following manner:

        % sh <script ... 

    SEE ALSO
        create(2), open(2)

    DIAGNOSTICS
        ERR is returned if the file descriptor is incorrect. 









                                    -1-

#-h- gtmode           639  asc  02-apr-82 16:55:30  v1.1 (sw-tools v1.1)


    Gtmode (2)                 20-Aug-81                      Gtmode (2)


    NAME
        Gtmode - determine mode of ratfor unit

    SYNOPSIS
        integer function gtmode(fd)
        
        filedes fd

    DESCRIPTION
        `gtmode'  determines  the mode of io on the unit `fd', returning
        one of the values RAW, RARE or  COOKED.   If  the  unit  is  not
        currently opened, the value ERR is returned. 

    IMPLEMENTATION

    SEE ALSO
        stmode(2)

    DIAGNOSTICS
        If `fd' is not currently open, a value of ERR is returned. 
































                                    -1-

#-h- gtzone           659  asc  02-apr-82 16:55:31  v1.1 (sw-tools v1.1)


    Gtzone (2)                 12-Mar-82                      Gtzone (2)


    NAME
        Gtzone - get time zone of requestor

    SYNOPSIS
        subroutine gtzone(buf)
        
        character buf(4)

    DESCRIPTION
        `gtzone'  returns  to the requestor the 3-character mnemonic for
        the time zone, terminated by an EOS character. 

    IMPLEMENTATION
        A typical way of implementing this routine is to  simply  strcpy
        a  string  into  the  buffer.   This  routine  may return a null
        string. 

    SEE ALSO
        

    DIAGNOSTICS
        






























                                    -1-

#-h- gwdir            848  asc  02-apr-82 16:55:31  v1.1 (sw-tools v1.1)


    Gwdir (2)                  20-Aug-81                       Gwdir (2)


    NAME
        Gwdir - get current working directory

    SYNOPSIS
        subroutine gwdir( name, dtype)
        
        character name(FILENAMESIZE)
        integer dtype

    DESCRIPTION
        `gwdir'   returns   the  current  working  directory  string  in
        `name'.  If `dtype' has the value LOCAL,  the  directory  string
        is  returned  in the form desired by the local operating system.
        If `dtype' has the  value  of  PATH,  the  directory  string  is
        returned  in  pathname format.  The directory string is returned
        as a character array terminated by an EOS character. 

    IMPLEMENTATION

    SEE ALSO
        cwdir(2)

    DIAGNOSTICS
        none




























                                    -1-

#-h- homdir           896  asc  02-apr-82 16:55:32  v1.1 (sw-tools v1.1)


    Homdir (2)                 20-Aug-81                      Homdir (2)


    NAME
        Homdir - return the home directory for this process

    SYNOPSIS
        subroutine homdir(home, dtype)
        
        character home(FILENAMESIZE)
        integer dtype

    DESCRIPTION
        `homdir'  returns  the  home  directory  string for the  current
        process.  If `dtype' has the value LOCAL, the  directory  string
        is  returned in the form native to the local operating system; a
        value of PATH causes it to be returned in pathname  format.   It
        is  returned  as  an EOS terminated string.  If this information
        cannot be determined, a stub which returns  an  EOS  in  home(1)
        will suffice. 

    IMPLEMENTATION

    SEE ALSO
        tooldr(3)

    DIAGNOSTICS
        none



























                                    -1-

#-h- initst          1572  asc  02-apr-82 16:55:33  v1.1 (sw-tools v1.1)


    Initst (2)                 20-Aug-81                      Initst (2)


    NAME
        Initst - initialize ratfor runtime environment

    SYNOPSIS
        subroutine initst

    DESCRIPTION
        Normally,   `initst'   is  implicitly  called  before  the  main
        subroutine of the user's  program  is  called.   `initst'  opens
        STDIN,  STDOUT and ERROUT, performing any redirections specified
        in the command line and  masking  those  redirections  from  the
        current  process.   The  remainder of the command line arguments
        are  prepared  for  retrieval  via  `getarg',  and   any   other
        system-dependent initialization is performed. 

    IMPLEMENTATION
        The  standard  I/O  units  are  generally  opened  in  the order
        ERROUT, STDIN  and  STDOUT.   If  an  error  occurs  during  the
        opening  of  ERROUT,  some  system-dependent method of reporting
        the error will need to be  used,  whereas  if  an  error  occurs
        while  opening  STDIN  or  STDOUT,  ERROUT can be used to report
        it.  The fetching of command line arguments from  the  operating
        system   is   in   the  domain  of  `initst',  as  well  as  any
        initializations  of  common  data  areas  needed  by  the  other
        primitive functions. 

    SEE ALSO
        endst(2), getarg(2), delarg(2)

    DIAGNOSTICS
        If  `initst' cannot function for some reason, the program should
        abort with a diagnostic message. 




















                                    -1-

#-h- intsrv          1176  asc  02-apr-82 16:55:34  v1.1 (sw-tools v1.1)


    Intsrv (2)                 20-Aug-81                      Intsrv (2)


    NAME
        Intsrv - interrupt service routine for tty interrupts

    SYNOPSIS
        subroutine intsrv

    DESCRIPTION
        `intsrv'  is  the  routine  called whenever a terminal interrupt
        character has been typed  after  `enbint'  has  been  called  to
        enable   the   trapping  of  these  interrupts.   The  canonical
        semantics of `intsrv'  is  to  kill  all  sub-processes  of  the
        current process.  Other functions may be embedded in `intsrv'. 

    IMPLEMENTATION
        `enbint'  and  `intsrv'  are not very well defined.  It is hoped
        that their definitions will become firmer in the near future. 
        
        If `enbint' has been implemented as a stub,  then  `intsrv'  may
        also be implemented as such. 

    SEE ALSO
        enbint(2)

    DIAGNOSTICS
        If  during  the  course  of  its  duties, `intsrv' encounters an
        error, it should notify the user  in  some  way.   This  may  be
        tricky, due to the asynchronous nature of its work. 

























                                    -1-

#-h- isatty          1052  asc  02-apr-82 16:55:35  v1.1 (sw-tools v1.1)


    Isatty (2)                 20-Aug-81                      Isatty (2)


    NAME
        Isatty - determine if file is an interactive device

    SYNOPSIS
        integer function isatty(fd)
        
        filedes fd

    DESCRIPTION
        `isatty'  returns the value YES if the file specified by `fd' is
        an interactive device, otherwise it returns NO.  `fd' is a  file
        identifier returned by a call to `open' or `create'. 

    IMPLEMENTATION
        When  a  file  is  opened, a flag is usually set indicating what
        device the file  is  associated  with.   `isatty'  usually  just
        reads this flag. 
        
        `isatty'  is  used  by several tools (`ls', `ar' and `users') to
        determine whether to format their output in columns or not.   It
        may  also  be  used  to determine whether to prompt for input or
        not. 

    SEE ALSO
        open(2), create(2)

    DIAGNOSTICS
        NO is returned if `fd' is in error. 
























                                    -1-

#-h- loccom          1537  asc  02-apr-82 16:55:36  v1.1 (sw-tools v1.1)


    Loccom (2)                 20-Aug-81                      Loccom (2)


    NAME
        Loccom - locate command along specified search path

    SYNOPSIS
        integer function loccom( in, spath, suffix, out)
        
        character in(FILENAMESIZE), out(FILENAMESIZE), spath(ARB)
        character suffix(ARB)

    DESCRIPTION
        `loccom'  searches  for  the command passed as an EOS-terminated
        character array in `in'  along  the  search  path  specified  by
        `spath',  returning  the  fully-qualified  file specification in
        the character array `out'.   For  each  element  of  the  search
        path,  all  suffixes passed in `suffix' are appended to `in' and
        an open at READ access is attempted.  The type of the file  thus
        found  (ASCII  or  BINARY)  is  returned  as  the  value  of the
        function.  If the command cannot be found, the value ERR  should
        be returned and the string `in' copied to `out'. 
        
        The structure of `spath' and `suffix' is:
        
        string_1@estring_2@e...string_N@e@n
        
        where  `@e'  represents  an  EOS character and `@n' represents a
        NEWLINE character.  A null directory  name  indicates  searching
        the current working directory. 

    IMPLEMENTATION

    SEE ALSO
        spawn(2)

    DIAGNOSTICS
        If  the  command cannot be found, a value of ERR is returned and
        the command string is returned in `out'. 
















                                    -1-

#-h- mailid          1314  asc  02-apr-82 16:55:37  v1.1 (sw-tools v1.1)


    Mailid (2)                 20-Aug-81                      Mailid (2)


    NAME
        Mailid - return username

    SYNOPSIS
        subroutine mailid(user)
        
        character user(USERSIZE)

    DESCRIPTION
        `mailid'  returns the name of the user of the current process as
        an EOS terminated string.  This name is then used  by  the  mail
        system. 

    IMPLEMENTATION
        Most  operating systems permit the user to determine some unique
        identifier of the  person  (or  account)  on  whose  behalf  the
        current  process  is  running.  The third field of each entry in
        the  mail  system's  database  file  is  dedicated  to  such  an
        identifier,  so  that mailid could be implemented by determining
        the identifier, opening ~msg/address and reading  records  until
        an  entry  with  that  identifier  is  found,  and returning the
        username  (field  one  of  the  record)  in  the  array  `user'.
        `mailid'  is  essential  for  the  correct  working  of the mail
        system. 

    SEE ALSO
        homdir(2)

    DIAGNOSTICS
        If the record could not be found in the database, some  nonsense
        username should be returned in `user'. 





















                                    -1-

#-h- mklocl           790  asc  02-apr-82 16:55:38  v1.1 (sw-tools v1.1)


    Mklocl (2)                 20-Aug-81                      Mklocl (2)


    NAME
        Mklocl   -   convert   string  to  fully  qualified  local  file
        specification

    SYNOPSIS
        call mklocl( in, out)
        
        character in(FILENAMESIZE), out(FILENAMESIZE)

    DESCRIPTION
        `mklocl' converts the input  filename  `in',  which  may  be  in
        pathname  format  or  a  partial  local file specification, to a
        fully qualified local file specification. 

    IMPLEMENTATION
        Initially, `mklocl' could be a stub, simply `scopy'ing  `in'  to
        `out'.  `mklocl' is used by the tools `fc' and `ld'. 

    SEE ALSO
        mkpath(2)

    DIAGNOSTICS
        none





























                                    -1-

#-h- mkpath           742  asc  02-apr-82 16:55:39  v1.1 (sw-tools v1.1)


    Mkpath (2)                 17-Nov-80                      Mkpath (2)


    NAME
        Mkpath - convert string to fully resolved path name

    SYNOPSIS
        call mkpath(in, out)
        
        character in(FILENAMESIZE), out(FILENAMESIZE)

    DESCRIPTION
        `mkpath'  converts  the  input  filename  `in',  which may be in
        pathname format or a partial  local  file  specification,  to  a
        fully qualified pathname. 

    IMPLEMENTATION
        Initially,  `mkpath'  could be a stub, simply `scopy'ing `in' to
        `out'.  `mkpath' is used by the tools `alist' and `ls'. 

    SEE ALSO
        mklocl(2)

    DIAGNOSTICS
        None






























                                    -1-

#-h- note            1718  asc  02-apr-82 16:55:41  v1.1 (sw-tools v1.1)


    Note (2)                   13-Nov-78                        Note (2)


    NAME
        Note - determine current file position

    SYNOPSIS
        stat = note (offset, fd)
        
        linepointer offset
        filedes fd
        integer stat returned as OK/ERR

    DESCRIPTION
        Note  determines  the  current  value  of  a  file's  read/write
        pointer.  The argument  "offset"  is  a  linepointer  that  will
        receive  the information.  Offset is maintained untouched by the
        user and passed to  "seek"  when  desiring  to  return  to  that
        particular location in the file. 

        Note  is  usually  used as the file is being written, picking up
        the pointer to the  end  of  the  file  before  each  record  is
        inserted there. 

        On  text  files  (e.g. those created by calls to putch, putlin),
        note is guaranteed to work at line  boundaries  only.   However,
        it should work anywhere on a file created by calls to writef. 

    IMPLEMENTATION
        Note  is  compatible  with whatever implementation is chosen for
        seek and the opening of files at READWRITE access. 

        Offset is a linepointer in which is stored  a  character  count,
        word   address,   block  and  record  address,  or  whatever  is
        appropriate for the local  operating  system.   Note  should  be
        taught   to   return  BEGINNING_OF_FILE  and  END_OF_FILE  where
        appropriate. 

        In the editor, note is called to locate  the  end  of  file  for
        subsequent writes. 

    SEE ALSO
        seek(2), readf(2), writef(2)

    DIAGNOSTICS
        None









                                    -1-

#-h- open            3091  asc  02-apr-82 16:55:43  v1.1 (sw-tools v1.1)


    Open (2)                   20-Aug-81                        Open (2)


    NAME
        Open - open an existing file

    SYNOPSIS
        filedes function open( name, access)
        
        character name(ARB)
        integer access

    DESCRIPTION
        `open'  attaches  an  existing  file  to  a  running program and
        associates the external file name with  an  internal  identifier
        for  use in other I/O routines.  Several opens of a file at READ
        access are permitted. 
        
        `name'  is  a  character  string  representing  a  pathname   or
        filename  in  whatever  format  is  used  by the local operating
        system.  It is passed as a character array  terminated  with  an
        EOS character. 
        
        `access'  is a descriptor for the type of access desired - READ,
        WRITE, READWRITE or APPEND. 
        
        The returned value of the function is a "filedes" descriptor  to
        be used in other I/O routines when referring to this file. 
        
        The  file  is  positioned at the beginning, unless APPEND access
        is  specified,  in  which  case  the  file   is   prepared   for
        extension. 

    IMPLEMENTATION
        `open'  connects  the  file  to the running program and performs
        those manipulations necessary to allow  reading  and/or  writing
        to  the  file.   An  internal descriptor is assigned to the file
        and subsequently used when  calling  other  primitives  such  as
        close, getch, putch, getlin, and putlin. 
        
        `open'  may  have to set up an internal I/O buffer for the file.
        It may also have to do an initial read  to  determine  the  file
        type  (ASCII  or BINARY).  Information about the file's type and
        teletype characteristics (YES or NO)  is  generally  maintained.
        This  information  is  then  made  available to the user via the
        `gettyp' and `isatty' functions. 
        
        `open' is generally taught to read characters of ASCII  type  as
        well   as  LOCAL  character  type  (if  different  from  ASCII).
        Translation of  characters  from  LOCAL  to  ASCII  is  done  in
        getch/getlin and vice versa for putch/putlin. 
        
        There  is  generally a limit to the maximum number of files open


                                    -1-


    Open (2)                   20-Aug-81                        Open (2)


        at any one time.  None of the tools require more than 7. 
        
        READWRITE access may cause problems.   Both `ed' and  `msg'  use
        this  access  on  their scratch buffer files.  If necessary, you
        may have to  implement  these  functions  by  opening  the  file
        twice, one at READ and once at WRITE access. 

    SEE ALSO
        create(2), close(2)

    DIAGNOSTICS
        `open'  returns  ERR  if the file does not exist, if the file is
        not readable/writable or if too many files are open. 







































                                    -2-

#-h- opendr          1431  asc  02-apr-82 16:55:44  v1.1 (sw-tools v1.1)


    Opendr (2)                 20-Aug-81                      Opendr (2)


    NAME
        Opendr - open directory for reading filenames

    SYNOPSIS
        filedes function opendr( name, fd))
        
        character name(FILENAMESIZE)
        filedes fd

    DESCRIPTION
        `opendr'  opens  the  specified  directory  for  READ access via
        `gdrprm'.  All write access to directories  is  implicitly  done
        with  the  `amove', `create' and `remove' primitives.  `name' is
        a character string representing the directory as a  pathname  or
        whatever  format is expected by the local operating system.  The
        name is passed  as  a  character  array  terminated  by  an  EOS
        character. 
        
        `fd'  is  a  "filedes"  descriptor  for  use  in other directory
        manipulation primitives.  The value returned by the function  is
        the value of `fd' or ERR. 

    IMPLEMENTATION
        `opendr'  is  the directory equivalent to `open' at READ access.
        It  prepares  the  directory  for  sequential  access   to   the
        filenames stored there. 

    SEE ALSO
        closdr(2), gdrprm(2), gdraux(2), amove(2), create(2), remove(2)

    DIAGNOSTICS
        A  value  of  ERR  is  returned  if  the  directory could not be
        opened, or too many directories have already been opened. 



















                                    -1-

#-h- prompt          2121  asc  02-apr-82 16:55:46  v1.1 (sw-tools v1.1)


    Prompt (2)                 20-Aug-81                      Prompt (2)


    NAME
        Prompt - get next line from file, prompting if a terminal

    SYNOPSIS
        integer function prompt( pstr, line, fd)
        
        character pstr(ARB), line(MAXLINE)
        filedes fd

    DESCRIPTION
        `prompt'  is  identical  to `getlin', with the exception that if
        `fd' corresponds to a terminal unit, the  prompt  string  `pstr'
        will  be  displayed before the read is performed.  The line read
        will be placed in `line' with the possible return  values  being
        identical  with  those of `getlin'.  If `fd' does not correspond
        to a terminal unit, `prompt' simply performs a `getlin'. 
        
        There is no implicit <CARRIAGE-RETURN,  LINEFEED>  pair  at  the
        end  of the prompt string (otherwise, there would be no need for
        this primitive).  If embedded NEWLINES are found in  the  prompt
        string,  they should result in <CARRIAGE-RETURN, LINEFEED> pairs
        being output on the terminal at the appropriate locations. 
        
        If after outputting the  prompt  string  and  reading  the  line
        `prompt'  sees  the  NEWLINE  character preceeded by an '@', the
        '@' should be replaced by a BLANK,  a  secondary  prompt  string
        consisting  of pstr(1) followed by an '_' (underscore) should be
        displayed, and another line fetched into the  buffer  after  the
        inserted  BLANK.   This  process  should  be  repeated until the
        NEWLINE  is  not  escaped,  or  MAXLINE  characters  have   been
        fetched. 

    IMPLEMENTATION
        The output of the prompt string is conditionalized upon
                               isatty(fd) == YES
        Since  `fd'  generally  is  associated  with  an  `open' at READ
        access, `prompt' may have to temporarily  open  a  unit  to  the
        terminal  at  WRITE  access  in  order  to  display  the  prompt
        string. 

    SEE ALSO
        putlin(2)

    DIAGNOSTICS
        none







                                    -1-

#-h- ptrcpy           509  asc  02-apr-82 16:55:47  v1.1 (sw-tools v1.1)


    Ptrcpy (2)                 20-Aug-81                      Ptrcpy (2)


    NAME
        Ptrcpy - copy linepointers

    SYNOPSIS
        subroutine ptrcpy( in, out)
        
        linepointer in, out

    DESCRIPTION
        `ptrcpy'   copies   the   linepointer   variable   `in'  to  the
        linepointer variable `out'. 

    IMPLEMENTATION

    SEE ALSO
        ptreq(2), note(2), seek(2)

    DIAGNOSTICS
        none

































                                    -1-

#-h- ptreq            622  asc  02-apr-82 16:55:48  v1.1 (sw-tools v1.1)


    Ptreq (2)                  20-Aug-81                       Ptreq (2)


    NAME
        Ptreq - determine if two linepointers are equal

    SYNOPSIS
        integer function ptreq( ptr1, ptr2)
        
        linepointer ptr1, ptr2

    DESCRIPTION
        `ptreq'  checks  for the equality of the two linepointers passed
        as `ptr1' and `ptr2'.  If they  are  equal,  the  value  YES  is
        returned, otherwise NO is returned. 

    IMPLEMENTATION

    SEE ALSO
        ptrcpy(2), note(2), seek(2)

    DIAGNOSTICS
        none
































                                    -1-

#-h- ptrtoc           923  asc  02-apr-82 16:55:48  v1.1 (sw-tools v1.1)


    Ptrtoc (2)                 20-Aug-81                      Ptrtoc (2)


    NAME
        Ptrtoc - format linepointer into characters

    SYNOPSIS
        integer function ptrtoc( ptr, buf, size)
        
        linepointer ptr
        character buf(size)
        integer size

    DESCRIPTION
        `ptrtoc'   generates   a   printable   character   string  which
        represents the value of the  linepointer  variable  `ptr'.   The
        characters  are  placed  in  the buffer `buf'.  If the formatted
        buffer would exceed `size' characters (including the EOS),  only
        `size'  characters  are  placed  in  `buf'.   The  length of the
        formatted string is returned as the value of the function. 

    IMPLEMENTATION

    SEE ALSO
        ptreq(2), ptrcpy(2), note(2), seek(2), ctoptr(2)

    DIAGNOSTICS
        none



























                                    -1-

#-h- putch           1224  asc  02-apr-82 16:55:49  v1.1 (sw-tools v1.1)


    Putch (2)                  20-Aug-81                       Putch (2)


    NAME
        Putch - write character to file

    SYNOPSIS
        subroutine putch( c, fd)
        
        character c
        filedes fd

    DESCRIPTION
        `putch'  writes  the  character  `c'  onto the file specified by
        `fd'.  If `c' is the NEWLINE character, the  appropriate  action
        is  taken  to  indicate  the end of the record on the file.  The
        character is assumed to be in  ASCII  format;  if  the  external
        representation is not ASCII, the necessary conversion is done. 
        
        If  fd'  corresponds  to  a  RAW  or  RARE  terminal  unit,  the
        character `c' is immediately written to  the  terminal  with  no
        interpretation   by   the  native  operating  system's  terminal
        handler. 

    IMPLEMENTATION
        Interspersed  calls  to  `putch'  and   `putlin'   should   work
        properly. 

    SEE ALSO
        putlin(2), getch(2), getlin(2), stmode(2)

    DIAGNOSTICS
        If  an  error  occurs  when  a  record is flushed, an ugly error
        message will appear on your terminal. 





















                                    -1-

#-h- putlin          1354  asc  02-apr-82 16:55:50  v1.1 (sw-tools v1.1)


    Putlin (2)                 20-Aug-81                      Putlin (2)


    NAME
        Putlin - output a line onto a given file

    SYNOPSIS
        subroutine putlin( line, fd)
        
        character line(ARB)
        filedes fd

    DESCRIPTION
        `putlin'  outputs  the  character  array  `line'  onto  the file
        specified  by  `fd'.   `line'  is  an  ASCII   character   array
        terminated  with  an  EOS  character.   NEWLINE  characters  are
        permitted in the array, with the effect of flushing  the  record
        since  the  last  NEWLINE  character.   If none is specified, no
        carriage-return (or end-of-record) is assumed.  If the  external
        representation  is  not ASCII, translation occurs before writing
        the record. 
        
        If `fd' is a RAW or RARE mode terminal unit, the  `line'  buffer
        is  written  immediately to the terminal, with no interpretation
        by the terminal driver. 

    IMPLEMENTATION
        Interspersed calls to `putch' and  `putlin'  are  permitted.   A
        common  implementation for COOKED mode units is to have `putlin'
        call `putch' until an EOS character is found. 

    SEE ALSO
        putch(2), getch(2), getlin(2), stmode(2)

    DIAGNOSTICS
        none



















                                    -1-

#-h- readf           1287  asc  02-apr-82 16:55:51  v1.1 (sw-tools v1.1)


    Readf (2)                  20-Aug-81                       Readf (2)


    NAME
        Readf - read from an opened file

    SYNOPSIS
        count = readf( buf, n, fd)
        
        character buf(ARB)
        integer n
        filedes fd
        integer count returned as count/EOF

    DESCRIPTION
        Readf  reads  `n'  bytes from the file opened on file descriptor
        `fd' into the array `buf'.  The bytes are placed  in  `buf'  one
        per  array  element.   Readf  is the typical way of doing binary
        reads on files.  Readf returns  the  number  of  bytes  actually
        read.   In most cases, this is equal to `n'.  However, it may be
        less if an EOF has been  encountered  or  if  `fd'  specified  a
        device  such  as  a  terminal  where  less  than  `n' bytes were
        input. 

    IMPLEMENTATION
        Readf is  the  typical  way  of  implementing  binary  I/O.   Do
        whatever  is  necessary  on your system to allow users to get at
        the file directly. 
        
        If reasonable, design readf  to  work  properly  in  conjunction
        with getch and getlin. 

    SEE ALSO
        writef(2), getch(2), putch(2)

    DIAGNOSTICS
        none


















                                    -1-

#-h- remark          1147  asc  02-apr-82 16:55:52  v1.1 (sw-tools v1.1)


    Remark (2)                 20-Aug-80                      Remark (2)


    NAME
        Remark - print single-line message

    SYNOPSIS
        subroutine remark(messag)
        
        character messag(ARB)

    DESCRIPTION
        `remark'  writes  the  message  onto  the  standard  error  file
        ERROUT.  A NEWLINE is always generated, even though one may  not
        appear in the message. 
        
        The  `messag'  array  is generally a Fortran hollerith string in
        the format generated by the  Ratfor  quoted  string  capability.
        It  may  also  be  an  character  array  terminated  with an EOS
        character. 

    IMPLEMENTATION
        If a quoted string  is  used  as  the  argument  to  remark,  it
        should,  by  convention,  be terminated by a PERIOD (`.').  This
        permits all implementations to locate the end of the  string  to
        print.   If  a  NEWLINE character is not found at the end of the
        string, one must be `putch'ed to ERROUT. 

    SEE ALSO
        putlin(2)

    DIAGNOSTICS
        none






















                                    -1-

#-h- remove          1197  asc  02-apr-82 16:55:53  v1.1 (sw-tools v1.1)


    Remove (2)                 20-Aug-81                      Remove (2)


    NAME
        Remove - delete a file from the file system

    SYNOPSIS
        integer function remove(name)
        
        character name(FILENAMESIZE)
        
        return(OK/ERR)

    DESCRIPTION
        `remove'  deletes  a file from the file system when invoked from
        a running program.  `name' is a character string representing  a
        pathname  or  filename  in  whatever format is used by the local
        operating system.  It is passed as a character array  terminated
        by an EOS character. 

        The  function value returned should be OK/ERR depending upon the
        success of the delete operation.   Deletion  of  a  non-existent
        file should result in a return of OK. 

    IMPLEMENTATION
        The  file  to  be  removed  need  not be opened before remove is
        called.  If the file is currently open on  other  units,  remove
        should display an error message. 

    SEE ALSO
        open(2), close(2), create(2)

    DIAGNOSTICS
        If an error occurs, a value of ERR is returned. 





















                                    -1-

#-h- scratf          1746  asc  02-apr-82 16:55:54  v1.1 (sw-tools v1.1)


    Scratf (2)                 20-Aug-81                      Scratf (2)


    NAME
        Scratf - generate unique scratch file name

    SYNOPSIS
        subroutine scratf( seed, name)
        
        character seed(ARB), name(FILENAMESIZE)

    DESCRIPTION
        `scratf'  is used to generate unique scratch file names.  `seed'
        is passed as a character array terminated by an  EOS  character,
        and  will  be  used  to  make this scratch file name unique with
        respect to other scratch files generated by this  process.   The
        scratch  file  name  generated  is  returned  in  `name'  as  an
        EOS-terminated  character  array.   Only  the  first  three  (3)
        characters  of  `seed'  are  guaranteed  to be used, so the user
        should be sure that all `seed's used in the program  are  unique
        in the first three characters. 

    IMPLEMENTATION
        `scratf'  is  used to avoid conflicts which occur when more than
        one user is logged in under a single  user  or  directory  name.
        The  optimal  implementation  would  be  to return an absolutely
        unique file name based upon `seed', which can often be  achieved
        via  some  manipulation of the process name or id.  It is common
        practice to have  all  scratch  files  generated  by  the  tools
        reside in a common scratch file directory. 
        
        On  single-user  systems  or systems which support the notion of
        "local files", `scratf' can simply return `seed' as `name'. 

    SEE ALSO
        getdir(2)

    DIAGNOSTICS
        If the file name could not be generated,  a  message  should  be
        printed. 















                                    -1-

#-h- seek            1062  asc  02-apr-82 16:55:55  v1.1 (sw-tools v1.1)


    Seek (2)                   20-Aug-81                        Seek (2)


    NAME
        Seek - move read/write pointer

    SYNOPSIS
        subroutine seek( addres, fd)
        
        linepointer addres
        filedes fd

    DESCRIPTION
        `seek'  positions  the  file  specified by `fd' for a subsequent
        read or write beginning at `addres'.  `addres' is a variable  of
        type  linepointer containing the system-dependent address of the
        record, which was originally obtained by a call to `note'. 
        
        If a write is performed after a `seek', the  file  is  truncated
        after  that  line,  due  to  the sequential nature of the Tool's
        I/O. 

    IMPLEMENTATION
        `seek' is generally used on files opened  at  READWRITE  access.
        The  units  of  `addres'  are  chosen  to  be  whatever  is most
        appropriate for the system involved. 

    SEE ALSO
        note(2), ptrcpy(2), ptreq(2)

    DIAGNOSTICS
        none























                                    -1-

#-h- sleep            813  asc  02-apr-82 16:55:56  v1.1 (sw-tools v1.1)


    Sleep (2)                  20-Aug-81                       Sleep (2)


    NAME
        Sleep - stop process for period of time

    SYNOPSIS
        subroutine sleep(secnds)
        
        integer secnds

    DESCRIPTION
        `sleep'  causes  the  current  process to suspend itself for the
        period of time specified in  the  parameter  `secnds'.   Control
        resumes  at  the next instruction after the call sleep statement
        when the time period has elapsed. 

    IMPLEMENTATION
        The only utility which uses `sleep' is `sched'.   Therefore,  it
        is  not  necessary,  although  such  a  facility  will make many
        real-time tasks easier to solve

    SEE ALSO

    DIAGNOSTICS
        none





























                                    -1-

#-h- spawn           4472  asc  02-apr-82 16:55:58  v1.1 (sw-tools v1.1)


    Spawn (2)                  20-Aug-81                       Spawn (2)


    NAME
        Spawn - initiate sub-process

    SYNOPSIS
        integer function spawn( image, args, pid, waitfl)
        
        character image(FILENAMESIZE), args(ARGBUFSIZE), pid(PIDSIZE), waitfl

    DESCRIPTION
        `spawn'  causes  the initiation of a sub-process.  `image' is an
        EOS-terminated character array specifying the  filename  of  the
        image  to  be  initiated,  in  either  pathname  or  local  file
        format. 
        
        `args' is a character array specifying the command  line  to  be
        passed  to  the  sub-process.   The  name by which the image was
        invoked should be the first word in  the  argument  buffer.   If
        the  string  passed  in  `image' is equal to the string "local",
        then `args' should contain the native command line to be  passed
        to the local command language interpreter. 
        
        If  `waitfl'  ==  WAIT  &  equal(image,  "local") == NO, `spawn'
        should scan `args' for redirection of  STDOUT  and  ERROUT.   If
        either  of  these  units  are  not redirected, the corresponding
        unit should be closed, and an APPEND redirection  to  that  file
        should  be  formatted into `args' for the child.  When the child
        process completes,  the  unit  should  be  re-opened  at  APPEND
        access,  thus  permitting  the correct interleaving of output on
        these units between parent and child processes. 
        
        `pid' is an array to receive  the  process  id  of  the  spawned
        sub-process.   This id may then be used in other process control
        primitives. 
        
        `waitfl' is a flag indicating whether the parent process  wishes
        to  synchronize  its  execution  with  the  termination  of  the
        sub-process.  If the value of WAIT is  specified,  `spawn'  will
        not  return  control  until  the  sub-process has completed.  If
        NOWAIT is specified, `spawn' immediately returns to  the  caller
        (for  use  with  real  pipes).  Processes spawned with this flag
        are required to exit when the parent process exits.   If  BACKGR
        is  specified,  the sub-process is spawned in the background and
        control is  immediately  returned  to  the  caller.   Background
        process  come  to  life  with the standard I/O units directed to
        the null device, and have an existence  totally  independent  of
        that  of  the  parent.   It  is  common  to  have the background
        processes run at a lower priority than foreground processes. 
        
        If an error occurs during the  initiation  of  the  sub-process,
        ERR  is  returned  to  the  user.  If the sub-process abnormally


                                    -1-


    Spawn (2)                  20-Aug-81                       Spawn (2)


        exits when WAIT has been specified, a value of CHILD_ABORTED  is
        returned.  Otherwise, OK is returned. 

    IMPLEMENTATION
        `spawn'  is  normally the most difficult primitive to implement.
        A few of the major obstacles which must be overcome are:
        
          1. Does the operating  system  permit  a  running  process  to
             spawn   a   sub-process?   If  it  provides  a  multi-user,
             interactive environment, it most certainly  could,  but  it
             may not be common knowledge as to how to do it. 
             
          2. Once  one  has  determined  how to spawn the process, it is
             necessary  to  determine  how  to  control  it.    If   the
             operating  system  does  not  provide  any  synchronization
             methods, they must be implemented. 
             
          3. Finally,  one  must  determine  how  to   communicate   the
             arguments  and  environment information to the sub-process.
             This   generally   entails   an    exploration    of    the
             system-provided  interprocess-communication mechanisms, and
             often requires the invention of better ones. 

    SEE ALSO

    DIAGNOSTICS
        A  value  of  ERR  is  returned  if  an  error   occurs   during
        sub-process  initiation.   If  the  sub-process exits abnormally
        when `waitfl' had a value of WAIT, CHILD_ABORTED is returned. 























                                    -2-

#-h- stmode          1277  asc  02-apr-82 16:55:59  v1.1 (sw-tools v1.1)


    Stmode (2)                 20-Aug-81                      Stmode (2)


    NAME
        Stmode - change mode on terminal unit to RAW/RARE/COOKED

    SYNOPSIS
        integer function stmode( fd, mode)
        
        filedes fd
        integer mode

    DESCRIPTION
        `stmode'  is  used  to  change  an  open ratfor unit, `fd', to a
        different mode  of  operation,  as  specified  by  `mode'.   The
        default  mode  when  a  unit is opened or created is COOKED.  If
        the unit corresponds to an interactive device, it  is  permitted
        to  change the mode to RARE or RAW.  The value to which the mode
        is set is returned as the value of the function. 

    IMPLEMENTATION
        `stmode' usually sets a flag for the particular unit, such  that
        future  `getch'  and `putch' calls on the unit will be performed
        correctly  for  the  given  mode  of  operation.   If  the  unit
        specified  is  not  currently associated with a particular file,
        the value of ERR will be returned. 

    SEE ALSO
        getch(2), putch(2)

    DIAGNOSTICS
        If the unit is not currently associated with a file,  the  value
        of ERR is returned. 






















                                    -1-

#-h- symbols        12201  asc  02-apr-82 16:56:02  v1.1 (sw-tools v1.1)


Symbols (2)                    18-Aug-81                     Symbols (2)


NAME
    Symbols - standard symbol definitions

#================= GENERAL SYMBOL DEFINITIONS =================

# General definitions for software tools
# Should be put on a file named 'symbols'
# Used by all the tools; read automatically by preprocessor


#   Many of these symbols may change for your particular machine.
#   The values provided are intended as guidelines, and may
#   well serve you adequately, but don't hesitate to change them if
#   necessary.

# In particular, the following might have to change for your system:
#         TERMINAL_IN
#         TERMINAL_OUT
#         MAXLINE
#         FILENAMESIZE
#         DRIVER    and    DRETURN
#         MAXOFILES
#         character

#   Also, watch out for the following definitions, which
#   may conflict with the Fortran operators on your system:
#       AND         OR        NOT


#  Many of the definitions will be used in character variables.
#  They must be defined to be something other than a valid ascii
#  character--such as a number > 255 or a negative number.
#  If you have defined "character" to be "integer", then you may
#  use either a very large number or a small negative number.
#  If you have defined "character" to be something like an 8-bit
#  signed field, you'll need to use negative numbers.
#  Use of a standard integer (whatever is the default size on your
#  machine) is STRONGLY recommended, despite the apparent waste of
#  storage.


# The following constants affect conditional pre-processing

define(VAX_VMS,)                # Define CPU and Operating system.
define(LARGE_ADDRESS_SPACE,)    # this is defined if the user has at least
                                # 18 address bits for use
define(TREE_STRUCT_FILE_SYS,)   # this is defined is the file system is
                                # tree structured
define(SORTED_DIRECTORIES,)     # defined if the directories are inherently
                                # sorted





Symbols (2)                    18-Aug-81                     Symbols (2)



# ASCII control character definitions:

define(NUL,0)
define(SOH,1)
define(STX,2)
define(ETX,3)
define(EOT,4)
define(ENQ,5)
define(ACK,6)
define(BEL,7)
define(BS,8)
define(HT,9)
define(LF,10)
define(VT,11)
define(FF,12)
define(CR,13)
define(SO,14)
define(SI,15)
define(DLE,16)
define(DC1,17)
define(DC2,18)
define(DC3,19)
define(DC4,20)
define(NAK,21)
define(SYN,22)
define(ETB,23)
define(CAN,24)
define(EM,25)
define(SUB,26)
define(ESC,27)
define(FS,28)
define(GS,29)
define(RS,30)
define(US,31)
define(SP,32)
define(DEL,127)

# Synonyms for ASCII control characters

define(BACKSPACE,8)
define(BELL,7)
define(BLANK,32)
define(CARRIAGE_RETURN,13)
define(NEWLINE,10)
define(RUBOUT,127)
define(TAB,9)

# Printable ASCII characters:






Symbols (2)                    18-Aug-81                     Symbols (2)


define(ACCENT,96)
define(AMPER,38)        # ampersand
define(AMPERSAND,AMPER)
define(AND,AMPER)
define(ATSIGN,64)
define(BACKSLASH,92)
define(BANG,33)         # exclamation mark
define(BAR,124)
define(BIGA,65)
define(BIGB,66)
define(BIGC,67)
define(BIGD,68)
define(BIGE,69)
define(BIGF,70)
define(BIGG,71)
define(BIGH,72)
define(BIGI,73)
define(BIGJ,74)
define(BIGK,75)
define(BIGL,76)
define(BIGM,77)
define(BIGN,78)
define(BIGO,79)
define(BIGP,80)
define(BIGQ,81)
define(BIGR,82)
define(BIGS,83)
define(BIGT,84)
define(BIGU,85)
define(BIGV,86)
define(BIGW,87)
define(BIGX,88)
define(BIGY,89)
define(BIGZ,90)
define(CARET,94)
define(COLON,58)
define(COMMA,44)
define(DASH,45)         #same as MINUS
define(DIG0,48)
define(DIG1,49)
define(DIG2,50)
define(DIG3,51)
define(DIG4,52)
define(DIG5,53)
define(DIG6,54)
define(DIG7,55)
define(DIG8,56)
define(DIG9,57)
define(DOLLAR,36)
define(DQUOTE,34)





Symbols (2)                    18-Aug-81                     Symbols (2)


define(EQUALS,61)
define(ESCAPE,ATSIGN)           # escape char for ch, find, tr, ed, and sh.
define(GREATER,62)
define(LBRACE,123)
define(LBRACK,91)
define(LESS,60)
define(LETA,97)
define(LETB,98)
define(LETC,99)
define(LETD,100)
define(LETE,101)
define(LETF,102)
define(LETG,103)
define(LETH,104)
define(LETI,105)
define(LETJ,106)
define(LETK,107)
define(LETL,108)
define(LETM,109)
define(LETN,110)
define(LETO,111)
define(LETP,112)
define(LETQ,113)
define(LETR,114)
define(LETS,115)
define(LETT,116)
define(LETU,117)
define(LETV,118)
define(LETW,119)
define(LETX,120)
define(LETY,121)
define(LETZ,122)
define(LPAREN,40)
define(MINUS,45)
define(NOT,BANG)        # used in pattern matching; choose ~, ^, or !
define(OR,BAR)
define(PERCENT,37)
define(PERIOD,46)
define(PLUS,43)
define(QMARK,63)
define(RBRACE,125)
define(RBRACK,93)
define(RPAREN,41)
define(SEMICOL,59)
define(SHARP,35)
define(SLASH,47)
define(SQUOTE,39)
define(STAR,42)
define(TAB,9)
define(TILDE,126)





Symbols (2)                    18-Aug-81                     Symbols (2)


define(UNDERLINE,95)


# Ratfor language extensions:

define(andif,if)
define(ARB,1000)
define(character,logical*1)     # define character data type
define(CHARACTER,character)
define(DS_DECL,integer $1($2);character c$1(arith($2,*,CHAR_PER_INT));
equivalence (c$1(1),$1(1));common/cdsmem/$1)
define(PB_DECL,integer pbp, pbsize; character pbbuf($1);
common/cpback/pbp, pbsize, pbbuf)
define(cvt_to_cptr,(CHAR_PER_INT*($1-1)+1))     # convert pointer to char ptr
define(elif,else if)
define(filedes,integer)         # file descriptor/designator data type
define(FILEDES,filedes)
define(IS_DIGIT,(DIG0<=$1&$1<=DIG9))    # valid only for ASCII!
define(IS_LETTER,(IS_UPPER($1)|IS_LOWER($1)))
define(IS_LOWER,(LETA<=$1&$1<=LETZ))
define(IS_UPPER,(BIGA<=$1&$1<=BIGZ))
define(long_real,double precision)
define(linepointer,real*8)
define(NULLPOINTER,-1)
define(LINEPTRSIZE,MAXCHARS)
define(pointer,integer)
define(POINTER,integer)



# Input/output modes:

define(APPEND,4)
define(PRINT,5)         # print file access
define(READ,1)
define(READWRITE,3)
define(WRITE,2)


# Standard input/output ports:

define(ERROUT,3)        # standard error file
define(STDERR,ERROUT)
define(STDIN,1)         # standard input file
define(STDOUT,2)        # standard output file


# TERMINAL_IN and TERMINAL_OUT are the names of the I/O channels
# from and to the user's terminal, respectively.  It's highly likely
# there is no such thing on your system; in this case, simply invent





Symbols (2)                    18-Aug-81                     Symbols (2)


# a name that is not likely to conflict with any file name.
# For example, the VAX/VMS version of the tools uses "TT", the RSX/11M
# version uses "TI:", the DEC 10 version uses "tty:", and the Prime
# version uses "/dev/tty".
# Note that you must make the 'open' primitive recognize this name
# and provide access to the terminal accordingly.

define(TTY_NAME,"TT")
define(TERMINAL_IN,TTY_NAME)
define(TERMINAL_OUT,TTY_NAME)


# Manifest constants included for readability and modifiability:

define(ALPHA,-9)
define(ASCII,12)                # flag for ascii character file
define(BEGINNING_OF_FILE,-2)    # flag to seek for positioning at
                                # the beginning of a file
define(BINARY,60)               # flag for indicating binary file
define(CHILD_ABORTED,101)       # possible status return from spawn
define(DIGIT,2)
define(END_OF_FILE,-1)          # flag to seek for positioning at
                                # end of file
define(EOF,-1)
define(EOS,0)
define(ERR,-3)
define(HUGE,30000)              # some arbitrarily large number
define(LAMBDA,0)                # end of list marker
define(LETTER,1)
define(LOCAL,6)                 # flag for local-type character file
define(NO,0)
define(NOERR,0)                 # flag for successful completion
define(OK,0)                    # success flag
define(PATH,5)                  # type == PATH
define(TMO,-4)                  # error return for timeout (dpm 8-Jun-81)
define(USERSIZE,20)             # size of username returned by userid
define(YES,1)


# Size limiting definitions for important objects:

define(FILENAMESIZE,100)        # max characters in file name
                                # (including EOS)
define(MAXARG,MAXLINE)          # max size of command line argument
define(MAXARGS,25)              # some tools require this for max no of args
define(MAXCHARS,20)             # max nbr of chars when converting
                                # from integers to characters
                                # (used by putint, outnum, etc.)
define(MAXLINE,512)             # normal size of line buffers;
                                # must be at least 1 more than MAXCARD





Symbols (2)                    18-Aug-81                     Symbols (2)


define(MAXCARD,arith(MAXLINE,-,1))
define(MAXNAME,FILENAMESIZE)    # max size of file name
define(MAXOFILES,15)            # max nbr opened files allowed at a time
define(MAXPAT,128)              # max size of encoded patterns
                                # (used in string matching)
define(NCHARS,33)               # number of special characters


# Machine-dependent parameters: (VAX)

define(BITS_PER_CHAR,8)
define(BITS_PER_WORD,32)        # (dpm 8-Jun-81)
define(CHARS_PER_WORD,4)        # (dpm 8-Jun-81)
define(CHAR_PER_INT,4)
define(MAX_INTEGER,1073241823)  # 2**30 - 1 (dpm 8-Jun-81)
define(MIN_INTEGER,-1073241824) # -2**30 - 1 (dpm 8-Jun-81)
define(MAX_REAL_EXP,38)
define(MIN_REAL_EXP,-37)        # (dpm 8-Jun-81)
define(REAL_PRECISION,7)        # (dpm 8-Jun-81)


# DRIVER is defined as those things you need to do to start a Software
# Tools program running.  The following is a common approach, but you
# may have to change it (for example, by adding a "program" card).
# Many machines will require no special driver procedure other than
# the call to 'initst'.

define(DRIVER,subroutine main # $1)

# DRETURN is used to finish up a Software Tools program:

define(DRETURN,return)          # (returning from subroutine defined in DRIVER)


# Definitions for 'spawn' primitive (if implemented):

define(WAIT,LETW)               # wait for subprocess to complete
define(NOWAIT,LETN)             # control returns as soon as
                                # subprocess starts
define(BACKGR,LETB)             # spawning a background process
define(PIDSIZE,9)
define(ARGBUFSIZE,512)


# rawmode io definitions

define(COOKED,0)                # line-at-a-time (record) io
define(RAW,1)                   # char-at-a-time (unfiltered) io
define(RARE,2)                  # char-at-a-time (with interrupts) io






Symbols (2)                    18-Aug-81                     Symbols (2)


# definitions for obtaining directory strings

define(BINDIRECTORY,1)
define(USRDIRECTORY,2)
define(TMPDIRECTORY,3)
define(LPRDIRECTORY,4)
define(MSGDIRECTORY,5)
define(MAILDIRECTORY,5)
define(MANDIRECTORY,6)
define(SRCDIRECTORY,7)
define(INCDIRECTORY,8)
define(LIBDIRECTORY,9)

# definitions needed for directory operations

define(TCOLWIDTH,24)            # width of date string returned by gdraux
define(MAXDIRECTS,10)           # max number of path fields in file spec

# definitions needed for double integer manipulations

define(initdi,{$1(1) = 0; $1(2) = 0})
define(incrdi,{$1(2) = $1(2) + 1; if($1(2) >= 10000)
{$1(1) = $1(1) + 1; $1(2) = 0}})
define(decrdi,{$1(2) = $1(2) - 1; if($1(2) < 0)
{$1(1) = $1(1) - 1; $1(2) = 9999}})
define(adddi,{$2(1) = $2(1) + $1(1); $2(2) = $2(2) + $1(2);
if ($2(2) >= 10000){$2(1) = $2(1) + 1; $2(2) = $2(2) - 10000}})
define(subdi,{$2(1) = $2(1) - $1(1); $2(2) = $2(2) - $1(2);
if ($2(2) < 0){$2(1) = $2(1) - 1; $2(2) = $2(2) + 10000}})

# It may be necessary to add special definitions; for example
# names of important directories, substitute routine names for
# Software Tools primitives that conflict with local subprograms,
# etc.

define(putc,putch($1,STDOUT))
define(getc,ifelse($1,,getch,getch($1,STDIN)))
define(putdec,putint($1,$2,STDOUT))
define(index,indexx)
define(INDEX,index)
define(SS_NORMAL,1)
define(BOTH_SUFFIX,".sh@e.exe@e@n")
define(IMAGE_SUFFIX,".exe@e@n")
define(NO_SUFFIX,"@e@n")
define(mkuniq,scratf)
# special definitions for pwait
define(ANDWAIT,51)
define(ORWAIT,50)
define(TERMSGSIZE,21)





#-h- trmlst          1005  asc  02-apr-82 16:56:05  v1.1 (sw-tools v1.1)


    Trmlst (2)                 12-Mar-82                      Trmlst (2)


    NAME
        Trmlst - list terminal a user is logged onto

    SYNOPSIS
        integer function trmlst(user, tlist)
        
        character user(ARB), tlist(ARB)
        
        return(number of terminals found)

    DESCRIPTION
        `trmlst'  scans  the  system for the names of all terminals upon
        which  `user'  is  logged  onto,  and  returns  the   names   as
        blank-separated  tokens  in  the  array  `tlist'.  The number of
        terminals found is returned as the value of the function. 

    IMPLEMENTATION
        As for `brdcst', this may be a difficult  function  to  provide.
        It  may be safely implemented as a stub returning 0.  It is only
        used by `sndmsg' and `mail' to notify users of mail. 

    SEE ALSO
        brdcst(2)

    DIAGNOSTICS
        Returns 0 if the user is not currently logged in. 


























                                    -1-

#-h- writef          1133  asc  02-apr-82 16:56:06  v1.1 (sw-tools v1.1)


    Writef (2)                 20-Aug-81                      Writef (2)


    NAME
        Writef - write to an opened file

    SYNOPSIS
        count = writef( buf, n, fd)
        
        character buf(ARB)
        integer n
        filedes fd
        integer count returned as count/ERR

    DESCRIPTION
        Writef  writes `n' bytes from the array `buf' to the file opened
        on file descriptor `fd'.  Writef is the  typical  way  of  doing
        binary writes to files. 
        
        Writef  returns  the  number of bytes actually written.  In most
        cases, this is  equal  to  `n'.   If,  however,  a  write  error
        occurs, writef returns ERR. 

    IMPLEMENTATION
        Writef  is  the  typical  way  of  implementing  binary I/O.  Do
        whatever is necessary on your system to allow users  to  get  at
        the file directly. 
        
        If  reasonable,  design  writef  to work properly in conjunction
        with putch and putlin. 

    SEE ALSO
        readf(2), putch(2), putlin(2)

    DIAGNOSTICS
        none



















                                    -1-

