8.14  EXPUNGE Command

   Command:  (EXPUNGE tid directory-pathname)

   Response: (EXPUNGE tid server-storage-units-freed)

   EXPUNGE causes the directory specified by pathname to be expunged.
   Expunging means that any files that have been soft deleted are to be
   permanently removed.

   For file systems that do not support soft deletion, the command is to
   be ignored; a success command response is sent, but no action is
   performed on the file system.  In this case, the number-of-server-
   storage-units-freed return value should be omitted.

   directory-pathname is a required string argument in the directory
   pathname format; it must refer to a directory on the server file
   system, and not to a file.  See the section "Syntax of File and
   Directory Pathname Arguments", section 7.4.

   The return value server-storage-units-freed is an integer specifying
   how many records, blocks, or whatever unit is used to measure file
   storage on the server host system, were recovered.  This return value
   should be omitted if the server does not know how many storage units
   were freed.

   The protocol does not define whether directory-pathname is really a
   pathname as directory or a wildcard pathname of files to be expunged.
   The protocol does not define whether or not wildcards are permitted,
   or required to be supported, in the directory portion of the pathname
   (representing an implicit request to expunge many directories).

8.15  FILEPOS Command

   Command:  (FILEPOS tid handle position resync-uid)

   Response: (FILEPOS tid)

   FILEPOS sets the file access pointer to a given position, relative to
   the beginning of the file.  FILEPOS is used to indicate the position
   of the next byte of data to be transferred.

   The handle indicates the file to be affected.  handle must be a data
   channel handle for a data stream opening, or a direct file identifier
   for a direct access opening.  Both handle and position are required
   arguments.

   position is an integer indicating to which point in the file the file
   access pointer is to be reset.  position is either a byte number
   according to the current byte size being used, or characters for
   character openings.  Position zero is the beginning of the file.  If
   this is a character opening, position is measured in server units,
   not in NFILE character set units.

   If the FILEPOS command is given on an input data channel (that is, a
   data channel currently sending data from server to user), the
   affected data channel must be resynchronized after the FILEPOS is
   accomplished, in order to identify the start of the new data.  The
   resync-uid is a unique identifier associated with the
   resynchronization of the data channel; it is unique with respect to
   this dialogue.  resync-uid must be supplied if handle is an input
   handle, but it is not supplied otherwise.  For more information on
   the resynchronization procedure:  See the section "NFILE Data
   Connection Resynchronization", section 9.2.

   In the output case, the user must somehow indicate to the server, on
   the output data channel, when there is no more data.  The user side
   sends the keyword token EOF to do so.  Upon receiving that control

   token, the server is required to position the file pointer according
   to the position given.  When the new file position is established,
   the server resumes accepting data at the new file position.

   In most cases, using the direct access mode of transfer is more
   convenient and efficient than repeated use of FILEPOS with a data
   stream opening.

   There are problems inherent in trying to set a file position of a
   character-oriented file on a foreign host, if one machine is a
   Symbolics computer and the other is not.  For example, character set
   translation must take place.  See the section "NFILE Character Set",
   section 6.  Because of these difficulties, FILEPOS might not be
   supported in the future on character files.  FILEPOS is not
   problematic for binary files.

8.15.1  Implementation Hint for FILEPOS Command

   The server processing of this command (by the control connection
   handler) must not attempt to wait for the resynchronization procedure
   to complete.  It is possible that the user could abort between
   sending the FILEPOS command and reading for the mark and
   resynchronization identifier.  That scenario could leave the sender
   of the resynchronization identifier, on the server side, blocked for
   output indefinitely.

   Only two commands received on the control connection can break the
   data channel out of the blocked state described above:  CLOSE with
   abort-p supplied as Boolean truth, and RESYNCHRONIZE-DATA-CHANNEL.
   Therefore, the control connection must not wait for the data channel
   to finish performing the resynchronization procedure.  This wait
   should instead be performed by the process managing the data channel.

8.16  FINISH Command

   Command:  (FINISH tid handle)

   Response: (FINISH tid truename binary-p other-properties)

   FINISH closes a file and reopens it immediately with the file
   position pointer saved, thus leaving it open for further I/O.  If
   possible, the implementation should do the closing and opening in an
   indivisible operation, such that no other process can get access to
   the file.

   The arguments, results, and their meaning are identical to those of
   the CLOSE command.  See the section "CLOSE Command", section 8.3.
   FINISH requires a handle, which has the same meaning as the handle of
   the CLOSE command.

   In the output case, for both direct mode and data stream mode of
   openings, the server writes out all buffers and sets the byte count
   of the file.  The user sends the keyword token EOF on the data
   channel, to indicate that the end of data has been reached.  The
   server leaves the file in such a state that if the system or server
   crashes anytime after the FINISH command has completed, it would
   later appear as though the file had been closed by this command.
   However, the file is not left in a closed state now; it is left open
   for further I/O operations.  FINISH is a reliability feature.

   FINISH is somewhat pointless in the input case, but valid.  The
   native Symbolics file system (LMFS) implements FINISH on an output
   file by an internal operation that effectively goes through the work
   of closing but leaves the file open for appending.

   ERRORS ON FINISH

   After writing every last bit sent by the user to disk, and before
   closing the file, the server checks the data channel specified by
   handle to see if an asynchronous error is outstanding on that
   channel.  That is, the server must determine whether it has sent an
   asynchronous error to the user, to which the user has not yet
   responded with a CONTINUE command.  If so, the server is unable to
   finish the file, and it must send a command error response response,
   indicating that an error is pending on the channel.  The appropriate
   three-letter error code is EPC.  See the section "NFILE Errors and
   Notifications", section 10.

8.17  HOME-DIRECTORY Command

   Command:  (HOME-DIRECTORY tid user)

   Response: (HOME-DIRECTORY tid directory-pathname)

   HOME-DIRECTORY returns the full pathname of the home directory on the
   server machine for the given user.

   user is a string that should be recognizable as a user's login name
   on the server operating system.  directory-pathname is a string in
   the directory pathname format.  See the section "Syntax of File and
   Directory Pathname Arguments", section 7.4.

8.18  LOGIN Command

   Command:  (LOGIN tid user password FILE-SYSTEM USER-VERSION)

   Response: (LOGIN tid keyword/value-pairs)

   LOGIN logs the given user in to the server machine, using the
   password if necessary.  Both user and password are string arguments;
   user is required, password is optional.  An omitted password is valid
   if the host allows the specified user to log in without a password.
   Depending on the operating system and server, it might be necessary
   to log in to run a program (in this case the NFILE server program) on
   the host.  LOGIN establishes a user identity that is used by the
   operating system to establish the file author and determine file
   access rights during the current session.

   The server has the option to reject with an error any command except
   LOGIN if a successful LOGIN command has not been performed.  This is
   recommended.  Many operating systems perform the login function in a
   different process and/or environment than user programs.  The portion
   of the NFILE server running in the special login environment could
   conceivably be capable only of processing the LOGIN command; this is
   the reason for having the LOGIN command in NFILE.

   FILE-SYSTEM and USER-VERSION are optional keyword/value pairs.  The
   FILE-SYSTEM keyword/value pair selects the identity of the file
   system to which all following commands in this session are to be
   directed.  This argument has meaning only if the server host machine
   has multiple file systems, and the targeted file system is other than
   the default file system that a user would get by initiating a
   dialogue with that host.  The FILE-SYSTEM argument is an arbitrary
   token list.  If the server does not recognize it, the server gives an
   appropriate command error response.

   Currently, the only use of FILE-SYSTEM is for Symbolics servers to
   select one of the front-end processor hosts instead of the LMFS,
   which is the default.  In this case, the first element in the token
   list is the keyword FEP, and the second element in the token list is
   an integer, indicating the desired FEP disk unit number.  If the
   server discovers there is no such file system, the server gives a
   command error response including the three-letter code NFS, meaning
   "no file system".  See the section "NFILE Errors and Notifications",
   section 10.

   The user tells the server what version of NFILE it is running by
   including the optional USER-VERSION keyword/value pair.  The value
   associated with USER-VERSION can be a string, an integer, or a token
   list.  This document describes NFILE user version 2 and server
   version 2.

   Upon receiving the representation of the user version, the server can
   either adjust certain parameters to handle this particular version,
   or simply ignore the user version altogether.  Currently, the only
   released versions of NFILE are user version 2 and server version 2.

   LOGIN RETURN VALUES:  keyword/value-pairs

   The keyword/value-pairs is a token list composed of keywords followed
   by their values.  The server includes any or all of the following
   keywords and their values; they are all optional.  The following
   keywords are recognized:

   NAME

   The value associated with NAME is a string specifying the user
   identity, in the server host's terms.

   PERSONAL-NAME

   The value associated with PERSONAL-NAME is a string representing the
   user's personal name, last name first.  For example:  "McGillicuddy,
   Aloysius X.".

   HOMEDIR-PATHNAME

   The value associated with HOMEDIR-PATHNAME is a string in the
   pathname as directory format, indicating the home directory of the
   user.  See the section "Syntax of File and Directory Pathname
   Arguments", section 7.4.

   GROUP-AFFILIATION

   The value associated with GROUP-AFFILIATION is a string specifying
   the group to which the user belongs, when this concept is
   appropriate.

   SERVER-VERSION

   The value associated with SERVER-VERSION can be a string, an integer,
   or a token list.  The value is a representation of the version of the
   server is running.  Upon receiving the server version, the user can:
   adjust certain parameters to handle this particular version; accept

   the version; or close the connection.  Currently, the only released
   versions of NFILE are user version 2 and server version 2.

   PROPERTY-INDEX-TABLE

   The value associated with PROPERTY-INDEX-TABLE is a token list of
   keywords.  This return value enables the server to inform the user
   which file properties are meaningful on its file system.  The
   keywords in PROPERTY-INDEX-TABLE can be used by the DIRECTORY command
   (a user request for information on file properties of a specified
   directory or directories).  The server can specify a certain property
   by giving an integer that is the index of that file property into the
   PROPERTY-INDEX-TABLE.  This reduces the volume of data sent during
   directory listings.  The first element in PROPERTY-INDEX-TABLE is
   indexed by the number 0.  See the section "DIRECTORY Command",
   section 8.11.

8.19  MULTIPLE-FILE-PLISTS Command

   Command:  (MULTIPLE-FILE-PLISTS tid input-handle paths
              characters properties)

   Response: (MULTIPLE-FILE-PLISTS tid)

   MULTIPLE-FILE-PLISTS returns file property information of one or more
   files.  The server sends the information in a data structure (the
   format is described later in this section) on the given input-handle.
   paths is an embedded token list composed of the pathnames in which
   the user is interested.  Each pathname in this list is a string in
   the full pathname syntax of the server host.  Unlike for the
   DIRECTORY command, wildcards are not allowed in these pathnames.  See
   the section "Syntax of File and Directory Pathname Arguments",
   section 7.4.

   characters is either Boolean truth (indicating that each file is a
   character file), the empty token list (each file is a binary file),
   or the keyword DEFAULT.  DEFAULT indicates that the server itself is
   to figure out whether a file is a character or binary file.  For more
   information on the meaning of the DEFAULT keyword:  See the section
   "OPEN Command", section 8.20.  The value of characters can influence
   some servers' idea of a file's length.

   properties is a token list of keywords indicating which properties
   the user wants returned.  The server is always free to return more
   properties than those requested in the properties argument.  If
   properties is supplied as the empty token list, the server should
   transmit all known properties on the files.

   The server transmits as much of the requested information as possible
   on the given input-handle.  The information is contained in a top-
   level token list of elements.  Each element corresponds with a
   supplied pathname; the order of the original pathlist must be
   retained in the returned token list.  An element is an empty token
   list if the corresponding file or any of its containing directories
   does not exist.  The elements that correspond to successfully located
   files are lists composed of truename followed by any properties.
   properties are keyword/value pairs.  truename is a string in the full
   pathname syntax of the server host.

   The following example shows TOP-LEVEL-LIST-BEGIN and TOP-LEVEL-LIST-
   END as parentheses, and LIST-BEGIN and LIST-END with square brackets.

   For example, the user supplied a pathlist argument resembling:

                            [file1 file2 file3]

   The server could not locate file1 or file3, but did locate file2, and
   found the length and author of file2.  The top-level token list
   transmitted by the server is:

        ( [] [ truename-of-file2 LENGTH 381 AUTHOR williams ] [] )

   For further detail on how file properties and values are expressed:
   See the section "Format of NFILE File Property/Value Pairs", section
   7.5.

8.20  OPEN Command

   Command:  (OPEN tid handle pathname direction binary-p
                TEMPORARY RAW SUPER-IMAGE DELETED PRESERVE-DATES
                SUBMIT DIRECT-FILE-ID ESTIMATED-LENGTH BYTE-SIZE
                IF-EXISTS IF-DOES-NOT-EXIST)

   Response: (OPEN tid truename binary-p other-properties)

   OPEN opens a file for reading, writing, or direct access at the
   server host.  That means, in general, asking the host file system to
   access the file and obtaining a file number, pointer, or other
   quantity for subsequent rapid access to the file; this is called an
   "opening".  See the section "NFILE File Opening Modes", section 5.

   The OPEN command has the most complicated syntax of any NFILE
   command.  The OPEN command has required arguments, an optional
   argument, and many optional keyword/value pairs.  For details on the
   syntax of each of these parts of the OPEN command:  See the section
   "Conventions Used in This Document", section 7.

   The following arguments are required:  pathname, direction, and
   binary-p.  handle is an optional argument, which must either be
   supplied or explicitly omitted by means of substituting in its place
   the empty token list.

   The OPEN command has many optional keyword/value pairs, which encode
   conceptual arguments to the server file system for the OPEN
   operation.  A detailed description of all the supported OPEN optional
   keywords is given below.

   The OPEN return values reflect information about the file opened,
   when the opening is successful.  In the case of a probe-type opening,
   this information is returned when the given file (or link, or
   directory) exists and is accessible, even though the file (or link,
   or directory) is not actually opened.  For detail on the OPEN return
   values: See the section "NFILE OPEN Response Return Values", section
   8.20.2.

   THE pathname OPEN ARGUMENT

   The pathname is a required argument specifying the file to be opened.
   pathname is a string in the full pathname syntax of the server host.
   See the section "Syntax of File and Directory Pathname Arguments",
   section 7.4.

   For some purposes (for example, when the OPEN argument direction is
   supplied as PROBE-DIRECTORY), only the directory specified by this
   pathname is utilized.  See the section "NFILE OPEN Optional
   Keyword/Value Pairs", section 8.20.1.

   THE handle OPEN ARGUMENT

   The handle argument of the OPEN command specifies a data channel to
   be used for the transfer.  Subsequent commands in this session use
   the same handle to specify this opening.  It is the user side's
   responsibility to ensure that handle refers to an existing and free
   data channel that does not require resynchronization before use.  A
   handle must be supplied, unless a probe-type opening is desired (that
   is, the direction is supplied as PROBE, PROBE-DIRECTORY, or PROBE-
   LINK) or a direct access opening is being requested (that is, a
   DIRECT-FILE-ID is supplied).  In those cases, the empty token list is
   supplied for handle.

   THE direction OPEN ARGUMENT

   The direction argument must be supplied as one of these keywords:
   INPUT, OUTPUT, IO, PROBE, PROBE-DIRECTORY, and PROBE-LINK.  The
   meanings of the direction keywords are as follows:

   INPUT

      Specifies that the file is to be opened for input server-to-user
      transfer).  To request a direct access opening, supply a value for
      DIRECT-FILE-ID. If no DIRECT-FILE-ID is supplied, the opening is a
      data stream opening.

   OUTPUT

      Specifies that the file is to be opened for output user-to-server
      transfer).  To request a direct access opening, supply a value for
      DIRECT-FILE-ID. If no DIRECT-FILE-ID is supplied, the opening is a
      data stream opening.

   IO

      Specifies that interspersed input and output will be performed on
      the file.  This is only meaningful in direct access mode.  A
      DIRECT-FILE-ID must also be supplied.  See the section "NFILE OPEN
      Optional Keyword/Value Pairs", section 8.20.1.

   If direction is supplied as PROBE, PROBE-LINK, or PROBE-DIRECTORY,
   the opening is said to be a probe-type opening.  The DIRECT-FILE-ID
   option is meaningless and an error for probe-type openings.  The file
   handle must be supplied as an empty token list for probe-type
   openings.

   PROBE

      Specifies that the file is not to be opened at all, but simply
      checked for existence.  If the file does not exist or is not
      accessible, the error indications and actions are identical to
      those that would be given for an INPUT opening.  If the file does
      exist, the successful command response contains the same
      information as it would have if the file had been opened for
      INPUT.  If it is a link, the link is followed to its target.

   PROBE-LINK

      Like PROBE, with one difference.  PROBE-LINK specifies that if the
      pathname is found to refer to a link, that link is not to be
      followed, and information about the link itself is to be returned.

   PROBE-DIRECTORY

      PROBE-DIRECTORY requests information about the directory
      designated by the pathname argument.  In the PROBE-DIRECTORY case,
      the pathname argument refers to the directory on which information
      is requested.  In all other cases, the pathname refers to a file
      to be opened.  If pathname contains a file name and file type,
      these parts of the pathname are ignored for PROBE-DIRECTORY
      openings as long as they are syntactically valid.

   THE binary-p OPEN ARGUMENT

   The value of binary-p affects the mode in which the server opens the
   file, as well as informing it whether or not character set
   translation must be performed.

   If binary-p is supplied as the empty token list, the opening is said
   to be a character opening.  The server performs character set
   translation between its native character set and the NFILE character
   set.  The data is transferred over the data connection one character
   per eight-bit byte.  See the section "NFILE Character Set", section
   6.

   If binary-p is supplied as Boolean truth, the opening is said to be a
   binary opening.  The user side supplies the byte size via the BYTE-
   SIZE option; if not supplied, the default byte size is 16 bits.  If
   byte size is less than 9, the file data is transferred byte by byte.
   If the byte size is 9 or greater, the server transfers each byte of
   the file as two eight-bit bytes, low-order first.

   binary-p can also be supplied as the keyword DEFAULT.  DEFAULT
   specifies that the server itself is to determine whether to transfer
   binary or character data.  DEFAULT is meaningful only for input
   openings; it is an error for OUTPUT, IO, or probe-type openings.  For
   file systems that maintain the innate binary or character nature of a
   file, the server simply asks the file system which case is in force
   for the file specified by pathname.

   When binary-p is supplied as DEFAULT, on file systems that do not
   maintain thisinformation, the server is required to perform a
   heuristic check for Symbolicsobject fileson the first two 16-bit
   bytes of the file.  If the file isdetermined to be aSymbolics object
   file, the server performs a BINARY openingwith BYTE-SIZE of16;
   otherwise, it performs a CHARACTER opening.

   The details of the check are as follows: if the first 16-bit byte is
   the octal number170023 and the second 16-bit byte is any number
   between 0 and 77 octal(inclusive), the file is recognized as a
   Symbolics object file.  In any othercase, it is not.

8.20.1  NFILE OPEN Optional Keyword/Value Pairs

   The OPEN command has many optional keyword/value pairs that encode
   conceptual arguments to the file system for the OPEN operation.

   The following options are used often:

   BYTE-SIZE

      Must be followed by an integer between 1 and 16, inclusive, or the
      empty token list.  BYTE-SIZE is meaningful only for binary
      openings.  BYTE-SIZE can be ignored for probe-type openings.  It
      can be omitted entirely for character openings, but if supplied,
      must be followed by the empty token list.  If binary-p is supplied
      as DEFAULT, BYTE-SIZE can be omitted entirely, or followed by the
      empty token list.

      If a binary opening is requested and BYTE-SIZE is not supplied,
      the assumed value is 16 for output openings. For input binary
      openings, the default is the host file system's stored conception
      of the file's byte size (for those hosts that natively support
      byte size).  For file systems that do not natively support
      natively byte size, the default byte-size on binary input is 16.

      For file systems that maintain the innate byte-size of each file,
      the server should supply this number to the appropriate operating
      system interface that performs the semantics of opening the file.
      For other operating systems, a file written with a given byte size
      must produce the same bytes in the same order when read with that
      byte size.  In this case, the server or host operating system can
      choose any packing scheme that complies with this rule.

      Operating systems that do not support byte size must ensure that
      binary files written from user ends of the current protocol can be
      read back correctly.  However, the server can choose packing
      schemes that allow all bits of the server host's word to be
      accessed and concur with other packing schemes used by native host
      software.

      For example, Multics supports 36 bit words and 9 bit bytes.  A
      packing scheme appropriate for a Multics NFILE server is:

               Byte Size                Packing Scheme

               7, 8, or 9 bits          four per 36-bit word
               10, 11, or 12 bits       three per 36-bit word
               13, 14, 15, or 16 bits   two per 36-bit word

      In the first packing scheme in the table, native Multics
      character-oriented software can access each logical byte
      sequentially.  In the last packing scheme, each Symbolics byte is
      in a halfword, easily accessible and visible in an octal
      representation.  To achieve maximum data transfer rate and access
      all bits of a Multics word, a byte size of 12 must be specified.

   DELETED

      If supplied as Boolean truth, DELETED specifies that deleted"
      files are to be treated as though they were not "deleted".
      DELETED is meaningful only for operating systems that support
      "soft deletion" and subsequent "undeletion" of files.  Other
      operating systems must ignore this option.  Normally, deleted
      files are not visible to the OPEN operation; this option makes
      them visible.

      DELETED can also be followed by the empty token list, which has
      the same effect as omitting the DELETED keyword/value pair
      entirely.  For output openings, DELETED is meaningless and an
      error if supplied.

   DIRECT-FILE-ID

      If supplied, the DIRECT-FILE-ID indicates that the opening is to
      be a direct access mode opening.  If not supplied, the opening is
      a data stream opening.  The value of DIRECT-FILE-ID is a string
      generated by the user, that has not been used as a DIRECT-FILE-ID
      in this dialogue, and does not designate any data channel.  The
      DIRECT-FILE-ID is a unique identifier for the direct access
      opening.  It is used for all operations that identify an opening
      rather than a data channel.  The DIRECT-FILE-ID is used to
      identify a direct access opening, just as a file handle is used to
      identify a data stream opening.  The PROPERTIES, CLOSE, and RENAME
      commands use the DIRECT-FILE-ID in this way.  There are only two
      NFILE commands applicable to direct access openings (ABORT and
      CONTINUE) that do not use the DIRECT-FILE-ID, but use a data
      channel handle instead.

   PRESERVE-DATES

      If supplied as Boolean truth, PRESERVE-DATES specifies that the

      server is to attempt to prevent the operating system from updating
      the "reference date" or date-time used" of the file.  This is
      meaningful only for input openings, and is an error otherwise.

      The Symbolics operating system invokes this option for operations
      such as View File in the editor, where it wishes to assert that
      the user did not "read" the file, but just "looked at it".
      Servers on operating systems that do not support reference dates
      or users revising or suppressing update of the reference dates
      must ignore this option.

   ESTIMATED-LENGTH

      The value of ESTIMATED-LENGTH is an integer estimating the length
      of the file to be transferred. This option is meaningful and
      permitted only for output openings.  ESTIMATED-LENGTH enables the
      user end to suggest to the server's file system how long the file
      is going to be.  This can be useful for file systems that must
      preallocate files or file maps or that accrue performance benefits
      from knowing this information at nthe time the file is first
      opened.  This estimate, if supplied, is not required to be exact.
      It is ignored by servers to which it is not useful or interesting.
      The units of the estimate are characters for character openings,
      and bytes of the agreed-upon byte size for binary openings.  The
      character units should be server units, if possible, but since
      this is only an estimate, NFILE character units are acceptable.
      See the section "NFILE Character Set", section 6.

   IF-EXISTS

      Meaningful only for output openings, ignored otherwise, but not
      diagnosed as an error.  The value of IF-EXISTS is a keyword that
      specifies the action to Be taken if a file of the given name
      already exists.  The semantics of the values are derived from the
      Common Lisp specification and repeated here for completeness.  If
      the file does not already exist, the IF-EXISTS option and its
      value are ignored.

      If the user side does not give the IF-EXISTS option, The action to
      be taken if a file of the given name already exists depends on
      whether or not the file system supports file versions.  If it
      does, the default is ERROR (if an explicit version is given in the
      file pathname) or NEW-VERSION (if the version in the file pathname
      is the newest version).  For file systems not supporting versions,
      the default is SUPERSEDE.  These actions are described below.

      IF-EXISTS provides the mechanism for overwriting or appending to
      files.  With the default setting of IF-EXISTS, new files are
      created by every output opening.

      Operating systems supporting soft deletion can take different
      actions if a "deleted" file already exists with the same name (and
      type and version, where appropriate) as a file to be created.  The
      Symbolics file system (LMFS) effectively uses SUPERSEDE, even if
      not asked to do so.  Other servers and file systems are urged to
      do similarly.  Recommended action is to not allow deleted files to
      prevent successful file creation (with specific version number)
      even if an IF-EXISTS option weaker than SUPERSEDE, RENAME, or
      RENAME-AND-DELETE is specified or implied.

      Here are the possible values and their meanings:

      ERROR

         Reports an error.

      NEW-VERSION

         Creates a new file with the same file name but with a larger
         version number.  This is the default when the version component
         of the filename is newest.  File systems without version
         numbers can implement this by effectively treating it as
         SUPERSEDE.

      RENAME

         Renames the existing file to some other name and then creates a
         new file with the specified name.  On most file systems, this
         renaming happens at the time of a successful close.

      RENAME-AND-DELETE

         Renames the existing file to some other name and then deletes
         it (but does not expunge it, on those systems that distinguish
         deletion from expunging).  Then it creates a new file with the
         specified name.  On most file systems, this renaming happens at
         the time of a successful close.

      OVERWRITE

         Output operations on the opening destructively modify the
         existing file.  New data replaces old data at the beginning of
         the file; however, the file is not truncated to length zero
         upon opening.

      TRUNCATE

         Output operations on the opening destructively modify the
         existing file.  The file pointer is initially positioned at the
         beginning of the file; at that time, TRUNCATE truncates the
         file to length zero and frees disk storage occupied by it.

      APPEND

         Output operations on the opening destructively modify the
         existing file.  New data is placed at the current end of the
         file.

      SUPERSEDE

         Supersedes the existing file.  This means that the old file is
         removed or deleted and expunged.  The new file takes its place.
         If possible, the file system does not destroy the old file
         until the new file is closed, against the possibility that the
         file will be close-aborted.  This differs from NEW-VERSION in
         that SUPERSEDE creates a new file with the same name as the old
         one, rather than a file name with a higher version number.

         There are currently no standards on what a server can do if it
         cannot implement some of these actions.

   IF-DOES-NOT-EXIST

      Meaningful for input openings, never meaningful for probe-type
      openings, and sometimes meaningful for output openings.  IF-DOES-
      NOT-EXIST takes a value token, which specifies the action to be
      taken if the file does not already exist.  Like IF-EXISTS, it is a
      derivative of Common Lisp.  The default is as follows: If this is
      a probe-type opening or read opening, or if the IF-EXISTS option
      is specified as OVERWRITE, TRUNCATE, or APPEND, the default is
      ERROR.  Otherwise, the default is CREATE.

      These are the values for IF-DOES-NOT-EXIST:

      ERROR

         Reports an error.

      CREATE

         Creates an empty file with the specified name and then proceeds
         as if it already existed.

   The following optional keyword/value pairs are rarely used, if ever:

   RAW

      If supplied as Boolean truth, RAW specifies that character set
      translation is not to be performed, but that characters are to be
      transferred intact, without inspection.  This option is meaningful
      only for character openings; it is an error otherwise.  It is also
      an error to supply RAW as Boolean truth for probe-type openings.
      RAW can also be followed by the empty token list, which has the
      same effect as if the RAW keyword/value pair were omitted
      entirely.  See the section "RAW Translation Mode", Appendix B.

   SUPER-IMAGE

      If supplied as Boolean truth, SUPER-IMAGE specifies that Rubout
      quoting is not to be performed.  This operation is meaningful only
      for character openings; it is an error otherwise.  It is also an
      error for probe-type openings.  SUPER-IMAGE can also be followed
      by the empty token list, which has the same effect as if the
      SUPER-IMAGE keyword/value pair were omitted entirely.

      SUPER-IMAGE mode causes the server to read or write character
      files where ASCII Rubout characters are a significant part of the
      file content, not where they are an escape for this protocol.
      However, other translations must still be performed:  See the
      section SUPER-IMAGE Translation Mode", Appendix C.

   TEMPORARY

      Used by the TOPS-20 server only.  TEMPORARY says to use GJ%TMP in
      the GTJFN.  This is useful mainly when writing files, and
      indicates that the foreign operating system is to treat the file
      as temporary.  See TOPS-20 documentation for more about the
      implications of this option.  Other servers can ignore it.  This
      option is meaningless and an error for input or probe-type
      openings.  TEMPORARY can also be followed by the empty token list,
      which has the same effect as if the TEMPORARY keyword/value pair
      were omitted entirely.

   SUBMIT

      SUBMIT is meaningful for output only.  If supplied as Boolean
      truth, SUBMIT causes the server to submit the contents of the file
      being written to the operating system as a job, after the file is
      closed.  VMS is an example of an operating system that could
      conveniently support SUBMIT.  SUBMIT can also be followed by the
      empty token list, which has the same effect as if the SUBMIT

      keyword/value pair were omitted entirely.  Servers that do not
      implement this option should give an error response if requested
      to submit a file to the operating system.

8.20.2  NFILE OPEN Response Return Values

   The results of a successful OPEN operation are reported in the
   command response.  Here is the specification of the OPEN response
   format:

   Response Format:

      (OPEN tid truename binary-p other-properties)

   The return values for OPEN and CLOSE are syntactically identical, but
   the values can change in the time interval between open and close.

   truename is a string representing the pathname of the file in the
   full pathname syntax of the server host.  It should be determined by
   the server once it has opened the file, via some request to its
   operating system.  The request can be of the form:  "What file
   corresponds to this JFN, file number, pointer, etc.?"  If the
   operating system supports version numbers, this string always
   contains an explicit version number.  It always contains a directory
   name, a file name, and so on.

   Some operating systems might not know the truename of an output file
   until it is closed.  It is permissible not to supply an explicit
   version number in the pathname in the OPEN response in this specific
   case.  On these systems the truename when the file is opened is
   different than the truename after it has been closed.

   The return value binary-p indicates whether the opening is a binary
   or character opening.  For binary openings, binary-p is supplied as
   Boolean truth; for character openings it is the empty token list.

   other-properties is a list of keyword/value pairs.  other-properties
   must contain CREATION-DATE and LENGTH.  AUTHOR should be included if
   the server operating system has a convenient mechanism for
   determining the author of the sfile.  The other properties described
   here can be included if desired.

   AUTHOR

   The value of AUTHOR is a string representing the name of the author
   of the file.  This is some kind of user identifier, whose format is
   system-specific.  As with CREATION-DATE (see below), AUTHOR is
   supposed to represent the logical determinor of the current data

   content of the file, not necessarily the agency that actually created
   the file.

   BYTE-SIZE

   The byte-size agreed upon via the rules described for the BYTE-SIZE
   option.  The value of BYTE-SIZE is an integer.  For details on the
   ramifications of BYTE-SIZE:  See the section "NFILE OPEN Optional
   Keyword/Value Pairs", section 8.20.1.  This parameter is only
   meaningful for BINARY openings.  However, if FILEPOS is returned in
   the other-properties list, BYTE-SIZE should also be included, even
   for character openings.

   CREATION-DATE

   The creation date of the file.  The date is expressed in Universal
   Time format, which measures a time as the number of seconds since
   January 1, 1900, at midnight GMT.  Creation date does not necessarily
   mean the time the file system created the directory entry or records
   of the file.  For systems that support modification or appending to
   files, it is usually the modification date of the file.  Creation
   date can mean the date that the bit count or byte count of the file
   was set by an application program.

   Some types of file systems support a user-settable quantity
   (CREATION-DATE) which the user can set to an arbitrary time, to
   indicate that the contents of this file were written a long time ago
   by someone else on another computer.  The default value of this
   quantity, if the user has not set it, is the time someone last
   modified the information in the file.  This quantity, in the OPEN
   response for an output file, is disregarded by the user side, but
   nevertheless must be present.

   The Symbolics computer system software uses this quantity as a unique
   identifier of file contents, for a given file name, type, and
   version, to prove that a file has not changed since it last recorded
   this quantity for a file.

   FILEPOS

   An integer giving the position of the logical file pointer, in
   characters or bytes as appropriate for the type of opening.  This is
   always zero for an input opening and for an output opening creating a
   new file.  For an output opening appending to an existing file,
   FILEPOS is the number of characters or bytes, as appropriate,
   currently in the file.  This number, for character openings, is
   measured in server units: See the section "NFILE Character Set",
   section 6.

   LENGTH

   An integer reporting the length of the file, in characters for
   character openings and in bytes of the agreed-upon size for binary
   openings.  LENGTH should be reported as zero for output openings,
   even if appending to an existing file.  The server usually only knows
   the length for a character opening in server units; thus, it reports
   length in server units.

8.21  PROPERTIES Command

   Command:  (PROPERTIES tid handle pathname control-keywords
   properties)

   Response: (PROPERTIES tid property-element settable-properties)

   PROPERTIES requests the property information about one file.  The
   file is identified by the pathname argument or the handle argument,
   but not both.  If pathname is supplied, it is a string in the full
   pathname syntax of the server host.  See the section "Syntax of File
   and Directory Pathname Arguments", section 7.4.

   If handle is supplied, its value is a string identifying an opening,
   which implicitly identifies a file.  For direct access mode openings,
   handle must be a direct file identifier.

   control-keywords is reserved in the current design.  However, it is a
   required argument, and must be supplied as the empty token list.  Its
   presence in the NFILE specification allows for future expansion.  In
   the future the value of control-keywords might affect the listing
   mode.

   properties is a token list of keywords indicating the properties the
   user wants returned.  (In command arguments, properties cannot be
   specified with integers, such as indices into the Property Index
   Table).  For a list of keywords associated with file properties:  See
   the section "Format of NFILE File Property/Value Pairs", section 7.5.

   The server is always free to return more properties than those
   requested in the properties argument.  If properties is supplied as
   the empty token list, the server transmits all known properties of
   the file.

   PROPERTIES COMMAND RESPONSE

   The server returns the property information for the given file in the
   command response.  The PROPERTIES command does not use any data
   channels.  If the specified file does not exist or is not accessible,
   the server signals an error and includes an appropriate three-letter
   error code in the command error response.  See the section "NFILE
   Errors and Notifications", section 10.

   The return value property-element is a token list.  The first element
   in that token list is the pathname of the file, in the full pathname
   syntax of the server host.  The following elements of the property-
   element token list are property/value pairs.  The server is expected
   to return several property/value pairs; the number of pairs is not
   constrained.  For further details on file properties and their
   associated values:  See the section "Format of NFILE File
   Property/Value Pairs", section 7.5.

   The return value settable-properties is a token list of keywords.
   The number of keywords is not constrained.  (Note that integers
   cannot be used in settable-properties to indicate the file property;
   keywords are to be used instead.)  Each keyword supplied in
   settable-properties identifies a property considered settable by the
   server.  The server is implicitly guaranteeing a mechanism for
   changing the properties reported as settable.  The user can change
   any of the settable properties for this file by using the CHANGE-
   PROPERTIES command.  See the section "CHANGE-PROPERTIES Command",
   section 8.2.

   The following example shows the format of the PROPERTIES command
   response.  Remember that the number of property/value pairs and
   keywords is not constrained; this example has two property/value
   pairs and three settable-properties keywords returned:

             TOP-LEVEL-LIST-BEGIN
             PROPERTIES         - name of the command
             tid                - transaction identifier
             LIST-BEGIN
             pathname of file
             prop1 value1       - file's property/value pairs
             prop2 value2
             LIST-END
             LIST-BEGIN
             keyword-1          - file's settable properties
             keyword-2
             keyword-3
             LIST-END
             TOP-LEVEL-LIST-END

   The following example is designed to better show the structure of the
   top-level token list by depicting TOP-LEVEL-LIST-BEGIN and TOP-
   LEVEL-LIST-END by parentheses and LIST-BEGIN and LIST-END by square
   brackets.  The indentation and newlines in the example are not part
   of the token list, but are used here to make the structure of the
   token list clear.

             (PROPERTIES tid [ pathname prop1 value1 prop2 value2 ...]
                             [ keyword1 keyword2 keyword3 ... ]

8.22  READ Command

   Command: (READ tid direct-file-id input-handle count FILEPOS)

   Response: (READ tid)

   READ requests input data flow for direct access openings.  The
   direct-file-id is the same as the DIRECT-FILE-ID argument that was
   given when opening the file; it designates the opening from which the
   characters or bytes are to be transferred.  The input-handle
   specifies which data channel should be used for the transfer of data
   from server to user.  The data channel should have been already
   established, cannot have been disestablished, and must not currently
   be in use.

   count is an integer specifying how many bytes (or NFILE characters,
   as appropriate) to read.  count can be supplied as the empty token
   list, meaning read to the end of the file.  If the user specifies the
   empty token list or a count greater than the number of bytes
   remaining in the file, the server sends the keyword EOF to mark the
   end of the file.

   FILEPOS is an optional keyword/value pair.  If the keyword FILEPOS is
   supplied, it must be followed by an integer.  Before data is
   transferred, the opening is positioned to the point specified by the
   value of FILEPOS.  The position of the point is measured in server
   units for character openings; for binary openings it is measured in
   binary bytes.  See the section "FILEPOS NFILE Command".

   Upon receiving the READ command, the server binds the data channel to
   the opening and immediately begins transferring data.  The server
   stops when all data has been transferred.  After the server sends the
   last requested byte, it unbinds the data channel, freeing it for
   other use.  When the user side has processed the last byte, the user
   side assumes that the data channel can now be reused for another data
   transfer.

8.23  RENAME Command

   Command:  (RENAME tid handle pathname to-pathname)

   Response: (RENAME tid from-pathname to-pathname)

   RENAME requests the server to give a file a new name.  This is
   NFILE's interface to the system's native rename operation, with all
   of its system-specific semantics and constraints.

   Either a handle or a pathname (but not both) specifies the file that
   is to receive a new name.  The argument to-pathname designates that
   new name.  The return value from-pathname gives the full original
   name of the file, and to-pathname gives the full new name of the
   file.  For systems that support version numbers, the return values
   can differ in version number from the values of the arguments given
   to RENAME.

   The arguments pathname and to-pathname and the return values from-
   pathname and to-pathname are strings in the full pathname syntax of
   the server host.  See the section "Syntax of File and Directory
   Pathname Arguments", section 7.4.

   If the file to be renamed is specified by a pathname, the file should
   be renamed immediately.  If the file is specified by handle, it is
   acceptable to wait until close-time to rename the file.

   Some operating systems can rename only within a directory.
   Nevertheless, the to-pathname of the RENAME must be fully specified;
   the server on these systems must check for and reject an attempted
   cross-directory rename.

8.24  RESYNCHRONIZE-DATA-CHANNEL Command

   The command and response format for this command varies, depending on
   whether the handle argument indicates an input or output data
   channel.

   For an Input Handle:

   Command:  (RESYNCHRONIZE-DATA-CHANNEL tid handle)

   Response: (RESYNCHRONIZE-DATA-CHANNEL tid identifier)

   For an Output Handle:

   Command:  (RESYNCHRONIZE-DATA-CHANNEL tid handle identifier)

   Response: (RESYNCHRONIZE-DATA-CHANNEL tid)

   RESYNCHRONIZE-DATA-CHANNEL begins a prescribed procedure between user
   and server over the unsafe data channel specified by handle.  The
   resynchronization procedure clears the data channel of any unwanted
   data, and restores the data channel to a safe state, ready to
   transfer data again.

   All arguments to RESYNCHRONIZE-DATA-CHANNEL are required.

   For a detailed description of how the user and server coordinate the
   resynchronization of data channels:  See the section "NFILE Data
   Connection Resynchronization", section 9.2.

8.24.1  Implementation Hints for RESYNCHRONIZE-DATA-CHANNEL Command

   In general, both the user and server should should be implemented
   with the knowledge that a transmission can be aborted.  That is, the
   receiving side must be careful not to act upon a transmission (that
   is, to perform any action or side effect) until the transmission has
   been successfully received in entirety.  This protects the user
   program from the possibility that an abort can occur after a
   transmission has been partially sent.

   RESYNCHRONIZING AN OUTPUT DATA CHANNEL

   The server will probably want to dispatch the looping and reading to
   the logical data process.  Looping reading for the resynchronization
   identifier in the control connection handler is not a viable option.
   If the user side fails to send the resynchronization identifier (for
   example, due to a user abort) the control connection handler can
   never be broken out of this loop.

   Should the user side send the control connection handler command
   first, or send the marks and identifiers first?

   Sending the marks first is problematic, because the data channel at
   the other end might not be reading them (for it has not yet been so
   instructed by the control connection handler).  The user might then
   become blocked for output, thus prohibiting sending of the
   RESYNCHRONIZE-DATA-CHANNEL command.

   On the other hand, sending the control connection handler command
   first requires that the user side can send the marks and identifiers
   between sending the control connection handler command and receiving
   a response for it.  The response will never come until the marks and
   identifiers have been successfully received.  The user implementation
   must allow for this one case of a command where a subroutine that
   "sends a command and waits for a response" is inapplicable.

   RESYNCHRONIZING AN INPUT DATA CHANNEL

   The server control process should dispatch the data process to send
   the mark, and not wait, lest the data process become blocked for
   output due to a user abort.  The control process must go back to its
   command loop, to possibly receive a command that might break the data
   process out of that block.

8.25  UNDATA-CONNECTION Command

   Command:  (UNDATA-CONNECTION tid input-handle output-handle)

   Response: (UNDATA-CONNECTION tid)

   UNDATA-CONNECTION explicitly disestablishes a data connection from
   the user side.  The user side has the option of disestablishing data
   connections at its discretion.  There is no place in the protocol
   where disestablishment of data connections is required, other than at
   the end of the session, where it is implicit.

   The data connection to be disestablished is the one designated by the
   input-handle and output-handle arguments.  These two handles must
   refer to the same data connection.

   It is not permitted to explicitly disestablish a data connection
   either of whose channels is active.  If the session is terminated by
   the breaking of the control connection, all file handles become
   meaningless, and the server must close all data connections known to
   it and close-abort all files opened on behalf of the user during the
   dialogue.

   In the Symbolics implementation, the user side disestablishes data
   connections that have not been used for a long time, such as twenty
   minutes or so.

   For more information about data connections:  See the section "NFILE
   Control and Data Connections", section 4.