RFC1037

Network Working Group B. Greenberg Request for Comments: 1037 S. Keene

                                                         December 1987

                   NFILE -  A File Access Protocol

STATUS OF THIS MEMO

  This document includes a specification of the NFILE file access
  protocol and its underlying levels of protocol, the Token List
  Transport Layer and Byte Stream with Mark.  The goal of this
  specification is to promote discussion of the ideas described here,
  and to encourage designers of future file protocols to take advantage
  of these ideas.  A secondary goal is to make the specification
  available to sites that might benefit from implementing NFILE.  The
  distribution of this document is unlimited.

                            TABLE OF CONTENTS
                                                                   Page
  1.  INTRODUCTION                                                    3

  2.  NFILE PROTOCOL LAYERING                                         4

  3.  OVERVIEW OF AN NFILE SESSION                                    5

  4.  NFILE CONTROL AND DATA CONNECTIONS                              6

  5.  NFILE FILE OPENING MODES                                        7

  6.  NFILE CHARACTER SET                                             9

  7.  CONVENTIONS USED IN THIS DOCUMENT                              10

      7.1  Mapping Data Types Into Token List Representation         10
      7.2  Format of NFILE Commands and Responses                    10
      7.3  Data Channel Handles and Direct File Identifiers          13
      7.4  Syntax of File and Directory Pathname Arguments           13
      7.5  Format of NFILE File Property/Value Pairs                 14

  8.  NFILE COMMANDS                                                 16

      8.1  ABORT Command                                             16
      8.2  CHANGE-PROPERTIES Command                                 16
      8.3  CLOSE Command                                             17
      8.4  COMPLETE Command                                          19
      8.5  CONTINUE Command                                          20

Greenberg & Keene [Page 1]

RFC 1037 NFILE - A File Access Protocol December 1987

      8.6  CREATE-DIRECTORY Command                                  21
      8.7  CREATE-LINK Command                                       21
      8.8  DATA-CONNECTION Command                                   22
      8.9  DELETE Command                                            23
      8.10  DIRECT-OUTPUT Command                                    23
      8.11  DIRECTORY Command                                        24
           8.11.1  NFILE DIRECTORY Data Format                       26
      8.12  DISABLE-CAPABILITIES Command                             27
      8.13  ENABLE-CAPABILITIES Command                              28
      8.14  EXPUNGE Command                                          28
      8.15  FILEPOS Command                                          29
           8.15.1  Implementation Hint for FILEPOS Command           30
      8.16  FINISH Command                                           30
      8.17  HOME-DIRECTORY Command                                   31
      8.18  LOGIN Command                                            32
      8.19  MULTIPLE-FILE-PLISTS Command                             34
      8.20  OPEN Command                                             35
           8.20.1  NFILE OPEN Optional Keyword/Value Pairs           39
           8.20.2  NFILE OPEN Response Return Values                 45
      8.21  PROPERTIES Command                                       47
      8.22  READ Command                                             49
      8.23  RENAME Command                                           50
      8.24  RESYNCHRONIZE-DATA-CHANNEL Command                       51
           8.24.1  Implementation Hints for RESYNCHRONIZE-DATA-      51
                   CHANNEL Command
      8.25  UNDATA-CONNECTION Command                                52

  9.  NFILE RESYNCHRONIZATION PROCEDURE                              53

      9.1  NFILE Control Connection Resynchronization                54
      9.2  NFILE Data Connection Resynchronization                   55

  10.  NFILE ERRORS AND NOTIFICATIONS                                58

      10.1  Notifications From the NFILE Server                      58
      10.2  NFILE Command Response Errors                            59
      10.3  NFILE Asynchronous Errors                                60
      10.4  NFILE Three-letter Error Codes                           61

  11.  TOKEN LIST TRANSPORT LAYER                                    65

      11.1  Introduction to the Token List Transport Layer           65
      11.2  Token List Stream                                        66
           11.2.1  Types of Tokens and Token Lists                   66
           11.2.2  Token List Stream Example                         68
           11.2.3  Mapping of Lisp Objects to Token List Stream      70
                   Representation
           11.2.4  Aborting and the Token List Stream                71

Greenberg & Keene [Page 2]

RFC 1037 NFILE - A File Access Protocol December 1987

      11.3  Token List Data Stream                                   72

  12.  BYTE STREAM WITH MARK                                         73

      12.1  Discussion of Byte Stream with Mark                      73
      12.2  Byte Stream with Mark Abortable States                   75

  13.  POSSIBLE FUTURE EXTENSIONS                                    77

  APPENDIX A.  NORMAL TRANSLATION MODE                               79

  APPENDIX B.  RAW TRANSLATION MODE                                  83

  APPENDIX C.  SUPER-IMAGE TRANSLATION MODE                          84

  NOTES                                                              86

                             LIST OF TABLES

  TABLE 1.    TRANSLATIONS FROM NFILE CHARACTERS TO UNIX CHARACTERS  80
  TABLE 2.    TRANSLATIONS FROM UNIX CHARACTERS TO NFILE CHARACTERS  80
  TABLE 3.    TRANSLATIONS FROM NFILE TO PDP-10 CHARACTERS           81
  TABLE 4.    TRANSLATIONS FROM PDP-10 CHARACTERS TO NFILE           82
              CHARACTERS
  TABLE 5.    SUPER-IMAGE TRANSLATION FROM NFILE TO ASCII            84
  TABLE 6.    SUPER-IMAGE TRANSLATION FROM ASCII TO NFILE            85

1. INTRODUCTION

  NFILE stands for "New File Protocol".  NFILE was originally designed
  as a replacement for an older protocol named QFILE, with the goal of
  solving robustness problems of QFILE, hence the name "New File
  Protocol".

  NFILE was designed and implemented at Symbolics by Bernard S.
  Greenberg.  Mike McMahon made important contributions, especially in
  the design and implementation of the Byte Stream with Mark and Token
  List Transport layers.  NFILE has been used successfully for file
  access between Symbolics computers since 1985.  NFILE servers have
  been written for UNIX hosts as well.  NFILE is intended for use by
  any type of file system, not just the native Symbolics file system.

  NFILE is a file access protocol that supports a large set of
  operations on files and directories on remote systems, including:

           - Reading and writing entire files
           - Reading and writing selected portions of files
           - Deleting and renaming files

Greenberg & Keene [Page 3]

RFC 1037 NFILE - A File Access Protocol December 1987

           - Creating links
           - Listing, creating, and expunging directories
           - Listing and changing the properties of files
           - Enabling and disabling access capabilities on a remote
             host

  NFILE supports file transfer of binary or character files.

  The NFILE server provides information about any errors that occur in
  the course of a command.  In addition, NFILE has a robust scheme for
  handling aborts on the user side.

  This specification defines NFILE user version 2 and server version 2.
  We do not envision NFILE as an unchanging protocol, but rather as a
  protocol that could continue to develop if additional requirements
  are identified though the process of this Request for Comments.  The
  design of NFILE makes room for various useful extensions.  Some of
  the extensions that we are considering are described later on in this
  document:  See the section "Possible Future Extensions", section 13.

2. NFILE PROTOCOL LAYERING

  NFILE is a layered file protocol.  The layers are:

            +-----------------------------------------------+
            |client program or user interface               |
            +-----------------------------------------------+
            |NFILE                                          |
            +-----------------------------------------------+
            |Token List Transport Layer                     |
            +-----------------------------------------------+
            |Byte Stream with Mark                          |
            +-----------------------------------------------+
            |reliable host-host byte transmission protocol  |
            +-----------------------------------------------+

  Byte Stream with Mark is a simple protocol that guarantees that an
  out-of-band signal can be transmitted in the case of program
  interruption.  Byte Stream with Mark is to be layered upon extant
  byte stream protocols.  An important goal of the NFILE design was
  that NFILE could be built on any byte stream.  It is currently
  implemented on TCP and Chaosnet.  See the section "Byte Stream with
  Mark", section 12.

  The Token List Transport Layer is a protocol that facilitates the
  transmission of simple structured data, such as lists.  See the
  section "Token List Transport Layer", section 11.

Greenberg & Keene [Page 4]

RFC 1037 NFILE - A File Access Protocol December 1987

  The NFILE commands and command responses are transmitted in "token
  lists".  See the section "NFILE Commands", section 8.

  This specification does not include a client program or user
  interface to the protocol.  In the Symbolics implementation, the
  normal file operations transparently invoke NFILE, when the remote
  host is known to support NFILE.  Another possible interface to NFILE
  would be through a dedicated client program that would issue NFILE
  commands in response to explicit requests by the user.

3. OVERVIEW OF AN NFILE SESSION

  An NFILE session is a dialogue between two hosts.  The host that
  initiates the NFILE session is known as the "user side", and the
  other host is the "server side".  The user side sends all NFILE
  commands.  The server receives each command, processes it, and
  responds to it, indicating the success or failure of the command.

  The user side keeps track of commands sent and command responses
  received by using "transaction identifiers" to identify each command.
  The user side generates a transaction identifier (which must be
  unique per this dialogue) for each command, and sends the transaction
  identifier to the server along with the command.  Each NFILE server
  response includes the transaction identifier of the command with
  which the response is associated.  The server is not required to
  respond to commands in the same order that the user gave them.

  The user side sends NFILE commands over a bidirectional network
  connection called the "control connection".  The server sends its
  command responses on the same control connection.  The control
  connection governing the NFILE session is established at the
  beginning of the session.  If the control connection is ever broken,
  the NFILE session is ended.

  Whereas NFILE commands and responses are transmitted on the control
  connection, file data is transferred over "data channels".  An "input
  data channel" transfers data from server to user.  An "output data
  channel" transfers data from user to server.  Each input data channel
  is associated with an output data channel; together these two
  channels comprise a "data connection".

  Often more than one NFILE activity is occurring at any given time.
  For example, several files can be open and transferring data
  simultaneously; one or more commands can be in process at the same
  time; and the server can be simultaneously transmitting directory
  lists and processing further commands.  This happens in an
  implementation in which the user side has multiple processes, and
  several processes share a single NFILE server.

Greenberg & Keene [Page 5]

RFC 1037 NFILE - A File Access Protocol December 1987

4. NFILE CONTROL AND DATA CONNECTIONS

  The user and server communicate through a single control connection
  and a set of data connections.  Data connections are established and
  disestablished by NFILE commands.  The user side sends NFILE commands
  to the server over the control connection.  The server responds to
  every user command over this control connection.  The actual file
  data is transmitted over the data connections.

  User aborts can disrupt the normal flow of data on the control
  connection and data connections.  An important aspect of any file
  protocol is the way it handles user aborts.  NFILE uses a
  resynchronization procedure to bring the affected control connection
  or data channel from an unknown, unsafe state into a known state.
  After resynchronization, the control connection or data channel can
  be reused.  See the section "NFILE Resynchronization Procedure",
  section 9.

  THE CONTROL CONNECTION

  An NFILE session is begun when the NFILE user program connects to a
  remote host and establishes a network connection.  This initial
  connection is the control conection of the dialogue.  If TCP is used
  as the underlying protocol, contact NFILE's well-known port, 59.  If
  Chaos is used, use the contact name "NFILE".

  The control connection is the vehicle used by the user to send its
  commands, and the server to send its command responses.  These types
  of communication occur over the NFILE control connection:

        - The user side sends NFILE commands.
        - The server sends command responses.
        - The server sends "notifications" and "asynchronous errors".
          See the section "NFILE Errors and Notifications", section 10.
        - During resynchronization (a special circumstance) either the
          user or server sends a mark.

  All commands, command responses, and other data flowing over the
  NFILE control connection are transmitted in the format of "top-level
  token lists".  The control connection expects never to receive "loose
  tokens"; that is, tokens not contained in token lists.

Greenberg & Keene [Page 6]

RFC 1037 NFILE - A File Access Protocol December 1987

  DATA CONNECTIONS

  Data connections are established and discarded at user request, by
  means of two NFILE commands:  DATA-CONNECTION and UNDATA-CONNECTION.
  Each data connection is associated with a specific control
  connection, which is the same control connection that caused the data
  connection to be established.

  Each data connection is composed of two "data channels".  Each data
  channel is capable of sending data in one direction.  The term "input
  channel" refers to the data channel that transmits data from the
  server to the user side; "output channel" refers to the data channel
  that transmits data from the user to the server side.  Throughout the
  NFILE documentation, the terms "input channel" and "output channel"
  are seen from the perspective of the user side.  A single data
  channel can be used for one data transfer after another.

  The format of the data transferred on the data channels is defined as
  a "token list data stream".  See the section "Token List Data
  Stream", section 11.3. When the end of data is reached, the keyword
  token EOF is sent.  Occasionally, token lists are transmitted over
  the data channels, such as asynchronous error descriptions.

5. NFILE FILE OPENING MODES

  The NFILE OPEN command 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".  The term "opening" translates to a file stream
  in Symbolics terminology, a JFN in TOPS-20 terminology, and a file
  descriptor in UNIX terminology.  An opening usually keeps track of
  how many bytes have been read or written, and other bookkeeping
  information.

  NFILE supports two ways of transferring file data, "data stream mode"
  and "direct access mode".  A single mode is associated with each
  opening.  Note that an NFILE dialogue can have more than one opening,
  and thus use both modes.

  DATA STREAM MODE:

  Data stream mode of file transfer is the default mode of NFILE's OPEN
  command.  Data stream mode is appropriate when the entire file is
  transferred, either from user to server, or from server to user.
  Data stream mode is used more often than direct access mode.

Greenberg & Keene [Page 7]

RFC 1037 NFILE - A File Access Protocol December 1987

  The OPEN command includes a "handle" argument, which identifies the
  data channel to be used to transfer the data.  The handle is used in
  subsequent commands to reference this particular opening.  When a
  data stream opening is requested with the OPEN command, the file is
  opened and the data begins to flow immediately.

  The sending side transmits the entire contents of the specified file
  over the specified data channel as rapidly as the network permits.
  When the sending side reaches the end of the file, it transmits a
  special control token to signal end of file.  The receiving side
  expects an uninterrupted stream of bytes to appear immediately on its
  side of the data channel.

  The user gives the CLOSE command to terminate a data stream transfer.
  CLOSE results in closing the file.

  DIRECT ACCESS MODE:

  Direct access mode enables reading or writing data from a given
  starting point in a file through a specified number of bytes.  In
  direct access mode, data is requested and sent in individual
  transactions.  To request a direct access mode opening, the OPEN
  command is used with a DIRECT-FILE-ID argument.  (In data stream
  mode, no DIRECT-FILE-ID is supplied.)  The direct file identifier is
  used in subsequent commands to reference the direct access opening.

  When a file is opened in direct access mode, the flow of data does
  not start immediately.  Rather, the user gives either a READ command
  (to request data to flow from server to user) or a DIRECT-OUTPUT
  command (to request data to flow from user to server).  When reading,
  the READ command allows the user to specify the starting point and
  the number of bytes of data to transfer.  When writing, the FILEPOS
  command can be used to specify the starting point, before the
  DIRECT-OUTPUT command is given.  The user can give many READ and
  DIRECT-OUTPUT commands, one after another.

  The user side terminates the direct access transfer by using the
  CLOSE command.  The ABORT command can be given to terminate without
  transmitting all of the specified bytes.

Greenberg & Keene [Page 8]

RFC 1037 NFILE - A File Access Protocol December 1987

6. NFILE CHARACTER SET

  The NFILE character set <1> is an extension of standard ASCII.  NFILE
  command and response names use only the standard ASCII characters.
  However, the protocol supports the transfer of the non-ASCII
  characters in the NFILE character set; these characters might be
  stored in files, or might be used in pathnames.

  Servers on machines that do not natively use the NFILE character set
  must perform character set translations for character openings,
  depending on the requested translation mode.  No translation is
  required for binary openings.  There are three translation modes for
  character openings:  NORMAL, RAW, and SUPER-IMAGE.  Each mode
  specifies a way to translate between the server's native set and the
  NFILE character set.

  NORMAL mode is the default of the OPEN command.  The translation for
  NORMAL mode ensures that a file containing characters in the NFILE
  character set can be written to a remote host and read back intact.
  OPEN has optional keyword arguments to specify RAW or SUPER-IMAGE.
  RAW mode means to perform no translation whatsoever.  SUPER-IMAGE
  mode is intended for use by PDP-10 family machines only.  It is
  included largely as an illustration of a system-dependent extension.

  The details of each translation mode are given in Appendices:

        See the section "NORMAL Translation Mode", Appendix A.  See the
        section "RAW Translation Mode", Appendix B.  See the section
        "SUPER-IMAGE Translation Mode", Appendix C.

  The use of the NFILE character set brings up a difficulty involved
  with determining an exact position within a character file.  Some
  NFILE characters expand to more than one native character on some
  servers.  Thus, for character files, when we speak of a given
  position in a file or the length of a file, we must specify whether
  we are speaking in "NFILE units" or "server units", because the
  counting of characters is different.  This causes major problems in
  file position reckoning for character files.  Specifically, it is
  futile for a user side to carefully monitor file position during
  output by counting characters, when character translation is in
  effect.  The server's operating system interface for "position to
  point x in a file" necessarily operates in server units, but the user
  side has counted in NFILE units.  The user side cannot try to
  second-guess the translation-counting process without losing host-
  independence.  See the section "FILEPOS NFILE Command".

Greenberg & Keene [Page 9]

RFC 1037 NFILE - A File Access Protocol December 1987

7. CONVENTIONS USED IN THIS DOCUMENT

7.1 Mapping Data Types Into Token List Representation

  Throughout this NFILE specification, the data types of arguments,
  return values, asynchronous error descriptions, and notifications are
  described as being strings, integers, dates, time intervals, and so
  on.  However, each conceptual data type must be mapped into the
  appropriate token list representation for transmission.  The mapping
  of conceptual data types to token list representation is shown here:

   Conceptual Type     Token List Representation

   ----------------------------------------------------------------

   Keyword             A keyword token

   Keyword list        A token list of keyword tokens

   Integer             A numeric data token

   String              A data token containing the characters of the
                       string in the NFILE character set.

   Boolean Truth       The token known as BOOLEAN-TRUTH.

   Boolean False       The empty token list.

   Date                A numeric data token.  The date is expressed in
                       Universal Time format, which measures a time as
                       the number of seconds since January 1, 1900, at
                       midnight GMT.

   Date-or-never       Can be either a date or the empty token list,
                       representing "never".  "Never" is used for
                       values such as the time a directory was last
                       expunged, if it has never been expunged.

   Time interval       A numeric data token.  The time interval is
                       expressed in seconds.  A time interval
                       indicating "never" is represented by the empty
                       token list.

7.2 Format of NFILE Commands and Responses

  Each command description begins by giving the command format and
  response format.  Here is the beginning of the DATA-CONNECTION
  command description:

Greenberg & Keene [Page 10]

RFC 1037 NFILE - A File Access Protocol December 1987

  Command:  (DATA-CONNECTION tid new-input-handle new-output-handle)

  Response: (DATA-CONNECTION tid connection-identifier)

  The command descriptions follow these conventions:

   1. NFILE commands and responses are transmitted as top-level token
      lists.

      Top-level token lists are enclosed in parentheses in these
      command descriptions.  These parentheses are not sent literally
      across the control or data connections, but are a shorthand
      representation of special control tokens that delimit top-level
      token lists.  Specifically, TOP-LEVEL-LIST-BEGIN starts a top-
      level token list; TOP-LEVEL-LIST-END ends a top-level token list.

   2. NFILE command names are keywords.

      The command name is required in every command and command
      response.  All NFILE command names are keywords.  Keywords appear
      in the NFILE documentation as their names in uppercase.  For
      example, DATA-CONNECTION and DELETE are two command names.

   3. A unique transaction identifier (tid) identifies each command.

      The transaction identifier is a string made up by the user side
      to identify this particular transaction, which is composed of the
      command and the response associated with this command.  The
      transaction identifier is abbreviated in the command descriptions
      as tid.  Transaction identifiers are limited to fifteen
      characters in length.  The transaction identifier is required in
      every command and command response.

  OPTIONAL ARGUMENTS

  Many NFILE commands have "optional arguments".  Optional arguments
  can be supplied (with appropriate values), or left out.  If optional
  arguments are left out, their omission must be made explicit by means
  of substituting the empty token list in their place.  The only
  exception to that rule is for trailing optional arguments or return
  values, which can be omitted without including the empty token list.

  For example, the text of the DELETE command description explains that
  either a handle or a pathname must be supplied, but not both;
  therefore, one of them is an optional argument.  Here is the command
  format of DELETE:

        (DELETE tid handle pathname)

Greenberg & Keene [Page 11]

RFC 1037 NFILE - A File Access Protocol December 1987

   If you supply a handle and no pathname, the command format is:

        (DELETE tid handle)

   If you supply a pathname and no handle, the command format is:

        (DELETE tid empty-token-list pathname)

  The empty token list in the token list stream appears as a LIST-BEGIN
  followed immediately by a LIST-END.

  OPTIONAL KEYWORD/VALUE PAIRS

  Four NFILE commands have "optional keyword/value pairs".  These
  commands are: COMPLETE, LOGIN, OPEN, and READ.  Optional
  keyword/value pairs can be either included in the command or omitted
  entirely.  There is no need to substitute the empty token list for
  ommitted optional keyword tokens, unlike optional arguments.  The
  order of the option keyword/value pairs is not significant.

  If included, optional keyword/value pairs are a sequence of
  alternating keywords and values.  The values associated with the
  keywords can be keywords, lists, strings, Booleans, integers, dates,
  date-or-never's, and time intervals.  The text of each command
  description states what type of value is appropriate for each
  optional keyword.

  Optional keyword/value pairs appear in the text as the keyword only,
  in uppercase letters.  For example, here is the format of the LOGIN
  command:

  Command Format:

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

  FILE-SYSTEM and USER-VERSION are two optional keywords associated
  with the LOGIN command.  The user side can supply USER-VERSION, and
  omit FILE-SYSTEM as shown in this example:

        (LOGIN x105 tjones let-me-in USER-VERSION 2)

  As seen above, the optional keyword/value pair USER-VERSION, if
  supplied in a command, consists of the keyword USER-VERSION followed
  by the value to be used for that keyword (in this example, 2).

Greenberg & Keene [Page 12]

RFC 1037 NFILE - A File Access Protocol December 1987

7.3 Data Channel Handles and Direct File Identifiers

  Several NFILE commands require an argument that specifies an opening.
  This kind of argument is called a handle in the command description.
  It is always a string type argument.  A handle can be either a data
  channel handle or a direct file identifier, depending on the mode of
  the opening:

  Data Stream

  The handle must identify a data channel that is bound to an opening.

  Direct Access

  In general, the handle must be a direct file identifier.  A direct
  file identifier specifies a direct access opening.  It is the same as
  the value supplied in the DIRECT-FILE-ID keyword/value pair in the
  OPEN command.  It is used for all operations that identify an opening
  rather than a data channel.

  Two NFILE commands applicable to direct access openings are
  exceptions to the general rule.  The handle supplied in ABORT and
  CONTINUE cannot be a direct file identifier, but must be a data
  channel handle instead.

7.4 Syntax of File and Directory Pathname Arguments

  Some arguments and return values in the NFILE command descriptions
  represent file pathnames.  These are strings in the pathname syntax
  native to the server host.  These pathnames contain no host
  identifiers of any kind.  These pathnames must be fully defaulted, in
  the sense that they have a directory and file name (and file type, if
  the server operating system supports file types).  If appropriate, a
  device is referenced in the pathname.  If the server file system
  supports version numbers, there is always an explicit version number,
  even if that number or other specification is that system's
  representation of "newest" or "oldest".

Greenberg & Keene [Page 13]

RFC 1037 NFILE - A File Access Protocol December 1987

  Here are some examples of file pathnames, for different server hosts:

  Server Host     Example of File Pathname

  ------------------------------------------------------------

     UNIX            /usr/max/life.c

     TOPS-20         ps:<max>life.bin.17

     VMS             MACD:[MAX]LIFE.FOR;3

     Symbolics LMFS  >max>life.lisp.newest

  ------------------------------------------------------------

  The CREATE-DIRECTORY and HOME-DIRECTORY commands take a directory as
  an argument.  In NFILE commands, a directory is represented by a
  string that names the directory.  In most cases this string is in the
  syntax native to the server host.  However in some cases the native
  format is modified somewhat to clarify that the string names a
  directory, and not a file.  For example, a directory on UNIX is
  represented by "/usr/max/", not "/usr/max".

  Here are some examples of directory pathnames for different server
  hosts:

  Server Host     Example of Directory Pathname

  ------------------------------------------------------------

     UNIX            /usr/max/

     TOPS-20         <max>

     VMS             MACD:[MAX]

     Symbolics LMFS  >max>hacks>

  ------------------------------------------------------------

7.5 Format of NFILE File Property/Value Pairs

  Several NFILE commands request information regarding the properties
  of files or directories.  These commands include:  DIRECTORY,
  MULTIPLE-FILE-PLISTS, PROPERTIES, and CHANGE-PROPERTIES.  This
  section describes how file property information is conveyed over the
  token list stream.

Greenberg & Keene [Page 14]

RFC 1037 NFILE - A File Access Protocol December 1987

  File property information is usually sent in property/value pairs,
  where the property identifies the property, and the following value
  gives the value of that property for the specified file.

  Each property is denoted either by a keyword or an integer.  You can
  mix both ways of specifying properties (keyword or integer) within a
  single description.  An integer is interpreted as an index into the
  Property Index Table, an array of property keywords.  The server can
  optionally send a Property Index Table to the user during the
  execution of the LOGIN command, although it is not required.  This
  greatly reduces the length of transmissions.

  In command arguments, file properties cannot be specified with
  integers; keywords must be used to specify file properties in command
  arguments.  Integers can be used to denote file properties only in
  command responses.

  We now list the keywords associated with file properties.  This list
  is not intended to be restrictive.  If a programmer implementing
  NFILE needs a new keyword, a new keyword (not on this list) can be
  invented.  The type of value of any new keywords is by default
  string.  The keywords are sorted here by conceptual data type:

   Data type       Keywords denoting file properties

  ----------------------------------------------------------------

   Integers        BLOCK-SIZE, BYTE-SIZE, GENERATION-RETENTION-COUNT,
                   LENGTH-IN-BLOCKS, LENGTH-IN-BYTES,
                   DEFAULT-GENERATION-RETENTION-COUNT

   Dates           CREATION-DATE, MODIFICATION-DATE

   Date-or-never's REFERENCE-DATE, INCREMENTAL-DUMP-DATE,
                   COMPLETE-DUMP-DATE, DATE-LAST-EXPUNGED,
                   EXPIRATION-DATE

   Time intervals  AUTO-EXPUNGE-INTERVAL

   Keyword Lists   SETTABLE-PROPERTIES, LINK-TRANSPARENCIES,
                   DEFAULT-LINK-TRANSPARENCIES

   Boolean values  DELETED, DONT-DELETE, DONT-DUMP, DONT-REAP,
                   SUPERSEDE-PROTECT, NOT-BACKED-UP, OFFLINE,
                   TEMPORARY, CHARACTERS, DIRECTORY

Greenberg & Keene [Page 15]

RFC 1037 NFILE - A File Access Protocol December 1987

   Strings         ACCOUNT, AUTHOR, LINK-TO, PHYSICAL-VOLUME,
                   PROTECTION, VOLUME-NAME, PACK-NUMBER, READER,
                   DISK-SPACE-DESCRIPTION, and any keywords not
                   on this list

  Note that these keyword names are intended to imply the semantics of
  the properties.  For a discussion of the semantics of CREATION-DATE:
  See the section "NFILE OPEN Response Return Values", section 8.20.2.
  The "Reference Guide to Streams, Files, and I/O" in the Symbolics
  documentation set details the semantics that Symbolics associates
  with these properties.

8. NFILE COMMANDS

  It is important to understand the conventions used in each of the
  following command descriptions.  See the section "Conventions Used in
  This Document", section 7.

8.1 ABORT Command

  Command:  (ABORT tid input-handle)

  Response: (ABORT tid)

  ABORT cleanly interrupts and prematurely terminates a single direct
  access mode data transfer initiated with READ.  The required input-
  handle string argument identifies a data channel on which an input
  transfer is currently taking place; this must be a direct access
  transfer.  input-handle must identify a data channel; it cannot be a
  direct file identifier.

  Upon receiving the ABORT command, the server checks to see if a
  transfer is still active on that channel.  If so, the server
  terminates the transfer by telling the data connection logical
  process to stop transferring bytes of data.  The user side needs to
  issue this command only when there are outstanding unread bytes.
  This excludes the case of the data channel having been disestablished
  or reallocated by the user side.

  Whether or not a transfer is active on that channel, the user side
  puts the data channel into the unsafe state.  Before the data channel
  can be used again, it must be resynchronized.

8.2 CHANGE-PROPERTIES Command

  Command:  (CHANGE-PROPERTIES tid handle pathname property-pairs)

  Response: (CHANGE-PROPERTIES tid)

Greenberg & Keene [Page 16]

RFC 1037 NFILE - A File Access Protocol December 1987

  CHANGE-PROPERTIES changes one or more properties of a file.  Either a
  handle or a pathname must be given, but not both.  Whichever one is
  given must be supplied as a string.  handle identifies a data channel
  that is bound to an open file; it can be a direct file identifier.
  pathname identifies a file on the server machine.

  property-pairs is a required token list of keyword/value pairs, where
  the name of the property to be changed is the keyword, and the
  desired new property value is the value.

  The properties that can be changed are host-dependent, as are any
  restrictions on the values of those properties.  The properties that
  can be changed are the same as those returned as settable-properties,
  in the command response for the PROPERTIES command.

  The server tries to modify all the properties listed in property-
  pairs to the desired new values.  There is currently no definition
  about what should be done if the server can successfully change some
  properties but not others.

  For further information on file property keywords and associated
  values:  See the section "Format of NFILE File Property/Value Pairs",
  section 7.5.

8.3 CLOSE Command

  Command:  (CLOSE tid handle abort-p)

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

  CLOSE terminates a data transfer, and frees a data channel.  The
  handle must be a data channel handle for a data stream opening, or a
  direct file identifier for a direct access opening.  If a data
  channel is given, a transfer must be active on that handle.  If
  abort-p is supplied as Boolean truth, the file is close-aborted, as
  described below.

  "Closing the file" has different implications specific to each
  operating system.  It generally implies invalidation of the pointer
  or logical identifier obtained from the operating system when the
  file was "opened", and freeing of operating system and/or job
  resources associated with active file access.  For output files, it
  involves ensuring that every last bit sent by the user has been
  successfully written to disk.  The server should not send a
  successful response until all these things have completed
  successfully.

Greenberg & Keene [Page 17]

RFC 1037 NFILE - A File Access Protocol December 1987

  In either data stream or direct access mode, the user can request the
  server to close-abort the file, instead of simply closing it.  To
  close-abort a file means to close it in such a way, if possible, that
  it is as if the file had never been opened.  In the specific case of
  a file being created, it must appear as if the file had never been
  created.  This might be more difficult to implement on certain
  operating systems than others, but tricks with temporary names and
  close-time renamings by the server can usually be used to implement
  close-abort in these cases.  In the case of a file being appended to,
  close-abort means to forget the appended data.

  AN UNSUCCESSFUL CLOSE OPERATION

  For the normal CLOSE operation (not a close-abort), 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
  description to the user, to which the user has not yet responded with
  a CONTINUE command.  If so, the server is unable to close the file,
  and therefore sends a command error 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.

  A SUCCESSFUL CLOSE OPERATION

  The return values for OPEN and CLOSE are syntactically identical, but
  the values might change between the time of the file being opened and
  when it is closed.  For example, the truename return value is
  supplied after all the close-time renaming of output files is done
  and the version numbers resolved (for operating systems supporting
  version numbers).  Therefore, on some systems the truename of a file
  has one value at the time it is opened, and a different value when it
  has been closed.  For a description of the CLOSE return values:  See
  the section "NFILE OPEN Response Return Values", section 8.20.2.

  If the user gives the CLOSE command with abort-p supplied as Boolean
  truth, thus requesting a close-abort of the file, the server need not
  check whether an asynchronous error description is outstanding on the
  channel.  The server simply close-aborts the file.

Greenberg & Keene [Page 18]

RFC 1037 NFILE - A File Access Protocol December 1987

8.4 COMPLETE Command

  Command:  (COMPLETE tid string pathname DIRECTION NEW-OK DELETED)

  Response: (COMPLETE tid new-string success)

  COMPLETE performs file pathname completion.

  string is a partial filename typed by the user and pathname is the
  default name against which it is being typed.  Both string and
  pathname are required arguments, and are of type string.  The
  remaining arguments are optional keyword/value pairs.

  NEW-OK is Boolean; if followed by Boolean truth, the server should
  allow either a file that already exists, or a file that does not yet
  exist.  The default of NEW-OK is false; that is, the server does not
  consider files that do not already exist.

  DELETED is a Boolean type argument; if followed by Boolean truth, the
  server is instructed to look for files that have been deleted but not
  yet expunged, as well as non-deleted files.  The default is to ignore
  soft-deleted files.

  DIRECTION can be followed by READ, to indicate that the file is to be
  read.  If the file is to be written, DIRECTION can be followed by
  WRITE.  The default is READ.

  The filename is completed according to the files present in the host
  file system, and the expanded string new-string is returned. New-
  string is always a string containing a file name:  either the
  original string, or a new, more specific string.  The value of
  success indicates the status of the completion. The keyword value OLD
  or NEW means complete success, whereas the empty token list means
  failure.  The following values of success are possible:

  Value               Meaning

  ----------------------------------------------------------------

  OLD                 Success:  the string completed to the name of
                      a file that exists.

  NEW                 Success:  the string completed to the name of
                      a file that could be created.

  Empty token list    Failure due to one of these reasons:

                      The file is on a file system that does not

Greenberg & Keene [Page 19]

RFC 1037 NFILE - A File Access Protocol December 1987

                      support completion.  new-string is supplied as
                      the unchanged string.

                      There is no possible completion.  new-string
                      is supplied as the unchanged string.

                      There is more than one possible completion.
                      The given string is completed up to the first
                      point of ambiguity, and the result is supplied
                      as new-string.

                      A directory name was completed.  Completion
                      was not successful because additional
                      components to the right of this directory
                      remain to be specified.  The string is
                      completed through the directory name and the
                      delimiter that follows it, and the result is
                      returned in new-string.

  The semantics of COMPLETE are not documented here.  See the
  "Reference Guide to Streams, Files, and I/O" in the Symbolics
  documentation set for the recommended semantics of COMPLETE.

8.5 CONTINUE Command

  Command:  (CONTINUE tid handle)

  Response: (CONTINUE tid)

  CONTINUE resumes a data transfer that was temporarily suspended due
  to an asynchronous error.  Each asynchronous error description has an
  optional argument of RESTARTABLE, indicating whether it makes any
  sense to try to continue after this particular error occurred.
  CONTINUE tries to resume the data transfer if the error is
  potentially recoverable, according to the RESTARTABLE argument in the
  asynchronous error description.  For a discussion of asynchronous
  errors:  See the section "NFILE Errors and Notifications", section
  10.

  handle is a required string-type argument that refers to the handle
  of the data channel that received an asynchronous error.  That data
  channel could have been in use for a data stream or direct access
  transfer.  handle cannot be a direct file identifier.

  If the asynchronous error description does not contain the
  RESTARTABLE argument, and the user issues the CONTINUE command
  anyway, the server gives a command error response.

Greenberg & Keene [Page 20]

RFC 1037 NFILE - A File Access Protocol December 1987

8.6 CREATE-DIRECTORY Command

  Command:  (CREATE-DIRECTORY tid pathname property-pairs)

  Response: (CREATE-DIRECTORY tid dir-truename)

  CREATE-DIRECTORY creates a directory on the remote file system.  The
  required pathname argument is a string identifying the pathname of
  the directory to be created.  The return value dir-truename is the
  pathname of the directory that was successfully created.  Both of
  these pathnames are directory pathnames:  See the section "Syntax of
  File and Directory Pathname Arguments", section 7.4.

  property-pairs is a keyword/value list of properties that further
  define the attributes of the directory to be created.  The allowable
  keywords and associated values are operating system dependent;
  typically they indicate arguments to be given to the native primitive
  for creating directories.

  If property-pairs is supplied as the empty token list, default access
  and creation attributes apply and should be assured by the server.
  See the section "Format of NFILE File Property/Value Pairs", section
  7.5.

8.7 CREATE-LINK Command

  Command:  (CREATE-LINK tid pathname target-pathname properties)

  Response: (CREATE-LINK tid link-truename)

  CREATE-LINK creates a link on the remote file system.

  pathname is the pathname of the link to be created; target-pathname
  is the place in the file system to which the link points.  Both are
  required arguments.  The return value link-truename names the
  resulting link.

  If a server on a file system that does not support links receives the
  CREATE-LINK command, it sends a command error response.

  The arguments pathname and target-pathname, and the return value
  link-truename, are all strings in the full pathname syntax of the
  server host.  See the section "Syntax of File and Directory Pathname
  Arguments", section 7.4.

  The required properties argument is a token list of keyword/value
  pairs. These properties and their values specify certain attributes
  to be given to the link.  The allowable keywords and associated

Greenberg & Keene [Page 21]

RFC 1037 NFILE - A File Access Protocol December 1987

  values are operating system dependent; typically they indicate
  arguments to be given to the native primitive for creating links.

  If no property pairs are given in the command, the server should
  apply a reasonable default set of attributes to the link.  See the
  section "Format of NFILE File Property/Value Pairs", section 7.5.

8.8 DATA-CONNECTION Command

  Command:  (DATA-CONNECTION tid new-input-handle new-output-handle)

  Response: (DATA-CONNECTION tid connection-identifier)

  DATA-CONNECTION enablesthe user side to initiate the establishment of
  a new data connection.  The user side supplies two required string
  arguments, new-input-handle and  new-output-handle.  These arguments
  are used by subsequent commands to reference the two data channels
  that constitute the data connection now being created.  new-input-
  handle describes the server-to-user data channel, and new-output-
  handle describes the user-to-server channel.  new-input-handle and
  new-output-handle cannot refer to any data channels already in use.

  Upon receiving the DATA-CONNECTION command, the server arranges for a
  logical port (called socket or contact name on some networks) to be
  made available on the foreign host machine.  When the server has made
  that port available, it must inform the user of its identity.  The
  server relays that information in the command response, in the
  required connection-identifier, a string.  The server then listens on
  the port named by connection-identifier, and waits for the user side
  to connect to it.

  Upon receiving the success command response, the user side supplies
  the connection-identifier to the local network implementation, in
  order to connect to the specified port.  The data connection is not
  fully established until the user side connects successfully to that
  port.  This command is unusual in that the successful command
  response does not signify the completion of the command; it indicates
  only that the server has fulfilled its responsibility in the process
  of establishing a data connection.

Greenberg & Keene [Page 22]

RFC 1037 NFILE - A File Access Protocol December 1987

  The connection-identifier informs the user of the correct identity of
  the logical port that the server has provided.  NFILE expects the
  connection-identifier to be a string.  For TCP this string is the
  port number represented in decimal.  For Chaosnet, this string is the
  contact name.  The connection-identifier is used only once; in all
  subsequent NFILE commands that need to reference either of the data
  channels that constitute this data connection, the new-input-handle
  and new-output-handle are used.

  For background information:  See the section "NFILE Control and Data
  Connections", section 4.

8.9 DELETE Command

  Command:  (DELETE tid handle pathname)

  Response: (DELETE tid)

  DELETE deletes a file on the remote file system.

  Either a handle or a pathname must be supplied, but not both.  If
  given, the handle must be a data channel handle for a data stream
  opening, or a direct file identifier for a direct access opening.
  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.

  With a pathname supplied, the DELETE command causes the specified
  file to be deleted.  DELETE has different results depending on the
  operating system involved.  That is, DELETE causes soft deletion on
  TOPS-20 and LMFS, and hard deletion on UNIX and Multics.  If an
  attempt is made to delete a delete-through link on a Symbolics LMFS,
  its target is deleted instead.

  If the handle argument is supplied to DELETE, the server deletes the
  open file bound to the data channel specified by handle at close
  time.  This is true in both the output and input cases.

8.10 DIRECT-OUTPUT Command

  Command:  (DIRECT-OUTPUT tid direct-handle output-handle)

  Response: (DIRECT-OUTPUT tid)

  DIRECT-OUTPUT starts and stops output data flow for a direct access
  file opening.  DIRECT-OUTPUT explicitly controls binding and
  unbinding of an output data channel to a direct access opening.

Greenberg & Keene [Page 23]

RFC 1037 NFILE - A File Access Protocol December 1987

  direct-handle is a required argument, and output-handle is optional.

  If supplied, output-handle is a request to bind an output data
  channel (indicated by output-handle) to the direct access opening
  designated by the direct-handle.  The specified output data channel
  must be free.  The server binds the data channel and begins accepting
  data from that connection and writing it to the opening.

  If the output-handle is omitted, this is a request to unbind the
  channel and terminate the active output transfer.

8.11 DIRECTORY Command

  Command:  (DIRECTORY tid input-handle pathname control-keywords
             properties)

  Response: (DIRECTORY tid)

  DIRECTORY returns a directory listing including the identities and
  attributes for logically related groups of files, directories, and
  links.  If the command is successful, a single token list containing
  the requested information is sent over the data channel specified by
  input-handle, and the data channel is then implicitly freed by both
  sides <2>.  For details on the format of the token list:  See the
  section "NFILE DIRECTORY Data Format", section 8.11.1.

  pathname specifies the files that are to be described; 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.

  The pathname generally contains wildcard characters, in operating-
  system-specific format, describing potential file name matches.  Most
  operating systems provide a facility that accepts such a pathname and
  returns information about all files matching this pathname.  Some
  operating systems allow wildcard (potential multiple) matches in the
  directory or device portions of the pathname; other operating systems
  do not.  There is no clear contract at this time about what is
  expected of servers on systems that do not allow wildcard matches (or
  some kinds of wild card matches), when presented with a wildcard.

  properties is a token list of keywords that are the names of
  properties.  If properties is omitted or supplied as the empty token
  list, the server sends along all properties.  If any properties are
  supplied, the user is requesting the server to send only those
  properties.

Greenberg & Keene [Page 24]

RFC 1037 NFILE - A File Access Protocol December 1987

  control-keywords ARGUMENT TO DIRECTORY

  control-keywords is a token list of keywords.  The control-keywords
  affect the way the DIRECTORY command works on the server machine.
  Although some of the options below request the server to limit (by
  some filter) the data to be returned, it is never an error if the
  server returns more information than is requested.

  The following keywords are recognized:

  DELETED

  Includes soft-deleted files in the directory list.  Without this
  option, they must not be included. Such files have the DELETED
  property indicated as true" among their properties.  DELETED is
  ignored on systems that do not support soft deletion.

  DIRECTORIES-ONLY

  This option changes the semantics of DIRECTORY fairly drastically.
  Normally, the server returns information about all files,
  directories, and links whose pathnames match the supplied pathname.
  This means that for each file, directory, or link to be listed, its
  directory name must match the potentially wildcarded) directory name
  in the supplied pathname, its file name must match the file name in
  the supplied pathname, and so on.

  When DIRECTORIES-ONLY is supplied, the server is to list only
  directories, not whose pathnames match the supplied pathname, but
  whose pathnames expressed as directory pathnames match the
  (potentially wildcarded) directory portion of the supplied pathname.
  The description of the PROBE-DIRECTORY keyword that can be supplied
  as the direction argument of the OPEN command discusses this:  See
  the section "OPEN Command", section 8.20.

  It is not yet established what servers on hosts that do not support
  this type of action natively are to do when presented with
  DIRECTORIES-ONLY and a pathname with a wildcard directory component.

  FAST Speeds up the operation and data transmission by not listing any
  properties at all for the files concerned; that is, only the
  truenames are returned.

Greenberg & Keene [Page 25]

RFC 1037 NFILE - A File Access Protocol December 1987

  NO-EXTRA-INFO

  Specifies that the server is to suppress listing those properties
  that are generally more difficult or expensive to obtain.  This
  typically eliminates listing of directory-specific properties such as
  information about default generation counts and expunge dates.

  SORTED

  This causes the directory listing to be sorted.  The sorting is done
  alphabetically by directory, then by file name, then file type, then
  file version (by increasing version number).

8.11.1 NFILE DIRECTORY Data Format

  If the NFILE DIRECTORY command completes successfully, a single token
  list containing the requested directory information is sent on the
  data channel specified by the input-handle argument in the DIRECTORY
  command.  This section describes the format of that single token
  list, and gives further detail on the properties argument to
  DIRECTORY.

  The token list is a top-level token list, so it is delimited by TOP-
  LEVEL-LIST-BEGIN and TOP-LEVEL-LIST-END.  The top-level token list
  contains embedded token lists.  The first embedded token list
  contains the empty token list followed by property/value pairs
  describing property information of the file system as a whole rather
  than of a specific file.  NFILE requires one property of the file
  system to be present: DISK-SPACE-DESCRIPTION is a string describing
  the amount of free file space available on the system.  The following
  embedded token lists contain the pathname of a file, followed by
  property/value pairs describing the properties of that file.

  The following example shows the format of the top-level token list
  returned by DIRECTORY, for two files.  It is expected that the server
  return several property/value pairs for each file; the number of
  pairs returned is not constrained.  In this example, two
  property/value pairs are returned for the file system, two pairs are
  returned for the first file, and only one pair is returned for the
  second file.

            TOP-LEVEL-LIST-BEGIN
            LIST-BEGIN       - first embedded token list starts
            LIST-BEGIN       - an empty embedded token list starts
            LIST-END         - the empty embedded token list ends
            prop1 value1     - property/value pairs of file system
            prop2 value2
            LIST-END

Greenberg & Keene [Page 26]

RFC 1037 NFILE - A File Access Protocol December 1987

            LIST-BEGIN
            pathname1        - pathname of the first file
            prop1 value1     - property/value pairs of first file
            prop2 value2
            LIST-END
            LIST-BEGIN
            pathname2        - pathname of the second file
            prop1 value1     - property/value pairs of second file
            LIST-END
            TOP-LEVEL-LIST-END

  The following example is designed to illustrate 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 squarbe
  rackets.  respectively. The indentation, blank spaces, 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.

                  ([   [ ]    prop1 value1 prop2 value2]
                   [pathname1 prop1 value1 prop2 value2]
                   [pathname2 prop1 value1])

  The 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 further information on file property/value pairs:  See the
  section "Format of NFILE File Property/Value Pairs", section 7.5.

8.12 DISABLE-CAPABILITIES Command

  Command:  (DISABLE-CAPABILITIES tid capability)

  Response: (DISABLE-CAPABILITIES tid cap-1 success-1
                 cap-2 success-2 cap-3 success-3 ...)

  DISABLE-CAPABILITIES causes an access capability to be disabled on
  the server machine.  capability is a string naming the capability to
  be disabled.  The meaning of the capability is dependent on the
  operating system.

  The return values cap-1, cap-2, and so on, are strings specifying
  names of capabilities.  If the capability named by cap-1 was
  successfully disabled, the corresponding success-1 is supplied as
  Boolean truth; otherwise it is the empty token list.

Greenberg & Keene [Page 27]

RFC 1037 NFILE - A File Access Protocol December 1987

  Although the user can specify only one capability to disable, it is
  conceivable that the result of disabling that particular capability
  is the disabling of other, related capabilities.  That is why the
  command response can contain information on more than one capability.

8.13 ENABLE-CAPABILITIES Command

  Command:  (ENABLE-CAPABILITIES tid capability password)}

  Response: (ENABLE-CAPABILITIES tid cap-1 success-1
             cap-2 success-2 cap-3 success-3 ...)

  ENABLE-CAPABILITIES causes an access capability to be enabled on the
  server machine.  The password argument is optional, and should be
  included only if it is needed to enable this particular capability.
  Both password and capability are strings.  The meaning of the
  capability is dependent on the operating system.

  The return values cap-1, cap-2 and so on, are strings specifying
  names of capabilities.  If the capability named by cap-1 was
  successfully enabled, the corresponding success-1 is supplied as
  Boolean truth; otherwise it is the empty token list.

  Although the user can specify only one capability to enable, it is
  conceivable that the result of enabling that particular capability is
  the enabling of other, related capabilities.  That is why the command
  response can contain information on more than one capability.

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.

Greenberg & Keene [Page 28]

RFC 1037 NFILE - A File Access Protocol December 1987

  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

Greenberg & Keene [Page 29]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 30]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 31]

RFC 1037 NFILE - A File Access Protocol December 1987

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.

Greenberg & Keene [Page 32]

RFC 1037 NFILE - A File Access Protocol December 1987

  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

Greenberg & Keene [Page 33]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 34]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 35]

RFC 1037 NFILE - A File Access Protocol December 1987

  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:

Greenberg & Keene [Page 36]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 37]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 38]

RFC 1037 NFILE - A File Access Protocol December 1987

  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:

Greenberg & Keene [Page 39]

RFC 1037 NFILE - A File Access Protocol December 1987

              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

Greenberg & Keene [Page 40]

RFC 1037 NFILE - A File Access Protocol December 1987

     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.

Greenberg & Keene [Page 41]

RFC 1037 NFILE - A File Access Protocol December 1987

     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.

Greenberg & Keene [Page 42]

RFC 1037 NFILE - A File Access Protocol December 1987

     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.

Greenberg & Keene [Page 43]

RFC 1037 NFILE - A File Access Protocol December 1987

  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

Greenberg & Keene [Page 44]

RFC 1037 NFILE - A File Access Protocol December 1987

     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

Greenberg & Keene [Page 45]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 46]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 47]

RFC 1037 NFILE - A File Access Protocol December 1987

  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:

Greenberg & Keene [Page 48]

RFC 1037 NFILE - A File Access Protocol December 1987

            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.

Greenberg & Keene [Page 49]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 50]

RFC 1037 NFILE - A File Access Protocol December 1987

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.

Greenberg & Keene [Page 51]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

Greenberg & Keene [Page 52]

RFC 1037 NFILE - A File Access Protocol December 1987

  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.

9. NFILE RESYNCHRONIZATION PROCEDURE

  Ordinarily, the user side sends NFILE commands to the server side
  over the control connection; the server side responds to every user
  command, and file data is transmitted over the data channels.  This
  section describes a resynchronization procedure that takes place when
  something disturbs the usual course of events.

  First, if the server side aborts while sending or receiving data,
  nothing can be done to salvage the connection between the two hosts.
  The control connection and any data channels associated with this
  connection are broken.  This happens rarely, if at all.

  It is not unusual for the user side to abort file operations, either
  commands or data transfer.  On a Symbolics computer, the user can do
  this by pressing CONTROL-ABORT.  An important aspect of any file
  protocol is the way it handles the situation when the user side
  aborts file operations.

  An NFILE user side reacts to user side aborts by immediately marking
  the connection unsafe.  When a control connection is unsafe, it must
  be resynchronized before it can be used again.  Data channels can
  also be marked unsafe, and must also be resynchronized before further
  use.  The resynchronization process rids the connection (whether
  control or data connection) of bytes of data that are now unwanted,
  and thus cleans up the channel so it can be used again.

  The resynchronization procedure is somewhat complex, but it fulfills
  a genuine need.  For those interested, a brief design discussion is
  included as note <3>.

Greenberg & Keene [Page 53]

RFC 1037 NFILE - A File Access Protocol December 1987

9.1 NFILE Control Connection Resynchronization

  NFILE requires any unsafe control connection to undergo a
  resynchronization procedure before further use.  Therefore, the
  resynchronization does not necessarily occur immediately after the
  control connection is marked unsafe.  The user side initiates the
  control connection resynchronization when another operation on the
  control connection is attempted.

  A "mark" is defined in the context of Byte Stream with Mark:  See the
  section "Discussion of Byte Stream with Mark", section 12.1.

  USER SIDE STEPS:  CONTROL CONNECTION RESYNCHRONIZATION

      1. The user side sends a mark over the control connection to
         the server.

      2. The user side sends the ASCII characters USER-RESYNC-DUMMY
         (as a data token) to the server.

      3. The user side sends a second mark to the server.

      4. The user side declares the control connection safe (at the
         token list level).

      5. The user side generates and sends a unique data token to
         the server.

      6. The user side then waits, expecting to detect a mark
         followed by the unique data token.  The user side reads and
         discards all tokens and marks until the desired match is
         found.

  Once the user side detects the mark and unique data token, the
  control connection has been fully resynchronized, and can be used
  again.

  SERVER SIDE STEPS:  CONTROL CONNECTION RESYNCHRONIZATION

       1. The server side detects a mark.  The server is thus alerted
          that the control connection is unsafe, and that
          resynchronization is in progress.

       2. The server continues to read data coming from the user side
          until it detects the second mark, and the token following
          it.

Greenberg & Keene [Page 54]

RFC 1037 NFILE - A File Access Protocol December 1987

       3. The server checks to see if the token following the mark is
          USER-RESYNC-DUMMY.  This rare situation occurs if the user
          aborts during the course of the resynchronization itself.
          If so, the server side discards the USER-RESYNC-DUMMY
          token.  The control connection is still unsafe, and the
          user side restarts the resynchronization procedure; the
          server side therefore begins at Step 2 again.

       4. If the token following the mark is not USER-RESYNC-DUMMY
          (this is the expected circumstance), the server should have
          received a single data token that is the unique data token
          generated by the user side.

              a. The server sends a mark to the user side.

              b. The server declares the control connection safe (at
                 the token list level).

              c. The server sends the unique data token to the user
                 side.

       5. If the server detects something following the mark that was
          neither USER-RESYNC-DUMMY nor a single data token, a
          protocol error has occurred.

9.2 NFILE Data Connection Resynchronization

  The NFILE data channel resynchronization procedure is similar to the
  NFILE control connection resynchronization.  Both procedures are
  based on a mark signalling the unsafe condition, then a second mark
  followed by a unique identifier.  One important difference between
  the two procedures is the circumstances in which they occur.  Control
  connections are put into unsafe states only when the user aborts
  during control connection I/O operations.  Data channels are made
  unsafe by a larger set of circumstances:

Greenberg & Keene [Page 55]

RFC 1037 NFILE - A File Access Protocol December 1987

      - User aborts occur during the file protocol operations that
        assign and deassign data channels.  This is the most common
        cause of data channels becoming unsafe.

      - A server receives a CLOSE command (with abort-p supplied as
        Boolean truth) specifying an open file that has not finished
        transmitting data.  That is, file reading is aborted.

      - The ABORT command is issued, causing data channels to be
        made unsafe.

      - The FILEPOS command is issued, causing the input data
        channel to become unsafe.

  The resynchronization clears the data channel of unwanted data from
  aborted operations and puts the data channel in a known state.  The
  data channel resynchronization procedure is invoked when the user
  side gives the RESYNCHRONIZE-DATA-CHANNEL command over the control
  connection.

  The following policies can be used to improve response time, but are
  not required by the NFILE protocol:  The user side can initiate
  resynchronization only if it needs the data channel, having first
  tried to use a free data channel that does not require
  resynchronization.  Also, the user side can periodically
  resynchronize all unsafe data channels.

  In giving the RESYNCHRONIZE-DATA-CHANNEL command, the user side
  indicates which data channel should be resynchronized.  Data channels
  are unidirectional, which means that depending on the direction
  (either input or output) of the data channel, either the user side or
  the server side sends the resynchronization data.  This is another
  difference from the resynchronization of the control connection, in
  which the resynchronization data is always sent by the user side.
  The resynchronization steps for input data channels are different
  than the steps for output data channels.

Greenberg & Keene [Page 56]

RFC 1037 NFILE - A File Access Protocol December 1987

  INPUT DATA CHANNEL RESYNCHRONIZATION

     1. The user side gives the RESYNCHRONIZE-DATA-CHANNEL command
        on the control connection, with only one argument, the
        handle of the data channel to be resynchronized.

     2. The server side of the data channel generates a unique
        identifier, and sends that data token in its regular
        command response to the user side.

     3. The server side sends a mark over the data channel.

     4. The server side sends the unique identifier token over the
        data channel.

     5. The user side reads until it detects a mark followed by the
        unique identifier token.  The resynchronization is then
        complete.  The data channel is no longer in an unsafe
        state.

  OUTPUT DATA CHANNEL RESYNCHRONIZATION

     1. The user side gives the RESYNCHRONIZE-DATA-CHANNEL command
        on the control connection, with two arguments: the handle
        of the data channel to be resynchronized, and a unique
        identifier that it has just generated.

     2. The user side of the data channel sends a mark.

     3. The user side of the data channel sends a dummy identifier
        token.  The dummy identifier can be any token that the
        server could not interpret as being the unique identifier.
        One suggestion is the data token DUMMY-IDENTIFIER.

     4. The server side of the data channel was alerted by the
        RESYNCHRONIZE-DATA-CHANNEL command that resynchronization
        is in progress.  The server side now reads the data,
        seeking the first mark.

     5. The server side reads and discards the first mark and the
        dummy identifier.

     6. The user side sends a second mark.

     7. The user side sends the unique identifier.

     8. The server side recognizes the mark and the unique
        identifier that follows, and the resynchronization is

Greenberg & Keene [Page 57]

RFC 1037 NFILE - A File Access Protocol December 1987

        complete.  The data channel is no longer in the unsafe
        state.

10. NFILE ERRORS AND NOTIFICATIONS

  NFILE recognizes two types of errors:  command response errors and
  asynchronous errors.  In addition to errors, NFILE supports
  notifications.

  Command response errors:

      - Signify an error that prevented the successful completion of
        the command; when such an error occurs, a command response
        error is sent instead of a normal command response.
      - Occur frequently in normal operations

  Asynchronous errors:

      - Are not related to any specific command
      - Are associated with an erring data channel
      - Typically indicate a problem in the transfer, such as
        running out of disk space or allocation, or an unreadable
        disk record
      - Occur rarely in normal operations

  Notifications:

      - Are not associated with an error
      - Are sent at the server's discretion
      - Provide general information, such as a warning that the
        system is going down

10.1 Notifications From the NFILE Server

  The NFILE server can send asynchronous notifications to the user side
  over the control connection.  The text of the notification contains
  information of interest to the person using NFILE, such as a warning
  that the server's operating system will be going down soon.
  Notifications can come from the server side at any time that the
  server is not sending something else.

  The format of NFILE notifications is:

            (NOTIFICATION "" text)

  The empty string "" takes the place of a transaction identifier.
  Notifications are initiated by the server, and are not associated
  with any transaction originated by the user side.n

Greenberg & Keene [Page 58]

RFC 1037 NFILE - A File Access Protocol December 1987

10.2 NFILE Command Response Errors

  When an error prevents the successful completion of an NFILE command,
  a command response error is sent instead of the normal command
  response.  A normal command response indicates success; a command
  response error indicates failure of the command.

  NFILE command response errors are sent from the server to the user
  across the control connection as top-level token lists, in this
  format:

            (ERROR tid three-letter-code error-vars message)

  ERROR is a keyword.  The tid is the transaction identifier of the
  command that encountered this error.  The arguments three-letter-
  code, error-vars, and message are all required.

  The three-letter-code provides the information on what kind of an
  error was encountered.  For a table of the three-letter codes and
  their meanings:  See the section "NFILE Three-letter Error Codes",
  section 10.4.

  message is a string that is displayed to the human user of the
  protocol.

  error-vars is a keyword/value list.  The three possible keywords are:
  PATHNAME, OPERATION, and NEW-PATHNAME.  Before transmitting an error,
  the server looks at the type of error to see if it can easily
  determine the value of any of the keywords.  If so, the server
  includes the keyword/value pair in its error.  If not, the
  keyword/value pair is omitted.  The value associated with OPERATION
  is the keyword naming the NFILE command that failed.  The values
  associated with PATHNAME and NEW-PATHNAME are strings in the full
  pathname syntax of the server host.

  For example, suppose the server on a file system with hierarchical
  directories could not access a file because its containing directory
  did not exist.  The command error response would use the PATHNAME
  keyword to indicate the first directory level that did not exist,
  instead of the full pathname which was supplied as the command
  argument.  This gives the user side valuable information that it
  otherwise would not have known.

Greenberg & Keene [Page 59]

RFC 1037 NFILE - A File Access Protocol December 1987

10.3 NFILE Asynchronous Errors

  When a data channel process, in either direction, encounters an error
  condition, the server sends an asynchronous error description. An
  asynchronous error description consists of a top-level token list.
  Typically, asynchronous errors indicate error conditions in the
  transfer, such as running out of disk space or allocation, or a
  unreadable disk record.

  The format of asynchronous error descriptions is:

        (ASYNC-ERROR handle three-letter-code error-vars message)

  ASYNC-ERROR is a keyword.  The handle argument identifies the erring
  data channel.  The arguments three-letter-code, error-vars, and
  message are all required.  Their meanings are the same as in NFILE
  command error responses: See the section "NFILE Command Response
  Errors", section 10.2.

  When the server detects an asynchronous error on an input data
  channel, the server sends an asynchronous error description on that
  data channel itself.  When an asynchronous error occurs on an output
  data channel, the asynchronous error description is sent on the
  control connection.

  Some asynchronous errors are restartable.  In this context,
  restartable means it makes sense to try to resume the operation.  One
  example of a restartable error is an attempt to write a file to a
  file system that is out of room.  The server side indicates whether
  an asynchronous error is restartable by prepending the keyword
  RESTARTABLE and the associated value Boolean truth to the error-vars
  list.  To proceed from a restartable error, the user side sends a
  CONTINUE command over the control connection.

  On any asynchronous error, either input or output, the data channel
  on the server side enters an "asynchronous error outstanding" state.
  The server can exit that state in one of two ways:  by receiving a
  CONTINUE command or a CLOSE command with the abort-p argument
  supplied as Boolean truth.

  On a normal CLOSE (not a close-abort), the server side checks the
  channel it was requested to close.  If an asynchronous error
  description has been sent on the data channel, but not yet processed
  by CONTINUE, the server side does not close the channel, but sends a
  command error response.  The same thing happens on a FINISH command
  received on a channel that has an asynchronous error pending.  In
  both cases, the three-letter code included in the command error
  response is EPC, for Error Pending on Channel.

Greenberg & Keene [Page 60]

RFC 1037 NFILE - A File Access Protocol December 1987

10.4 NFILE Three-letter Error Codes

  Usually the server's operating system provides some description of an
  error that occurs.  NFILE has a mechanism for conveying that
  information to the user side.  Upon detecting an error, the NFILE
  server should characterize the error by choosing the three-letter
  code that best describes the error.  The three-letter code is an
  argument in both the command response error and asynchronous error
  messages from the server to the user.

  Each of the NFILE three-letter codes represents some system error.
  The set of codes enables all operating systems to use one error-
  reporting mechanism.  Some operating systems will never encounter
  certain of the error conditions.

  Some errors fit logically into two error codes.  For example, suppose
  the server could not delete a file because the file was not found.
  This error could be considered either CDF (Cannot Delete File) or FNF
  (File Not Found).  In this case, File Not Found gives more specific
  and valuable information than Cannot Delete File.  Since the protocol
  does not allow more than one error code to be reported when an error
  occurs, the server must choose the most appropriate error code, given
  the information available to it from the operating system.

  This is the set of three-letter codes:

    ACC   Access error.  This indicates a protection-violation error.

    ATD   Incorrect access to directory.  A directory could not be
          accessed because the user's access rights to it did not
          permit this type of access.

    ATF   Incorrect access to file.  A file could not be accessed
          because the user's access rights to it did not permit this
          type of access.

    BUG   File system bug.  This includes all protocol violations
          detected by the server, as well as by the host file system.

    CCD   Cannot create directory.  An error occurred in attempting to
          create a directory.

    CDF   Cannot delete file.  The file system reported that it cannot
          delete a file.

    CCL   Cannot create link.  An error occurred in attempting to
          create a link.

Greenberg & Keene [Page 61]

RFC 1037 NFILE - A File Access Protocol December 1987

    CIR   Circular link.  An operation was attempted on a pathname that
          designates a link that eventually links back to itself.

    CRF   Cannot rename file.  An error occurred in attempting to
          rename a file.

    CSP   Cannot set property.  An error occurred in attempting to
          change the properties of a file.  This could mean that you
          tried to set a property that only the file system is allowed
          to set, or a property that is not defined on this type of
          file system.

    DAE   Directory already exists.  A directory could not be created
          because a directory or file of this name already exists.

    DAT   Data error.  The file system contains unreadable data.  This
          could mean data errors detected by hardware or inconsistent
          data inside the file system.

    DEV   Device not found.  The device of the file was not found or
          does not exist.

    DND   "Do Not Delete" flag set.  An attempt was made to delete a
          file that is marked by a "Do Not Delete" flag.

    DNE   Directory not empty.  An invalid deletion of a nonempty
          directory was attempted.

    DNF   Directory not found.  The directory was not found or does not
          exist.  This refers specifically to the containing directory;
          if you are trying to access a directory, and the actual
          directory you are trying to access is not found, FNF (for
          File Not Found) should be indicated instead.

    EPC   Error pending on channel.  The server cannot close the
          channel in attempting to close or finish the channel.

    FAE   File already exists.  The file could not be created because a
          file or directory of this name already exists.

    FNF   File not found.  The file was not found in the containing
          directory.  The TOPS-20 and TENEX "no such file type" and "no
          such file version" errors should also report this condition.

    FOO   File open for output.  Opening a file that was already opened
          for output was attempted.

    FOR   Filepos out of range.  Setting the file pointer past the

Greenberg & Keene [Page 62]

RFC 1037 NFILE - A File Access Protocol December 1987

          end-of-file position or to a negative position was attempted.

    FTB   File too big.  File is larger than the maximum file size
          supported by the file system.

    HNA    Host not available The file server or file system is
          intentionally denying service to user.  This does not mean
          that the network connection failed; it means that the file
          system is explicitly not available.

    IBS    Invalid byte size.  The value of the "byte size" option was
          not valid.

    ICO   Inconsistent options.  Some of the options given in this
          operation are inconsistent with others.

    IOD   Invalid operation for directory.  The specified operation is
          invalid for directories, and the given pathname specifies a
          directory, in directory pathname as file format.

    IOL   Invalid operation for link.  The specified operation is
          invalid for links, and this pathname is the name of a link.

    IP?   Invalid password.  The specified password was invalid.

    IPS   Invalid pathname syntax.  This includes all invalid pathname
          syntax errors.

    IPV   Invalid property value.  The new value provided for the
          property is invalid.

    IWC   Invalid wildcard.  The pathname is not a valid wildcard
          pathname.

    LCK   File locked.  The file is locked.  It cannot be accessed,
          possibly because it is in use by some other process.

    LIP   Login problems.  A problem was encountered while trying to
          log in to the file system.

    MSC   Miscellaneous problems.

    NAV   Not available.  The file or device exists but is not
          available.  Typically, the disk pack is not mounted on a
          drive, the drive is broken, or the like.  Operator
          intervention is probably required to fix the problem, but
          retrying the operation is likely to succeed after the problem
          is solved.

Greenberg & Keene [Page 63]

RFC 1037 NFILE - A File Access Protocol December 1987

    NER   Not enough resources.  For example, a system limit on the
          number of open files or network connections has been reached.

    NET   Network problem.  The file server had some sort of trouble
          trying to create a new data connection, or perform some other
          network operation, and was unable to do so.

    NFS   No file system.  The file system was not available.  For
          example, this host does not have any file systems, or this
          host's file system cannot be initialized or accessed for some
          reason, or the file system simply does not exist.

    NLI   Not logged in.  A file operation was attempted before logging
          in.  Normally the file system interface always logs in before
          doing any operation, but this problem can occur in certain
          unusual cases in which logging in has been aborted.

    NMR   No more room.  The file system is out of room.  This can mean
          any of several things:

                     - The entire file system is full.
                     - The particular volume involved is full.
                     - The particular directory involved is full.
                     - The user's allocated quota has been exceeded.

    RAD   Rename across directories.  The devices or directories of the
          initial and target pathnames are not the same, but on this
          file system they are required to be.

    REF   Rename to existing file.  The target name of a rename
          operation is the name of a file that already exists.

    UKC   Unknown operation. An unsupported file system operation was
          attempted, or an unsupported command was attempted.

    UKP   Unknown property.  The property is unknown.

    UNK   Unknown user.  The specified user name is unknown to this
          host.

    UUO   Unimplemented option.  An option to a command is not
          implemented.

    WKF   Wrong kind of file.  This includes errors in which an invalid
          operation for a file, directory, or link was attempted.

    WNA   Wildcard not allowed.

Greenberg & Keene [Page 64]

RFC 1037 NFILE - A File Access Protocol December 1987

11. TOKEN LIST TRANSPORT LAYER

  PURPOSE:  The Token List Transport Layer is a protocol that
  facilitates the transmission of simple structured data, such as
  lists.

11.1 Introduction to the Token List Transport Layer

  The Token List Transport Layer is a general-purpose protocol.  The
  Token List Transport Layer sends "tokens" through its underlying
  stream.  Each token usually represents a simple quantity, such as a
  string or integer.

  Tokens can be organized into "token lists".  Special tokens are
  provided to denote the starting and ending point of lists.  The token
  list transport layer differentiates between "top-level token lists",
  which are not contained in other lists, and "embedded token lists",
  which are contained in other lists.  Using lists makes it convenient
  to send structured records, such as commands and command responses of
  the client protocol.  The top-level token lists provide robustness.

  The Token List Transport Layer is a general term that includes two
  separate but related subjects:  the "token list stream" and the
  "token list data stream".  The token list stream is commonly used for
  applications that can easily organize the information to be
  transmitted into tokens and lists.  The token list data stream is
  more appropriate for transmitting a large volume of data that cannot
  easily be structured into tokens and lists, such as file data, which
  is simply a sequence of characters or bytes.

  The following table illustrates the main differences between token
  list streams and token list data streams:

                    Token List Data Stream      Token List Stream
                    ----------------------      -----------------

    Built on:     token list stream           Byte Stream with Mark

    Transmits:    stream data                 tokens, token lists

    Example
    of use:       NFILE data channels         NFILE control
                                              connection

Greenberg & Keene [Page 65]

RFC 1037 NFILE - A File Access Protocol December 1987

  NFILE uses the the Token List Transport Layer, and provides an
  excellent example of its usefulness.  The NFILE commands and command
  responses are sent over the control connection in a token list
  stream.  File data is sent across each data channel in a token list
  data stream.

11.2 Token List Stream

11.2.1 Types of Tokens and Token Lists

  All numbers in the token list documentation are represented in
  decimal notation.  Bytes are 8 bits long.

  TYPES OF TOKENS

  Tokens are of the following types:

           1. Atomic tokens.

              Atomic tokens are of the following subtypes:

             - Data tokens.  A data token consists of a sequence of
               bytes with an effectively infinite maximum length.  In
               some contexts a data token represents a string; in
               other contexts, a data token is other arbitrary data.

               Each data token is preceded in the token list stream
               by a representation of its length in bytes.

               Data tokens that are under 200 bytes long are preceded
               by one byte containing their length in bytes.  That
               is, a data token of 34 bytes is preceded by one byte
               of value 34.

               Data tokens 200 bytes or over are preceded by the byte
               known as PUNCTUATION-LONG, of value 201.  After the
               201 comes a four-byte-long number (least significant
               byte first) containing the length of the data token
               that follows.

             - Numeric tokens.  A sequence of bytes that represent
               and encode a nonnegative binary integer.  The largest
               valid integer is 2^63 - 1.

               Numeric tokens are either short integers (less than
               256) or long integers (greater than or equal to 256).
               Short integers are preceded by the byte known as
               PUNCTUATION-SHORT-INTEGER, of value 206.

Greenberg & Keene [Page 66]

RFC 1037 NFILE - A File Access Protocol December 1987

               Long integers are begun by PUNCTUATION-LONG-INTEGER,
               of value 207.  One byte follows, containing the length
               (in bytes) of the long integer.  The integer itself is
               next, least significant byte first.

             - Keyword tokens.  A sequence of bytes that represent
               and encode a named identifier of the implemented
               protocol.  Keyword tokens are used by the client
               protocol to convey a name; the only significance of a
               keyword token is in its name.

               Each keyword is preceded by the byte known as
               PUNCTUATION-KEYWORD, of value 208.  The data token
               following PUNCTUATION-KEYWORD represents the name of
               the keyword as a string.  The characters are in
               upper-case standard ASCII.

             - Boolean truth.  A special token that represents the
               Boolean truth value.  This token is known as
               BOOLEAN-TRUTH, of value 209 <4>.

  2. Control tokens.

  The token list stream supports four control tokens to delimit token
  lists, and one padding token.

              TOP-LEVEL-LIST-BEGIN  202   This control token
                                          appears at the start of
                                          each top-level token list.

              TOP-LEVEL-LIST-END    203   This control token
                                          appears at the end of
                                          each top-level token list.
              LIST-BEGIN            204   This control token
                                          appears at the start of
                                          each embedded token list.

              LIST-END              205   This control token
                                          appears at the end of
                                          each embedded token list.

              PUNCTUATION-PAD       200   This padding token should
                                          be ignored by the token
                                          list stream.  It can be
                                          sent to fill buffers.

Greenberg & Keene [Page 67]

RFC 1037 NFILE - A File Access Protocol December 1987

  TOKEN LISTS

  A token list consists of a sequence of atomic tokens or token lists.
  Token lists are begun and ended by control tokens that delimit the
  token lists.  There are three types of token lists:

        1. Top-level token lists.

           Top-level token lists begin with TOP-LEVEL-LIST-BEGIN and
           end with TOP-LEVEL-LIST-END.  Top-level token lists are not
           contained in other lists.

        2. Embedded token lists.

           These token lists occur inside other token lists.  They
           begin with LIST-BEGIN and end with LIST-END.

        3. The empty token list.

           This is a special example of the embedded token list.  In
           some contexts, the empty token list represents Boolean
           falsity.  An embedded empty token list is composed of a
           LIST-BEGIN followed immediately by a LIST-END.  A top-level
           empty token list is composed of TOP-LEVEL-LIST-BEGIN
           followed immediately by TOP-LEVEL-LIST-END.

11.2.2 Token List Stream Example

  This section contains an example of some data that can appear on a
  token list stream.  The example is a top-level token list encoding an
  NFILE DELETE command.

  The DELETE command is composed of the following pieces:  a TOP-
  LEVEL-LIST-BEGIN, the keyword DELETE, a data token containing the
  transaction identifier, a LIST-BEGIN, a LIST-END, a data token
  containing a pathname of a file to be deleted, and a TOP-LEVEL-LIST-
  END.  This example uses t105 as the transaction identifier, and
  /usr/max/temp as the pathname.

  All numbers in this section are expressed in decimal notation.

  The pieces of the command are displayed here in order:

           1. TOP-LEVEL-LIST-BEGIN
           2. The keyword token whose name is DELETE
           3. The data token containing the characters:  t105
           4. LIST-BEGIN
           5. LIST-END

Greenberg & Keene [Page 68]

RFC 1037 NFILE - A File Access Protocol December 1987

           6. The data token containing the characters:  /usr/max/temp
           7. TOP-LEVEL-LIST-END

  Now, let's translate each piece of the command into the bytes that
  are transmitted through the token list stream.

       1. TOP-LEVEL-LIST-BEGIN

          202     represents TOP-LEVEL-LIST-BEGIN

       2. The keyword token whose name is DELETE.

          A keyword token is introduced by PUNCTUATION-KEYWORD, which
          is represented in the token list stream as the byte 208.

          A data token follows, containing the string "DELETE".  A
          data token under 200 bytes long is introduced by one byte
          containing its length in bytes.  The length of this data
          token is 6 bytes.

          The data token continues with the standard ASCII character
          set representation of each character in the string DELETE:

              208     represents PUNCTUATION-KEYWORD
              006     represents the length of this data token
              068     represents "D"
              069     represents "E"
              076     represents "L"
              069     represents "E"
              084     represents "T"
              069     represents "E"

       3. The data token containing the characters:  t105

          This data token is begun by its length in bytes (4), and
          continues with the NFILE character set representation of
          each character in the string:

              004     represents the length of this data token
              116     represents "t"
              049     represents "1"
              048     represents "0"
              053     represents "5"

       4. LIST-BEGIN

              204     represents LIST-BEGIN

Greenberg & Keene [Page 69]

RFC 1037 NFILE - A File Access Protocol December 1987

       5. LIST-END

              205     represents LIST-END

       6. The data token containing the characters:  /usr/max/temp

              013     represents length of this data token
              047     represents "/"
              117     represents "u"
              115     represents "s"
              114     represents "r"
              047     represents "/"
              109     represents "m"
              097     represents "a"
              120     represents "x"
              047     represents "/"
              116     represents "t"
              101     represents "e"
              109     represents "m"
              112     represents "p"

       7. TOP-LEVEL-LIST-END

              203     represents TOP-LEVEL-LIST-END

11.2.3 Mapping of Lisp Objects to Token List Stream Representation

  The Symbolics interface to the token list stream sends Lisp objects
  through the underlying Byte Stream with Mark and produces Lisp
  objects on the other end.  Not all Lisp objects can be sent in this
  way.  For example, compound objects other than lists are not handled.
  An appropriate analogy is the sending and reconstruction of list
  structure via printed representation.  These are the types of objects
  that can be sent, and their representations:

       - Lisp strings are represented as data tokens in the NFILE
         character set.  Only 8-bit strings can be sent <5>.

       - Keyword symbols are represented as keyword tokens.  Although
         identifiable and reconstructable as keyword symbols, only
         their names are sent.  Any properties, bindings, and the
         like are not sent.

       - T is represented as BOOLEAN-TRUTH.

       - NIL is represented as the empty token list.

       - Lists are represented as token lists.  Circular lists cannot

Greenberg & Keene [Page 70]

RFC 1037 NFILE - A File Access Protocol December 1987

         be sent.  See the footnote related to the ambiguity between

         NIL and the empty list:  See the section "Types of Tokens
         and Token Lists", section 11.2.1.

       - Integers are represented as numeric tokens.  Only
         nonnegative integers less than 2^63 can be sent.

11.2.4 Aborting and the Token List Stream

  A token list stream accrues the benefits of the abort management
  policy of the Byte Stream with Mark on which it is built.  In order
  to fully realize this benefit, some simple rules must be obeyed by
  any implementation of the token list stream.

  The term "transmission" means either an atomic token or a complete
  top-level token list. A transmission starts with the control token
  TOP-LEVEL-BEGIN and ends with TOP-LEVEL-END.  The top-level token
  list can contain embedded token lists.

  The interface that writes to the token list stream must be capable of
  writing the representation of entire transmissions.  When this
  interface is called, it must effectively lock the token list stream,
  and exclude access by other processes until the entire transmission
  has been encoded and sent.

  If the sending is aborted while the stream is locked, the stream
  enters an "unsafe" state.  Trying to send data while the stream is
  unsafe signals an error.  The application and the token list stream
  must send a mark to cause resynchronization, and allow the token list
  stream to be used again.  When the reading side encounters this mark,
  it resynchronizes itself according to whatever client protocol is in
  use.

  Similarly, the interface that reads from the token list stream must
  be capable of reading entire transmissions.  When this interface is
  called, it must lock the stream, excluding access by other processes
  until the entire transmission has been read.

  If the reading is aborted while the stream is locked, the stream
  enters an unsafe state.  The only exit from this unsafe state is by
  means of receiving a mark.  When the stream is unsafe, the only valid
  operation that can be performed upon it is "read and discard all
  tokens until a mark is encountered; read and discard that mark;
  declare the stream safe again".

Greenberg & Keene [Page 71]

RFC 1037 NFILE - A File Access Protocol December 1987

  Depending on the client protocol, the receipt of a mark might cause
  the reading side to read for further marks.  NFILE implements the
  resynchronization of token list streams, and serves as a useful
  example: See the section "NFILE Control Connection
  Resynchronization", section 9.1.

  The Symbolics implementation provides the two mark-handling
  primitives in this way:

     1. Send token (or list) preceded by a mark.  When the stream
        is in the unsafe state (on the output side), this is the
        only permitted output operation (other than closing).

     2. Read through to a mark and read the token (or list)
        following the mark.  When the stream is in the unsafe state
        (on the input side), this is the only permitted input
        operation (other than closing).

11.3 Token List Data Stream

  The token list data stream is a facility to transmit stream data
  through a token list stream.  The token list data stream imposes the
  following protocol on the data transmitted:

           - Data is sent in the format of loose data tokens, not
             contained in token lists.

           - The keyword token EOF indicates that the end of data has
             been reached.

           - Token lists can be transmitted through the token list
             data stream.

           - No loose tokens other than data tokens or the keyword
             token EOF can be sent.

           - Boundaries between data tokens are not signification.
             The data is considered to be a continuous stream, with
             the possible exception of marks.

  The token list data stream is most appropriate for sending file data.
  It is expected (but not required) that its typical mode of use is to
  send a large number of data tokens, with an occasional token list.
  The design intent was that token lists would be used by the
  application program to indicate exceptional situations.

  Data tokens, the keyword token EOF, and token lists are defined in

Greenberg & Keene [Page 72]

RFC 1037 NFILE - A File Access Protocol December 1987

  the token list stream documentation:  See the section "Types of
  Tokens and Token Lists", section 11.2.1.

  The NFILE file protocol provides a good example of the use of token
  list data streams.  NFILE sends file data through token list data
  streams; each NFILE data channel is a token list data stream.  Errors
  such as disk errors during the reading of a file are conveyed as
  token lists through the token list data stream.

12. BYTE STREAM WITH MARK

  PURPOSE:  Byte Stream with Mark is a simple layer of protocol that
  guarantees that an out-of-band signal can be transmitted in the case
  of program interruption.  Byte Stream with Mark is designed to
  provide end-to-end stream consistency in the face of user program
  aborts.

12.1 Discussion of Byte Stream with Mark

  INTRODUCTION

  Byte Stream with Mark is a reliable, bidirectional byte stream with
  one out-of-band (but not out-of-sequence) signal called a "mark".
  The design of Byte Stream with Mark ensures that the mark is always
  recognizable on the receiving end.  The Byte Stream with Mark is
  built on an underlying stream, which must support the transmission of
  8-bit bytes.  Byte Stream with Mark has been implemented to run on
  TCP and Chaos.  Marks are implemented differently on the two
  protocols.

  Marks are used to resynchronize the stream when something has
  occurred to interrupt normal operations.  For example, an application
  layer sending data over the Byte Stream with Mark can abort in the
  middle of sending that data.  Recovery is handled by sending a mark.

  In the context of this document, "aborting" is defined as follows:
  Aborting the current execution of a program means to halt that
  execution and to abandon it, never to complete it.  The data
  representing the state of the execution are irrevocably discarded.

  EXAMPLE OF USE

  Byte Stream with Mark is the layer of protocol underlying NFILE.
  NFILE uses the marks implemented in Byte Stream with Mark to
  resynchronize control connections or data channels whose
  synchronization has been lost.  For a description of NFILE's use of
  marks to resynchronize streams:  See the section "NFILE
  Resynchronization Procedure", section 9.

Greenberg & Keene [Page 73]

RFC 1037 NFILE - A File Access Protocol December 1987

  BYTE STREAM WITH MARK ON CHAOSNET

  A mark is recognized on Chaosnet by a packet bearing the opcode 201
  (octal).  There is no data in a mark packet, so the data portion of
  the packet is ignored.  Byte Stream with Mark transmits all data in
  packets bearing opcode 200 (octal).

  If Byte Stream with Mark is implemented on another (non-Chaos) stream
  that supports opcode-bearing packets, the recommended implementation
  is the reservation of an opcode for the mark.

  BYTE STREAM WITH MARK ON TCP:  RECORD MODE

  The purpose of Byte Stream with Mark is to guarantee that marks can
  always be unambiguously identified.  Therefore, for TCP (and for any
  transport layer that does not implement packets natively) a simple
  record stream is imposed on the stream.  The record boundaries serve
  only to distinguish where a mark can occur.  A record consists of a
  two-byte byte count, most significant byte first, followed by that
  many bytes of data.  A byte count of zero is recognized as a mark.

  Both the sending side and the receiving side must rigorously maintain
  the integrity of the record boundaries.  A writer to the stream must
  never output a byte count without that number of data bytes
  following.  Similarly, a reader of the stream, after reading a byte
  count, has effectively contracted to read that many bytes from the
  encapsulated stream, regardless of whether those bytes are requested
  by the application layer.

  MAINTAINING RECORD INTEGRITY

  This subsection deals with maintaining record integrity on non-Chaos
  networks.  Since Chaos implements packets natively, no special care
  is required to maintain record integrity on the Chaos network.

  The design discussed here guarantees record integrity; the underlying
  stream must guarantee data integrity.

  The basic design of Byte Stream with Mark on TCP (and other transport
  layers that do not implement packets natively) is to preserve record
  integrity by putting clearly demarcated, byte-counted records in the
  natural records of the encapsulated stream.  Therefore, when the
  outer stream requests a buffer's worth of file data from the
  encapsulated stream, it expects to receive a buffer containing one
  entire, ntegral, record of that stream, complete with byte count.

  Because of diverse network implementations on different operating
  systems, the software that implements the encapsulated stream might

Greenberg & Keene [Page 74]

RFC 1037 NFILE - A File Access Protocol December 1987

  not be able to provide integral record buffers to the Byte Stream
  with Mark implementation.  For example, the writing stream could have
  written records that are much longer than available buffers on the
  receiving system.  In this case, a request to read from the
  encapsulated stream returns some buffer or some amount of data
  representing less than an entire Byte Stream with Mark record.  The
  input subroutine of the Byte Stream with Mark implementation must
  therefore return a region of this (smaller) buffer, representing less
  than the full Byte Stream with Mark record.  Nevertheless, the Byte
  Stream with Mark must extract the count of the full Byte Stream with
  Mark record from the first such buffer of each Byte Stream with Mark
  record, and maintain and update this count as succeeding component
  buffers are read.

  In this case, if the program reading from the Byte Stream with Mark
  aborts while reading data, the implementation of Byte Stream with
  Mark must continue to read through the remaining buffers of the Byte
  Stream with Mark record that has been subdivided in this fashion.

  The user side program will have determined that an abort has
  occurred, and will request the Byte Stream with Mark to read up to
  and through the next mark.  The Byte Stream with Mark will have
  processed a fractional record, and must discard the remaining buffers
  of the record now being read.

12.2 Byte Stream with Mark Abortable States

  Byte Stream with Mark is designed to provide end-to-end stream
  consistency in the face of user program aborts.  This section
  describes user program aborts, and how Byte Stream with Mark handles
  them.  In the context of this document, "aborting" is defined as
  follows:  Aborting the current execution of a program means to halt
  that execution and to abandon it, never to complete it.  The data
  representing the state of the execution are irrevocably discarded.

  USER PROGRAM ABORTS AND I/O STREAMS

  Aborting the execution of the code that manipulates I/O streams, in
  general, poses significant problems.  Given that a stream is a static
  data object, and is intended to be used over and over again, aborting
  the execution of any routine manipulating a stream can leave it in an
  inconsistent, unusable state.

  Many operating systems solve this problem by manipulating a large
  subset of streams within the confines of the supervisor or executive
  program, which is not vulnerable to aborts, short of system or
  network failure.  Nevertheless, the need still exists to implement
  streams outside of the boundaries of the supervisor.  Furthermore,

Greenberg & Keene [Page 75]

RFC 1037 NFILE - A File Access Protocol December 1987

  the Symbolics computer environment has no supervisor or executive
  program, and is thus vulnerable to aborts everywhere.

  BYTE STREAM WITH MARK HANDLING OF USER PROGRAM ABORTS

  Byte Stream with Mark is designed to be nearly impervious to the
  aborting of programs using it.  Its design is based on careful
  analysis of all possible states of the stream, and of the effect of
  aborts of the programs using the stream in each of these states.
  This section provides that analysis.

  A "transmission" is a collection of user data sent by the application
  level through the Byte Stream with Mark whose end is well-defined,
  once its start has been recognized.  For instance, the token list
  stream, when using Byte Stream with Mark, sends token lists.  When a
  TOP-LEVEL-LIST-BEGIN has been sent, the containing transmission is
  not considered complete until the corresponding TOP-LEVEL-LIST-END is
  read.  See the section "Token List Transport Layer", section 11.

  The following cases are possible states of the stream when an abort
  occurs:

        1. Abort occurs when the user program is not manipulating the
           stream.

           This case presents no problem.

        2. Abort occurs after a transmission has been partially sent,
           at a packet or record boundary.

           This implies that the datum that would indicate the
           successful complete sending of that transmission has been
           not yet been sent.

           The Byte Stream with Mark state is consistent, but the
           application level state is not.  The application level must
           determine that the execution of the code composing and
           sending its transmission was, in fact, aborted, and
           initiate resynchronization via marks.

           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.

Greenberg & Keene [Page 76]

RFC 1037 NFILE - A File Access Protocol December 1987

        3. Abort occurs during the sending or receiving of a record.

           This is the most vulnerable state of the mechanism.  This
           case does not occur on packet-oriented media; it is
           subsumed by the next case.

           This case is handled by minimizing the extent of this
           window, and killing the connection when and if the
           situation is detected.  Depending on the operating system
           involved, this window could be minimized by using
           interrupt-disabling mechanisms, auxiliary processes or
           tasks, or some other technique.

           For buffered streams, input and output waiting can be done
           in consistent states, thus minimizing the amount of time
           manipulating the actual encapsulated stream.  For
           unbuffered streams, a lot of time can be spent in this
           window.  It is expected that unbuffered streams will be
           exceedingly uncommon.  Nevertheless, the implementation of
           Byte Stream with Mark must detect this case.

        4. Abort occurs during the sending or receiving of fundamental
           units of the lowest-level underlying stream (packets,
           buffers, or bytes).

           This case is usually handled by inhibiting interrupts, or
           other forms of masking, in the code implementing the
           encapsulated stream, since no waiting is possible at
           unexpected times.

13. POSSIBLE FUTURE EXTENSIONS

  NFILE was designed to be extended as the needs of its clients grow,
  or as new clients with different needs appear.  Currently it meets
  the needs of the Symbolics Genera 7.0 operating system, although its
  design is intentionally general.  If users of other operating systems
  identify new features that would be useful, they could be added to
  NFILE.  This section illustrates some areas areas where the design of
  NFILE intentionally accommodates extensions.

        - The NFILE protocol encodes commands and responses as text,
          rather than using prearranged numbers.  This means that new
          commands and responses can be added without having to obtain
          a new number from a central registry.

        - The Token List Transport Layer provides a general substrate
          for the value-transmission portion of network protocols.  In
          fact, it has been used at Symbolics for other protocols

Greenberg & Keene [Page 77]

RFC 1037 NFILE - A File Access Protocol December 1987

          besides NFILE.  The Token List Transport Layer could
          conveniently be extended to support transmission of other
          types of values besides those it currently supports.

        - The character set to be used for file transfer could be made
          negotiable.

        - The command character set could be made negotiable.
          Currently there is no negotiation sequence, but one could be
          added.

        - Greater support for more complex file organizations could be
          added, such as record files, databases, and so on.  This
          could be an extension to the direct access mode facility.

        - Currently, the LOGIN command allows the user side to inform
          the server which version of NFILE it is running.  This
          feature is included in NFILE so that a server can continue
          to support older versions of the protocol even after new,
          extended versions have been implemented.  However, the
          specification is currently somewhat vague as to how the
          server can make use of the version.

        - NFILE is not restricted to using TCP or Chaos as its
          underlying protocol.  NFILE can be built on any byte stream
          protocol that supports reliable transmission of 8-bit bytes
          and multiple connections.

  In addition to the possible future extensions, we would like to
  mention a known limitation of NFILE.

  Currently NFILE requires multiple connections for a single session.
  That is, the control connection must be separate from the data
  connections.  If NFILE is to be used over a telephone, this
  requirement poses an inconvenient restriction.  It is possible to
  implement a multiplexing scheme as a level between NFILE and the
  communication medium.

Greenberg & Keene [Page 78]

RFC 1037 NFILE - A File Access Protocol December 1987

                               APPENDIX A
                         NORMAL TRANSLATION MODE

  NORMAL translation mode guarantees the following:

        - A file containing characters in the NFILE character set can
          be written to any NFILE server and read back intact
          (containing the same characters).

        - A file written by NFILE should not appear as "foreign" to a
          server operating system unless the file contains NFILE's
          extended characters.  That is, a server file that uses only
          the subset of the NFILE character set limited to standard
          ASCII characters (the 95 printing characters, and the native
          representation of return, linefeed, page, backspace, rubout,
          and tab) can be read and written, with the result being the
          same data in NFILE characters as exists in server
          characters.

  In this section, all numbers designating values of character codes
  are to be interpreted in octal.  The notation "x in c1..c2" means
  "for all character codes x such that c1 <= x <= c2."

  The NFILE character set is an extension of standard ASCII.  The 95
  ASCII printing characters have the same numerical codes in the NFILE
  character set.  Five ASCII non-printing characters have counterparts
  in the NFILE character set, as shown in the following table.  The
  NFILE character set includes a single Return character, rather than
  the carriage-return line-feed sequence typically used in ASCII.  The
  NFILE character set does not include the ASCII control characters,
  other than the five shown in the following table, but does include
  some additional printing and formatting characters that have no
  counterparts in ASCII.

                            NFILE     Standard ASCII

        Rubout:             207       177
        Backspace:          210       10
        Tab:                211       11
        Linefeed:           212       12
        Page:               214       14

  Note that the NFILE Return character is of code 215.  This character
  includes "going to the next line".  This is a notable difference from
  the convention used in PDP-10 ASCII in which lines are ended by a
  pair of characters, "carriage return" and "line feed".

Greenberg & Keene [Page 79]

RFC 1037 NFILE - A File Access Protocol December 1987

  NORMAL TRANSLATION TO UNIX SERVERS

  The translation given in this table is appropriate for use by UNIX
  servers, or other servers that use 8-bit bytes to store ASCII
  characters.  Machines with 8-bit bytes usually place the extra NFILE
  characters in the top half of their character set.

      TABLE 1.   TRANSLATIONS FROM NFILE CHARACTERS TO UNIX CHARACTERS

           NFILE character       UNIX character

           x in 000..007         x
           x in 010..015         x + 200
           x in 016..176         x
           177                   377
           x in 200..207         x
           x in 210..211         x - 200
           212                   015
           x in 213..214         x - 200
           215                   012
           x in 216..376         x
           377                   177

      TABLE 2.   TRANSLATIONS FROM UNIX CHARACTERS TO NFILE CHARACTERS

           UNIX character        NFILE character

           x in 000..007         x
           x in 010..011         x + 200
           012                   215
           x in 013..014         x + 200
           015                   212
           x in 016..176         x
           177                   377
           x in 200..207         x
           x in 210..215         x - 200
           x in 216..376         x
           377                   177

  NORMAL TRANSLATION TO PDP-10 FAMILY SERVERS

  The translation given in this table is appropriate for use by PDP-10
  family servers, or other servers that use 7-bit bytes to store ASCII
  characters.  On the PDP-10 the sequence CRLF, 015 012, represents a
  new line.

Greenberg & Keene [Page 80]

RFC 1037 NFILE - A File Access Protocol December 1987

  The mechanism for this translation on machines with 7-bit bytes is to
  use the RUBOUT character (octal code 177) as an escape character.

        TABLE 3.   TRANSLATIONS FROM NFILE TO PDP-10 CHARACTERS

           NFILE character       PDP-10 character(s)

           x in 000..007         x
           x in 010..012         177 x
           013                   013
           x in 014..015         177 x
           x in 016..176         x
           177                   177 177
           x in 200..207         177 x - 200
           x in 210..212         x - 200
           213                   177 013
           214                   014
           215                   015 012
           x in 216..376         177 x - 200
           377                   no corresponding code

  These tables might seem confusing at first, but there are some
  general rules about it that should make it clearer.  First, NFILE
  characters in the range 000..177 are generally represented as
  themselves, and x in 200..377 is generally represented as 177
  followed by x - 200.  That is, 177 is used to quote the second 200
  NFILE characters.  It was deemed that 177 is a more useful and common
  character than 377, so 177 177 means 177, and there is no way to
  describe 377 with PDP-10 ASCII characters.  In the NFILE character
  set, the formatting control characters appear offset up by 200 with
  respect to standard ASCII.  This explains why the preferred mode of
  expressing 210 (backspace) is 010, and 010 turns into 177 010.  The
  same reasoning applies to 211 (Tab), 212 (Linefeed), 214 (Formfeed),
  and 215 (Return).

  More special care is needed for the Return character, which is the
  mapping of the system-dependent representation of "the start of a new
  line".  The NFILE Return (215) is equivalent to 015 012 (CRLF) in
  some ASCII systems.  In the NFILE character set there is no
  representation

Greenberg & Keene [Page 81]

RFC 1037 NFILE - A File Access Protocol December 1987

    TABLE 4.   TRANSLATIONS FROM PDP-10 CHARACTERS TO NFILE CHARACTERS

           PDP-10 character      NFILE character

           x in 000..007         x
           x in 010..012         x + 200
           013                   013
           014                   214
           015 012               215
           015 not-012           115
           x in 016..176         x
           177 x in 000..007     x + 200
           177 x in 010..012     x
           177 013               213
           177 x in 014..015     x
           177 x in 016..176     x + 200
           177 177               177

  of a carriage that doesn't go to a new line, so if there is one in a
  server file, it must be translated to something else.  When
  converting ASCII characters to NFILE characters, an 015 followed by
  an 012 therefore turns into a 215.  A stray CR is arbitrarily
  translated into a single M (115).

Greenberg & Keene [Page 82]

RFC 1037 NFILE - A File Access Protocol December 1987

                               APPENDIX B
                          RAW TRANSLATION MODE

  RAW mode means no translation should be performed.  In RAW mode the
  server operating system should treat the file as a character file and
  use the same data formatting that would be appropriate for a
  character file, but transfer the actual binary values of the
  character codes.

Greenberg & Keene [Page 83]

RFC 1037 NFILE - A File Access Protocol December 1987

                               APPENDIX C
                      SUPER-IMAGE TRANSLATION MODE

  SUPER-IMAGE mode is intended for use by PDP-10 family machines only.
  It is included largely as an illustration of a system-dependent
  extension.  A server machine that has 8-bit bytes should treat
  SUPER-IMAGE mode the same as NORMAL mode.

  In this section, all numbers designating values of character codes
  are to be interpreted in octal.  The notation "x in c1..c2" means
  "for all character codes x such that c1 <= x <= c2."

  SUPER-IMAGE mode suppresses the use of the 177 character as an escape
  character.  Character translation should be done as in NORMAL mode,
  with one exception.  When a two-character sequence beginning with 177
  is detected, the 177 should not be output at all.

  In this section, all numbers designating values of character codes
  are to be interpreted in octal.  SUPER-IMAGE mode is intended for use
  by PDP-10 machines only.

  SUPER-IMAGE suppresses the use of Rubout for quoting.  That is, for
  each entry beginning with a 177 in the PDP-10 character column in the
  NORMAL translation table, the NFILE character has the 177 removed.

        TABLE 5.   SUPER-IMAGE TRANSLATION FROM NFILE TO ASCII

           NFILE character   PDP-10 character(s)

           x in 000..177     x
           x in 200..214     <x - 200>
           215               015 012
           x in 216..376     <x - 200>
           377               no corresponding code

Greenberg & Keene [Page 84]

RFC 1037 NFILE - A File Access Protocol December 1987

        TABLE 6.   SUPER-IMAGE TRANSLATION FROM ASCII TO NFILE

           PDP-10 character  NFILE character

           x in 000..007     x
           x in 010..012     x + 200
           013               013
           014               214
           015 012           215
           015 not-012       115
           x in <016..176>   x
           177               177

Greenberg & Keene [Page 85]

RFC 1037 NFILE - A File Access Protocol December 1987

                                  NOTES

  1. NFILE's requirement for using the NFILE character set is
     recognized as a drawback for non-Symbolics machines.  A useful
     extension to NFILE would be a provision to make the character set
     negotiable.

  2. Implementation note:  Care must be taken that the freeing is done
     before the control connection is allowed to process another
     command, or else the control connection may find the data channel
     to be falsely indicated as being in use.

  3. The Symbolics operating system has the policy that whenever the
     user side is waiting for the server side, a user abort can occur.
     This user side waiting can occur in any context, such awaiting a
     response, waiting in the middle of reading network input, or
     waiting in the middle of transmitting network output.  Thus there
     are no "hung" states.

  4. Note that the Token List Transport Layer supplies a special token
     to indicate Boolean truth, but no corresponding token to indicate
     Boolean falsity.  NFILE uses an empty token list to indicate
     Boolean falsity.  The historical reason for this asymmetry is the
     inability of the Lisp language to differentiate between the empty
     list and NIL, which is traditionally used to mean Boolean falsity.
     If the flexibility of both a Boolean falsity and an empty token
     list were allowed, it would create problems for an operating
     system that cannot distinguish between the two.  This aspect of
     the protocol is recognized as a concession to the Lisp language.
     The unfortunate effect is to disallow operating systems to
     distinguish between Boolean falsity and an empty list.

  5. No so-called "fat strings" can be sent.

Greenberg & Keene [Page 86]