Difference between revisions of "RFC1037"

Latest revision as of 11:55, 29 November 2020

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

   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

   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

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

        - 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.

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.

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.

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.

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.

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.

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.

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.

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".

CONVENTIONS USED IN THIS DOCUMENT

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.

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:

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)

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).

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.

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".

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>

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.

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

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.

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.

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.

CHANGE-PROPERTIES Command

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

Response: (CHANGE-PROPERTIES tid)

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.

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.

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.

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

                   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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

         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.

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.

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

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

8.15 FILEPOS Command

Command: (FILEPOS tid handle position resync-uid)

Response: (FILEPOS tid)

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

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

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

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

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

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

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

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

8.15.1 Implementation Hint for FILEPOS Command

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

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

8.16 FINISH Command

Command: (FINISH tid handle)

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

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

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

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

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

ERRORS ON FINISH

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

8.17 HOME-DIRECTORY Command

Command: (HOME-DIRECTORY tid user)

Response: (HOME-DIRECTORY tid directory-pathname)

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

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

8.18 LOGIN Command

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

Response: (LOGIN tid keyword/value-pairs)

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

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

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

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

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

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

LOGIN RETURN VALUES: keyword/value-pairs

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

NAME

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

PERSONAL-NAME

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

HOMEDIR-PATHNAME

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

GROUP-AFFILIATION

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

SERVER-VERSION

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

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

PROPERTY-INDEX-TABLE

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

8.19 MULTIPLE-FILE-PLISTS Command

Command: (MULTIPLE-FILE-PLISTS tid input-handle paths

          characters properties)

Response: (MULTIPLE-FILE-PLISTS tid)

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

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

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

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

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

For example, the user supplied a pathlist argument resembling:

                        [file1 file2 file3]

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

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

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

8.20 OPEN Command

Command: (OPEN tid handle pathname direction binary-p

            TEMPORARY RAW SUPER-IMAGE DELETED PRESERVE-DATES
            SUBMIT DIRECT-FILE-ID ESTIMATED-LENGTH BYTE-SIZE
            IF-EXISTS IF-DOES-NOT-EXIST)

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

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

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

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

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

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

THE pathname OPEN ARGUMENT

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

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

THE handle OPEN ARGUMENT

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

THE direction OPEN ARGUMENT

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

INPUT

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

OUTPUT

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

IO

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

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

PROBE

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

PROBE-LINK

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

PROBE-DIRECTORY

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

THE binary-p OPEN ARGUMENT

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

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

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

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

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

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

8.20.1 NFILE OPEN Optional Keyword/Value Pairs

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

The following options are used often:

BYTE-SIZE

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

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

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

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

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

           Byte Size                Packing Scheme

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

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

DELETED

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

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

DIRECT-FILE-ID

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

PRESERVE-DATES

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

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

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

ESTIMATED-LENGTH

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

IF-EXISTS

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

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

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

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

  Here are the possible values and their meanings:

  ERROR

     Reports an error.

  NEW-VERSION

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

  RENAME

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

  RENAME-AND-DELETE

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

  OVERWRITE

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

  TRUNCATE

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

  APPEND

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

  SUPERSEDE

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

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

IF-DOES-NOT-EXIST

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

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

  ERROR

     Reports an error.

  CREATE

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

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

RAW

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

SUPER-IMAGE

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

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

TEMPORARY

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

SUBMIT

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

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

8.20.2 NFILE OPEN Response Return Values

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

Response Format:

  (OPEN tid truename binary-p other-properties)

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

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

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

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

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

AUTHOR

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

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

BYTE-SIZE

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

CREATION-DATE

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

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

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

FILEPOS

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

LENGTH

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

8.21 PROPERTIES Command

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

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

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

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

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

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

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

PROPERTIES COMMAND RESPONSE

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

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

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

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

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

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

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

8.22 READ Command

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

Response: (READ tid)

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

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

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

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

8.23 RENAME Command

Command: (RENAME tid handle pathname to-pathname)

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

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

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

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

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

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

8.24 RESYNCHRONIZE-DATA-CHANNEL Command

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

For an Input Handle:

Command: (RESYNCHRONIZE-DATA-CHANNEL tid handle)

Response: (RESYNCHRONIZE-DATA-CHANNEL tid identifier)

For an Output Handle:

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

Response: (RESYNCHRONIZE-DATA-CHANNEL tid)

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

All arguments to RESYNCHRONIZE-DATA-CHANNEL are required.

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

8.24.1 Implementation Hints for RESYNCHRONIZE-DATA-CHANNEL Command

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

RESYNCHRONIZING AN OUTPUT DATA CHANNEL

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

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

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

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

RESYNCHRONIZING AN INPUT DATA CHANNEL

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

8.25 UNDATA-CONNECTION Command

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

Response: (UNDATA-CONNECTION tid)

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

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

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

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

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

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>.

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.

    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.

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:

   - 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.

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

     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

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.

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.

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.

 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

       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.

 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.

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

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.

            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.

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

        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

    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

      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".

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

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.

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

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,

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.

     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

       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.

                            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".

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.

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

 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).

                            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.

                            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

     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

                               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.

Anonymous

Search

Difference between revisions of "RFC1037"

Namespaces

More

Page actions

Latest revision as of 11:55, 29 November 2020

Contents

INTRODUCTION

NFILE PROTOCOL LAYERING

OVERVIEW OF AN NFILE SESSION

NFILE CONTROL AND DATA CONNECTIONS

NFILE FILE OPENING MODES

NFILE CHARACTER SET

CONVENTIONS USED IN THIS DOCUMENT

Mapping Data Types Into Token List Representation

Format of NFILE Commands and Responses

Data Channel Handles and Direct File Identifiers

Syntax of File and Directory Pathname Arguments

Format of NFILE File Property/Value Pairs

NFILE COMMANDS

ABORT Command

CHANGE-PROPERTIES Command

CLOSE Command

COMPLETE Command

CONTINUE Command

CREATE-DIRECTORY Command

CREATE-LINK Command

DATA-CONNECTION Command

DELETE Command

NFILE RESYNCHRONIZATION PROCEDURE

NFILE Control Connection Resynchronization

NFILE Data Connection Resynchronization

Navigation

Navigation

Wiki tools

Wiki tools

@@ Line 1: / Line 1: @@
 Network Working Group                                      B. Greenberg
 Request for Comments:  1037                                    S. Keene
-                                                          December 1987
+                                                      December 1987
-                    NFILE -  A File Access Protocol
+                NFILE -  A File Access Protocol
 STATUS OF THIS MEMO
-  This document includes a specification of the NFILE file access
+This document includes a specification of the NFILE file access
-  protocol and its underlying levels of protocol, the Token List
+protocol and its underlying levels of protocol, the Token List
-  Transport Layer and Byte Stream with Mark.  The goal of this
+Transport Layer and Byte Stream with Mark.  The goal of this
-  specification is to promote discussion of the ideas described here,
+specification is to promote discussion of the ideas described here,
-  and to encourage designers of future file protocols to take advantage
+and to encourage designers of future file protocols to take advantage
-  of these ideas.  A secondary goal is to make the specification
+of these ideas.  A secondary goal is to make the specification
-  available to sites that might benefit from implementing NFILE.  The
+available to sites that might benefit from implementing NFILE.  The
-  distribution of this document is unlimited.
+distribution of this document is unlimited.
-                            TABLE OF CONTENTS
-                                                                    Page
-.  INTRODUCTION                                                    3
-.  NFILE PROTOCOL LAYERING                                        4
-.  OVERVIEW OF AN NFILE SESSION                                    5
-.  NFILE CONTROL AND DATA CONNECTIONS                              6
-.  NFILE FILE OPENING MODES                                        7
-.  NFILE CHARACTER SET                                            9
-.  CONVENTIONS USED IN THIS DOCUMENT                              10
-.1  Mapping Data Types Into Token List Representation        10
-.2  Format of NFILE Commands and Responses                    10
-.3  Data Channel Handles and Direct File Identifiers          13
-.4  Syntax of File and Directory Pathname Arguments          13
-.5  Format of NFILE File Property/Value Pairs                14
-.  NFILE COMMANDS                                                16
-.1  ABORT Command                                            16
-.2  CHANGE-PROPERTIES Command                                16
-.3  CLOSE Command                                            17
-.4  COMPLETE Command                                          19
-.5  CONTINUE Command                                          20
-Greenberg & Keene                                              [Page 1]
-RFC 1037            NFILE - A File Access Protocol        December 1987
-.6  CREATE-DIRECTORY Command                                  21
-.7  CREATE-LINK Command                                      21
-.8  DATA-CONNECTION Command                                  22
-.9  DELETE Command                                            23
-.10  DIRECT-OUTPUT Command                                    23
-.11  DIRECTORY Command                                        24
-.11.1  NFILE DIRECTORY Data Format                      26
-.12  DISABLE-CAPABILITIES Command                            27
-.13  ENABLE-CAPABILITIES Command                              28
-.14  EXPUNGE Command                                          28
-.15  FILEPOS Command                                          29
-.15.1  Implementation Hint for FILEPOS Command          30
-.16  FINISH Command                                          30
-.17  HOME-DIRECTORY Command                                  31
-.18  LOGIN Command                                            32
-.19  MULTIPLE-FILE-PLISTS Command                            34
-.20  OPEN Command                                            35
-.20.1  NFILE OPEN Optional Keyword/Value Pairs          39
-.20.2  NFILE OPEN Response Return Values                45
-.21  PROPERTIES Command                                      47
-.22  READ Command                                            49
-.23  RENAME Command                                          50
-.24  RESYNCHRONIZE-DATA-CHANNEL Command                      51
-.24.1  Implementation Hints for RESYNCHRONIZE-DATA-      51
-                    CHANNEL Command
-.25  UNDATA-CONNECTION Command                                52
-.  NFILE RESYNCHRONIZATION PROCEDURE                              53
-.1  NFILE Control Connection Resynchronization                54
-.2  NFILE Data Connection Resynchronization                  55
-.  NFILE ERRORS AND NOTIFICATIONS                                58
-.1  Notifications From the NFILE Server                      58
-.2  NFILE Command Response Errors                            59
-.3  NFILE Asynchronous Errors                                60
-.4  NFILE Three-letter Error Codes                          61
-.  TOKEN LIST TRANSPORT LAYER                                    65
-.1  Introduction to the Token List Transport Layer          65
-.2  Token List Stream                                        66
-.2.1  Types of Tokens and Token Lists                  66
-.2.2  Token List Stream Example                        68
-.2.3  Mapping of Lisp Objects to Token List Stream      70
-                    Representation
-.2.4  Aborting and the Token List Stream                71
-Greenberg & Keene                                              [Page 2]
-RFC 1037            NFILE - A File Access Protocol        December 1987
-.3  Token List Data Stream                                  72
-.  BYTE STREAM WITH MARK                                        73
-.1  Discussion of Byte Stream with Mark                      73
-.2  Byte Stream with Mark Abortable States                  75
-.  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
-.  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]
+                          TABLE OF CONTENTS
+                                                                Page
+.  INTRODUCTION                                                    3
-RFC 1037            NFILE - A File Access Protocol        December 1987
+.  NFILE PROTOCOL LAYERING                                        4
+.  OVERVIEW OF AN NFILE SESSION                                    5
-            - Creating links
+.  NFILE CONTROL AND DATA CONNECTIONS                              6
-            - 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.
+.  NFILE FILE OPENING MODES                                        7
-  The NFILE server provides information about any errors that occur in
+.  NFILE CHARACTER SET                                            9
-  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.
+.  CONVENTIONS USED IN THIS DOCUMENT                              10
-  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.
-.  NFILE PROTOCOL LAYERING
+.1  Mapping Data Types Into Token List Representation        10
+.2  Format of NFILE Commands and Responses                    10
+.3  Data Channel Handles and Direct File Identifiers          13
+.4  Syntax of File and Directory Pathname Arguments          13
+.5  Format of NFILE File Property/Value Pairs                14
-  NFILE is a layered file protocol.  The layers are:
+.  NFILE COMMANDS                                                16
-            +-----------------------------------------------+
+.1  ABORT Command                                            16
-            |client program or user interface              |
+.2  CHANGE-PROPERTIES Command                                16
-            +-----------------------------------------------+
+.3  CLOSE Command                                            17
-            |NFILE                                         |
+.4  COMPLETE Command                                         19
-            +-----------------------------------------------+
+.5  CONTINUE Command                                          20
-            |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
+.6  CREATE-DIRECTORY Command                                  21
-  out-of-band signal can be transmitted in the case of program
+.7  CREATE-LINK Command                                      21
-  interruption.  Byte Stream with Mark is to be layered upon extant
+.8  DATA-CONNECTION Command                                  22
-  byte stream protocols.  An important goal of the NFILE design was
+.9  DELETE Command                                            23
-  that NFILE could be built on any byte stream.  It is currently
+.10  DIRECT-OUTPUT Command                                    23
-  implemented on TCP and Chaosnet.  See the section "Byte Stream with
+.11  DIRECTORY Command                                        24
-  Mark", section 12.
+.11.1  NFILE DIRECTORY Data Format                      26
+.12  DISABLE-CAPABILITIES Command                            27
+.13  ENABLE-CAPABILITIES Command                              28
+.14  EXPUNGE Command                                          28
+.15  FILEPOS Command                                          29
+.15.1  Implementation Hint for FILEPOS Command          30
+.16  FINISH Command                                          30
+.17  HOME-DIRECTORY Command                                  31
+.18  LOGIN Command                                            32
+.19  MULTIPLE-FILE-PLISTS Command                            34
+.20  OPEN Command                                            35
+.20.1  NFILE OPEN Optional Keyword/Value Pairs          39
+.20.2  NFILE OPEN Response Return Values                45
+.21  PROPERTIES Command                                      47
+.22  READ Command                                            49
+.23  RENAME Command                                          50
+.24  RESYNCHRONIZE-DATA-CHANNEL Command                      51
+.24.1  Implementation Hints for RESYNCHRONIZE-DATA-      51
+                CHANNEL Command
+.25  UNDATA-CONNECTION Command                                52
-  The Token List Transport Layer is a protocol that facilitates the
+.  NFILE RESYNCHRONIZATION PROCEDURE                              53
-  transmission of simple structured data, such as lists.  See the
-  section "Token List Transport Layer", section 11.
+.1  NFILE Control Connection Resynchronization                54
+.2  NFILE Data Connection Resynchronization                  55
+.  NFILE ERRORS AND NOTIFICATIONS                                58
+.1  Notifications From the NFILE Server                      58
+.2  NFILE Command Response Errors                            59
+.3  NFILE Asynchronous Errors                                60
+.4  NFILE Three-letter Error Codes                          61
-Greenberg & Keene                                              [Page 4]
+.  TOKEN LIST TRANSPORT LAYER                                    65
-RFC 1037            NFILE - A File Access Protocol        December 1987
+.1  Introduction to the Token List Transport Layer          65
+.2  Token List Stream                                        66
+.2.1  Types of Tokens and Token Lists                  66
+.2.2  Token List Stream Example                        68
+.2.3  Mapping of Lisp Objects to Token List Stream      70
+                Representation
+.2.4  Aborting and the Token List Stream                71
+.3  Token List Data Stream                                  72
-  The NFILE commands and command responses are transmitted in "token
+.  BYTE STREAM WITH MARK                                        73
-  lists".  See the section "NFILE Commands", section 8.
-  This specification does not include a client program or user
+.1  Discussion of Byte Stream with Mark                      73
-  interface to the protocol.  In the Symbolics implementation, the
+.2  Byte Stream with Mark Abortable States                  75
-  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.
-.  OVERVIEW OF AN NFILE SESSION
+.  POSSIBLE FUTURE EXTENSIONS                                    77
-  An NFILE session is a dialogue between two hosts.  The host that
+APPENDIX A.  NORMAL TRANSLATION MODE                              79
-  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
+APPENDIX B.  RAW TRANSLATION MODE                                  83
-  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
+APPENDIX C.  SUPER-IMAGE TRANSLATION MODE                          84
-  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
+NOTES                                                              86
-  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.
+                          LIST OF TABLES
-  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.
+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
+== INTRODUCTION ==
-Greenberg & Keene                                              [Page 5]
+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".
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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:
-.  NFILE CONTROL AND DATA CONNECTIONS
+        - Reading and writing entire files
+        - Reading and writing selected portions of files
+        - Deleting and renaming files
-  The user and server communicate through a single control connection
+        - Creating links
-  and a set of data connections.  Data connections are established and
+        - Listing, creating, and expunging directories
-  disestablished by NFILE commands.  The user side sends NFILE commands
+        - Listing and changing the properties of files
-  to the server over the control connection.  The server responds to
+        - Enabling and disabling access capabilities on a remote
-  every user command over this control connection.  The actual file
+          host
-  data is transmitted over the data connections.
-  User aborts can disrupt the normal flow of data on the control
+NFILE supports file transfer of binary or character files.
-  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
+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.
-  An NFILE session is begun when the NFILE user program connects to a
+This specification defines NFILE user version 2 and server version 2.
-  remote host and establishes a network connection.  This initial
+We do not envision NFILE as an unchanging protocol, but rather as a
-  connection is the control conection of the dialogue.  If TCP is used
+protocol that could continue to develop if additional requirements
-  as the underlying protocol, contact NFILE's well-known port, 59.  If
+are identified though the process of this Request for Comments.  The
-  Chaos is used, use the contact name "NFILE".
+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.
-  The control connection is the vehicle used by the user to send its
+== NFILE PROTOCOL LAYERING ==
-  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.
+NFILE is a layered file protocol.  The layers are:
-        - 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
+          |client program or user interface              |
-  token lists".  The control connection expects never to receive "loose
+          +-----------------------------------------------+
-  tokens"; that is, tokens not contained in token lists.
+          |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.
+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.
+== 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".
-Greenberg & Keene                                              [Page 6]
+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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+== 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.
-  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.
-  Data connections are established and discarded at user request, by
+THE CONTROL CONNECTION
-  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
+An NFILE session is begun when the NFILE user program connects to a
-  channel is capable of sending data in one direction.  The term "input
+remote host and establishes a network connection.  This initial
-  channel" refers to the data channel that transmits data from the
+connection is the control conection of the dialogue.  If TCP is used
-  server to the user side; "output channel" refers to the data channel
+as the underlying protocol, contact NFILE's well-known port, 59.  If
-  that transmits data from the user to the server side.  Throughout the
+Chaos is used, use the contact name "NFILE".
-  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
+The control connection is the vehicle used by the user to send its
-  a "token list data stream".  See the section "Token List Data
+commands, and the server to send its command responses.  These types
-  Stream", section 11.3. When the end of data is reached, the keyword
+of communication occur over the NFILE control connection:
-  token EOF is sent.  Occasionally, token lists are transmitted over
-  the data channels, such as asynchronous error descriptions.
-.  NFILE FILE OPENING MODES
+      - 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.
-  The NFILE OPEN command opens a file for reading, writing, or "direct
+All commands, command responses, and other data flowing over the
-  access" at the server host.  That means, in general, asking the host
+NFILE control connection are transmitted in the format of "top-level
-  file system to access the file and obtaining a file number, pointer,
+token lists".  The control connection expects never to receive "loose
-  or other quantity for subsequent rapid access to the file; this is
+tokens"; that is, tokens not contained in token lists.
-  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"
+DATA CONNECTIONS
-  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 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.
-  Data stream mode of file transfer is the default mode of NFILE's OPEN
+Each data connection is composed of two "data channels".  Each data
-  command.  Data stream mode is appropriate when the entire file is
+channel is capable of sending data in one direction.  The term "input
-  transferred, either from user to server, or from server to user.
+channel" refers to the data channel that transmits data from the
-  Data stream mode is used more often than direct access mode.
+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.
+== 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.
-Greenberg & Keene                                              [Page 7]
+DATA STREAM MODE:
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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.
+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 OPEN command includes a "handle" argument, which identifies the
+The sending side transmits the entire contents of the specified file
-  data channel to be used to transfer the data.  The handle is used in
+over the specified data channel as rapidly as the network permits.
-  subsequent commands to reference this particular opening.  When a
+When the sending side reaches the end of the file, it transmits a
-  data stream opening is requested with the OPEN command, the file is
+special control token to signal end of file.  The receiving side
-  opened and the data begins to flow immediately.
+expects an uninterrupted stream of bytes to appear immediately on its
+side of the data channel.
-  The sending side transmits the entire contents of the specified file
+The user gives the CLOSE command to terminate a data stream transfer.
-  over the specified data channel as rapidly as the network permits.
+CLOSE results in closing the file.
-  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.
+DIRECT ACCESS MODE:
-  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.
-  Direct access mode enables reading or writing data from a given
+When a file is opened in direct access mode, the flow of data does
-  starting point in a file through a specified number of bytes.  In
+not start immediately.  Rather, the user gives either a READ command
-  direct access mode, data is requested and sent in individual
+(to request data to flow from server to user) or a DIRECT-OUTPUT
-  transactions.  To request a direct access mode opening, the OPEN
+command (to request data to flow from user to server).  When reading,
-  command is used with a DIRECT-FILE-ID argument.  (In data stream
+the READ command allows the user to specify the starting point and
-  mode, no DIRECT-FILE-ID is supplied.)  The direct file identifier is
+the number of bytes of data to transfer.  When writing, the FILEPOS
-  used in subsequent commands to reference the direct access opening.
+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.
-  When a file is opened in direct access mode, the flow of data does
+The user side terminates the direct access transfer by using the
-  not start immediately.  Rather, the user gives either a READ command
+CLOSE command.  The ABORT command can be given to terminate without
-  (to request data to flow from server to user) or a DIRECT-OUTPUT
+transmitting all of the specified bytes.
-  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
+== NFILE CHARACTER SET ==
-  CLOSE command.  The ABORT command can be given to terminate without
-  transmitting all of the specified bytes.
+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".
+== CONVENTIONS USED IN THIS DOCUMENT ==
+=== 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
+ ----------------------------------------------------------------
-Greenberg & Keene                                              [Page 8]
+ Keyword            A keyword token
-RFC 1037            NFILE - A File Access Protocol        December 1987
+ Keyword list        A token list of keyword tokens
+ Integer            A numeric data token
-.  NFILE CHARACTER SET
+  String              A data token containing the characters of the
+                    string in the NFILE character set.
-  The NFILE character set <1> is an extension of standard ASCII.  NFILE
+ Boolean Truth      The token known as BOOLEAN-TRUTH.
-  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
+  Boolean False      The empty token list.
-  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
+ Date                A numeric data token.  The date is expressed in
-  NORMAL mode ensures that a file containing characters in the NFILE
+                    Universal Time format, which measures a time as
-  character set can be written to a remote host and read back intact.
+                    the number of seconds since January 1, 1900, at
-  OPEN has optional keyword arguments to specify RAW or SUPER-IMAGE.
+                    midnight GMT.
-  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:
+ 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.
-        See the section "NORMAL Translation Mode", Appendix A.  See the
+ Time interval      A numeric data token.  The time interval is
-        section "RAW Translation Mode", Appendix B.  See the section
+                    expressed in seconds.  A time interval
-        "SUPER-IMAGE Translation Mode", Appendix C.
+                    indicating "never" is represented by the empty
+                    token list.
-  The use of the NFILE character set brings up a difficulty involved
+=== Format of NFILE Commands and Responses ===
-  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".
+Each command description begins by giving the command format and
+response format.  Here is the beginning of the DATA-CONNECTION
+command description:
+Command:  (DATA-CONNECTION tid new-input-handle new-output-handle)
+Response: (DATA-CONNECTION tid connection-identifier)
+The command descriptions follow these conventions:
+. NFILE commands and responses are transmitted as top-level token
+    lists.
-Greenberg & Keene                                              [Page 9]
+    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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+. 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.
-.  CONVENTIONS USED IN THIS DOCUMENT
+. A unique transaction identifier (tid) identifies each command.
-.1  Mapping Data Types Into Token List Representation
+    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.
-  Throughout this NFILE specification, the data types of arguments,
+OPTIONAL 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
+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:
-    Keyword            A keyword token
+      (DELETE tid handle pathname)
-    Keyword list        A token list of keyword tokens
+ If you supply a handle and no pathname, the command format is:
-    Integer            A numeric data token
+      (DELETE tid handle)
-    String              A data token containing the characters of the
+ If you supply a pathname and no handle, the command format is:
-                        string in the NFILE character set.
-    Boolean Truth       The token known as BOOLEAN-TRUTH.
+       (DELETE tid empty-token-list pathname)
-    Boolean False      The empty token list.
+The empty token list in the token list stream appears as a LIST-BEGIN
+followed immediately by a LIST-END.
-    Date                A numeric data token.  The date is expressed in
+OPTIONAL KEYWORD/VALUE PAIRS
-                        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,
+Four NFILE commands have "optional keyword/value pairs".  These
-                        representing "never".  "Never" is used for
+commands are: COMPLETE, LOGIN, OPEN, and READ.  Optional
-                        values such as the time a directory was last
+keyword/value pairs can be either included in the command or omitted
-                        expunged, if it has never been expunged.
+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.
-    Time interval      A numeric data token.  The time interval is
+If included, optional keyword/value pairs are a sequence of
-                        expressed in seconds.  A time interval
+alternating keywords and values.  The values associated with the
-                        indicating "never" is represented by the empty
+keywords can be keywords, lists, strings, Booleans, integers, dates,
-                        token list.
+date-or-never's, and time intervals.  The text of each command
+description states what type of value is appropriate for each
+optional keyword.
-.2  Format of NFILE Commands and Responses
+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:
-  Each command description begins by giving the command format and
+Command Format:
-  response format.  Here is the beginning of the DATA-CONNECTION
-  command description:
+      (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:
-Greenberg & Keene                                              [Page 10]
+      (LOGIN x105 tjones let-me-in USER-VERSION 2)
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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).
+=== Data Channel Handles and Direct File Identifiers ===
-  Command:  (DATA-CONNECTION tid new-input-handle new-output-handle)
+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:
-  Response: (DATA-CONNECTION tid connection-identifier)
+Data Stream
-  The command descriptions follow these conventions:
+The handle must identify a data channel that is bound to an opening.
-. NFILE commands and responses are transmitted as top-level token
+Direct Access
-      lists.
-      Top-level token lists are enclosed in parentheses in these
+In general, the handle must be a direct file identifier.  A direct
-      command descriptions.  These parentheses are not sent literally
+file identifier specifies a direct access opening.  It is the same as
-      across the control or data connections, but are a shorthand
+the value supplied in the DIRECT-FILE-ID keyword/value pair in the
-      representation of special control tokens that delimit top-level
+OPEN command.  It is used for all operations that identify an opening
-      token lists.  Specifically, TOP-LEVEL-LIST-BEGIN starts a top-
+rather than a data channel.
-      level token list; TOP-LEVEL-LIST-END ends a top-level token list.
-. NFILE command names are keywords.
+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.
-      The command name is required in every command and command
+=== Syntax of File and Directory Pathname Arguments ===
-      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.
-. A unique transaction identifier (tid) identifies each command.
+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".
-      The transaction identifier is a string made up by the user side
+Here are some examples of file pathnames, for different server hosts:
-      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
+Server Host    Example of File Pathname
-  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
+   UNIX            /usr/max/life.c
-  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)
+  TOPS-20        ps:<max>life.bin.17
+  VMS            MACD:[MAX]LIFE.FOR;3
+  Symbolics LMFS  >max>life.lisp.newest
-Greenberg & Keene                                              [Page 11]
+------------------------------------------------------------
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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:
-     If you supply a handle and no pathname, the command format is:
+Server Host     Example of Directory Pathname
-        (DELETE tid handle)
+------------------------------------------------------------
-    If you supply a pathname and no handle, the command format is:
+  UNIX            /usr/max/
-        (DELETE tid empty-token-list pathname)
+  TOPS-20        <max>
-   The empty token list in the token list stream appears as a LIST-BEGIN
+   VMS            MACD:[MAX]
-  followed immediately by a LIST-END.
-   OPTIONAL KEYWORD/VALUE PAIRS
+   Symbolics LMFS  >max>hacks>
-  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
+=== Format of NFILE File Property/Value Pairs ===
-  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,
+Several NFILE commands request information regarding the properties
-  in uppercase letters.  For example, here is the format of the LOGIN
+of files or directories.  These commands include:  DIRECTORY,
-  command:
+MULTIPLE-FILE-PLISTS, PROPERTIES, and CHANGE-PROPERTIES.  This
+section describes how file property information is conveyed over the
+token list stream.
-  Command Format:
+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.
-        (LOGIN tid user password FILE-SYSTEM USER-VERSION)
+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.
-  FILE-SYSTEM and USER-VERSION are two optional keywords associated
+In command arguments, file properties cannot be specified with
-  with the LOGIN command.  The user side can supply USER-VERSION, and
+integers; keywords must be used to specify file properties in command
-  omit FILE-SYSTEM as shown in this example:
+arguments.  Integers can be used to denote file properties only in
+command responses.
-        (LOGIN x105 tjones let-me-in USER-VERSION 2)
+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:
-  As seen above, the optional keyword/value pair USER-VERSION, if
+ Data type      Keywords denoting file properties
-  supplied in a command, consists of the keyword USER-VERSION followed
-  by the value to be used for that keyword (in this example, 2).
+----------------------------------------------------------------
+ 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
-Greenberg & Keene                                              [Page 12]
+ Boolean values  DELETED, DONT-DELETE, DONT-DUMP, DONT-REAP,
+                SUPERSEDE-PROTECT, NOT-BACKED-UP, OFFLINE,
+                TEMPORARY, CHARACTERS, DIRECTORY
-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.
-.3  Data Channel Handles and Direct File Identifiers
+== NFILE COMMANDS ==
-  Several NFILE commands require an argument that specifies an opening.
+It is important to understand the conventions used in each of the
-  This kind of argument is called a handle in the command description.
+following command descriptions.  See the section "Conventions Used in
-  It is always a string type argument.  A handle can be either a data
+This Document", section 7.
-  channel handle or a direct file identifier, depending on the mode of
-  the opening:
+=== ABORT Command ===
-  Data Stream
+Command:  (ABORT tid input-handle)
-  The handle must identify a data channel that is bound to an opening.
+Response: (ABORT tid)
-  Direct Access
+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.
-  In general, the handle must be a direct file identifier.  A direct
+Upon receiving the ABORT command, the server checks to see if a
-  file identifier specifies a direct access opening.  It is the same as
+transfer is still active on that channel.  If so, the server
-  the value supplied in the DIRECT-FILE-ID keyword/value pair in the
+terminates the transfer by telling the data connection logical
-  OPEN command.  It is used for all operations that identify an opening
+process to stop transferring bytes of data.  The user side needs to
-  rather than a data channel.
+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.
-  Two NFILE commands applicable to direct access openings are
+Whether or not a transfer is active on that channel, the user side
-  exceptions to the general rule.  The handle supplied in ABORT and
+puts the data channel into the unsafe state.  Before the data channel
-  CONTINUE cannot be a direct file identifier, but must be a data
+can be used again, it must be resynchronized.
-  channel handle instead.
-.4  Syntax of File and Directory Pathname Arguments
+=== CHANGE-PROPERTIES Command ===
-  Some arguments and return values in the NFILE command descriptions
+Command:  (CHANGE-PROPERTIES tid handle pathname property-pairs)
-  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".
+Response: (CHANGE-PROPERTIES tid)
+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.
+=== 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.
+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.
-Greenberg & Keene                                              [Page 13]
+AN UNSUCCESSFUL CLOSE OPERATION
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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
+.
+A SUCCESSFUL CLOSE OPERATION
-  Here are some examples of file pathnames, for different server hosts:
+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.
-  Server Host    Example of File Pathname
+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.
-  ------------------------------------------------------------
+=== COMPLETE Command ===
-      UNIX            /usr/max/life.c
+Command:  (COMPLETE tid string pathname DIRECTION NEW-OK DELETED)
-      TOPS-20        ps:<max>life.bin.17
+Response: (COMPLETE tid new-string success)
-      VMS            MACD:[MAX]LIFE.FOR;3
+COMPLETE performs file pathname completion.
-      Symbolics LMFS  >max>life.lisp.newest
+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.
-  The CREATE-DIRECTORY and HOME-DIRECTORY commands take a directory as
+DELETED is a Boolean type argument; if followed by Boolean truth, the
-  an argument.  In NFILE commands, a directory is represented by a
+server is instructed to look for files that have been deleted but not
-  string that names the directory.  In most cases this string is in the
+yet expunged, as well as non-deleted files.  The default is to ignore
-  syntax native to the server host.  However in some cases the native
+soft-deleted files.
-  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
+DIRECTION can be followed by READ, to indicate that the file is to be
-  hosts:
+read.  If the file is to be written, DIRECTION can be followed by
+WRITE.  The default is READ.
-  Server Host    Example of Directory Pathname
+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
-      UNIX            /usr/max/
+----------------------------------------------------------------
-      TOPS-20        <max>
+OLD                Success:  the string completed to the name of
+                    a file that exists.
-      VMS            MACD:[MAX]
+NEW                Success:  the string completed to the name of
+                    a file that could be created.
-      Symbolics LMFS  >max>hacks>
+Empty token list    Failure due to one of these reasons:
-  ------------------------------------------------------------
+                    The file is on a file system that does not
-.5  Format of NFILE File Property/Value Pairs
+                    support completion.  new-string is supplied as
+                    the unchanged string.
-  Several NFILE commands request information regarding the properties
+                    There is no possible completion.  new-string
-  of files or directories.  These commands include:  DIRECTORY,
+                    is supplied as the unchanged string.
-  MULTIPLE-FILE-PLISTS, PROPERTIES, and CHANGE-PROPERTIES.  This
-  section describes how file property information is conveyed over the
-  token list stream.
+                    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.
-Greenberg & Keene                                              [Page 14]
+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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+=== CONTINUE Command ===
+Command:  (CONTINUE tid handle)
-  File property information is usually sent in property/value pairs,
+Response: (CONTINUE tid)
-  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
+CONTINUE resumes a data transfer that was temporarily suspended due
-  mix both ways of specifying properties (keyword or integer) within a
+to an asynchronous error.  Each asynchronous error description has an
-  single description.  An integer is interpreted as an index into the
+optional argument of RESTARTABLE, indicating whether it makes any
-  Property Index Table, an array of property keywords.  The server can
+sense to try to continue after this particular error occurred.
-  optionally send a Property Index Table to the user during the
+CONTINUE tries to resume the data transfer if the error is
-  execution of the LOGIN command, although it is not required.  This
+potentially recoverable, according to the RESTARTABLE argument in the
-  greatly reduces the length of transmissions.
+asynchronous error description.  For a discussion of asynchronous
+errors:  See the section "NFILE Errors and Notifications", section
+.
-  In command arguments, file properties cannot be specified with
+handle is a required string-type argument that refers to the handle
-  integers; keywords must be used to specify file properties in command
+of the data channel that received an asynchronous error.  That data
-  arguments.  Integers can be used to denote file properties only in
+channel could have been in use for a data stream or direct access
-  command responses.
+transfer.  handle cannot be a direct file identifier.
-  We now list the keywords associated with file properties.  This list
+If the asynchronous error description does not contain the
-  is not intended to be restrictive.  If a programmer implementing
+RESTARTABLE argument, and the user issues the CONTINUE command
-  NFILE needs a new keyword, a new keyword (not on this list) can be
+anyway, the server gives a command error response.
-  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
+=== CREATE-DIRECTORY Command ===
-  ----------------------------------------------------------------
+Command:  (CREATE-DIRECTORY tid pathname property-pairs)
-    Integers        BLOCK-SIZE, BYTE-SIZE, GENERATION-RETENTION-COUNT,
+Response: (CREATE-DIRECTORY tid dir-truename)
-                    LENGTH-IN-BLOCKS, LENGTH-IN-BYTES,
-                    DEFAULT-GENERATION-RETENTION-COUNT
-    Dates          CREATION-DATE, MODIFICATION-DATE
+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.
-    Date-or-never's REFERENCE-DATE, INCREMENTAL-DUMP-DATE,
+property-pairs is a keyword/value list of properties that further
-                    COMPLETE-DUMP-DATE, DATE-LAST-EXPUNGED,
+define the attributes of the directory to be created.  The allowable
-                    EXPIRATION-DATE
+keywords and associated values are operating system dependent;
+typically they indicate arguments to be given to the native primitive
+for creating directories.
-    Time intervals  AUTO-EXPUNGE-INTERVAL
+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
+.5.
-    Keyword Lists  SETTABLE-PROPERTIES, LINK-TRANSPARENCIES,
+=== CREATE-LINK Command ===
-                    DEFAULT-LINK-TRANSPARENCIES
-    Boolean values  DELETED, DONT-DELETE, DONT-DUMP, DONT-REAP,
+Command:  (CREATE-LINK tid pathname target-pathname properties)
-                    SUPERSEDE-PROTECT, NOT-BACKED-UP, OFFLINE,
-                    TEMPORARY, CHARACTERS, DIRECTORY
+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.
-Greenberg & Keene                                              [Page 15]
+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
-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.
-    Strings        ACCOUNT, AUTHOR, LINK-TO, PHYSICAL-VOLUME,
+=== DATA-CONNECTION Command ===
-                    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
+Command:  (DATA-CONNECTION tid new-input-handle new-output-handle)
-  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.
-.  NFILE COMMANDS
+Response: (DATA-CONNECTION tid connection-identifier)
-  It is important to understand the conventions used in each of the
+DATA-CONNECTION enablesthe user side to initiate the establishment of
-  following command descriptions.  See the section "Conventions Used in
+a new data connection.  The user side supplies two required string
-  This Document", section 7.
+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.
-.1  ABORT Command
+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.
-  Command:  (ABORT tid input-handle)
+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.
-  Response: (ABORT tid)
+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.
-  ABORT cleanly interrupts and prematurely terminates a single direct
+For background information:  See the section "NFILE Control and Data
-  access mode data transfer initiated with READ.  The required input-
+Connections", section 4.
-  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
+=== DELETE Command ===
-  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
+Command:  (DELETE tid handle pathname)
-  puts the data channel into the unsafe state.  Before the data channel
-  can be used again, it must be resynchronized.
-.2  CHANGE-PROPERTIES Command
+Response: (DELETE tid)
-  Command:  (CHANGE-PROPERTIES tid handle pathname property-pairs)
+DELETE deletes a file on the remote file system.
-  Response: (CHANGE-PROPERTIES tid)
+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
-Greenberg & Keene                                              [Page 16]
+open file bound to the data channel specified by handle at close
+time.  This is true in both the output and input cases.
-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.
-.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
-.
-  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
-.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.
-.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
-.
-  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
-.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
-.5.
-.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  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.
-.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.
 .10  DIRECT-OUTPUT Command
-  Command:  (DIRECT-OUTPUT tid direct-handle output-handle)
+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
+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.
-  direct-handle is a required argument, and output-handle is optional.
+direct-handle is a required argument, and output-handle is optional.
-  If supplied, output-handle is a request to bind an output data
+If supplied, output-handle is a request to bind an output data
-  channel (indicated by output-handle) to the direct access opening
+channel (indicated by output-handle) to the direct access opening
-  designated by the direct-handle.  The specified output data channel
+designated by the direct-handle.  The specified output data channel
-  must be free.  The server binds the data channel and begins accepting
+must be free.  The server binds the data channel and begins accepting
-  data from that connection and writing it to the opening.
+data from that connection and writing it to the opening.
-  If the output-handle is omitted, this is a request to unbind the
+If the output-handle is omitted, this is a request to unbind the
-  channel and terminate the active output transfer.
+channel and terminate the active output transfer.
 .11  DIRECTORY Command
-  Command:  (DIRECTORY tid input-handle pathname control-keywords
+Command:  (DIRECTORY tid input-handle pathname control-keywords
-              properties)
+          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
+Response: (DIRECTORY tid)
-  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:
+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.
-  DELETED
+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.
-  Includes soft-deleted files in the directory list.  Without this
+The pathname generally contains wildcard characters, in operating-
-  option, they must not be included. Such files have the DELETED
+system-specific format, describing potential file name matches.  Most
-  property indicated as true" among their properties.  DELETED is
+operating systems provide a facility that accepts such a pathname and
-  ignored on systems that do not support soft deletion.
+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.
-  DIRECTORIES-ONLY
+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.
-  This option changes the semantics of DIRECTORY fairly drastically.
+control-keywords ARGUMENT TO DIRECTORY
-  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
+control-keywords is a token list of keywords.  The control-keywords
-  directories, not whose pathnames match the supplied pathname, but
+affect the way the DIRECTORY command works on the server machine.
-  whose pathnames expressed as directory pathnames match the
+Although some of the options below request the server to limit (by
-  (potentially wildcarded) directory portion of the supplied pathname.
+some filter) the data to be returned, it is never an error if the
-  The description of the PROBE-DIRECTORY keyword that can be supplied
+server returns more information than is requested.
-  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
+The following keywords are recognized:
-  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
+DELETED
-  properties at all for the files concerned; that is, only the
-  truenames are returned.
+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.
+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.
-Greenberg & Keene                                              [Page 25]
+SORTED
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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).
-  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).
 .11.1  NFILE DIRECTORY Data Format
-  If the NFILE DIRECTORY command completes successfully, a single token
+If the NFILE DIRECTORY command completes successfully, a single token
-  list containing the requested directory information is sent on the
+list containing the requested directory information is sent on the
-  data channel specified by the input-handle argument in the DIRECTORY
+data channel specified by the input-handle argument in the DIRECTORY
-  command.  This section describes the format of that single token
+command.  This section describes the format of that single token
-  list, and gives further detail on the properties argument to
+list, and gives further detail on the properties argument to
-  DIRECTORY.
+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
+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.
-Greenberg & Keene                                              [Page 26]
+          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
-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.
-            LIST-BEGIN
+                ([  [ ]    prop1 value1 prop2 value2]
-            pathname1       - pathname of the first file
+                [pathname1 prop1 value1 prop2 value2]
-            prop1 value1     - property/value pairs of first file
+                [pathname2 prop1 value1])
-            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
+The pathname is a string in the full pathname syntax of the server
-  top-level token list by depicting TOP-LEVEL-LIST-BEGIN and TOP-
+host.  See the section "Syntax of File and Directory Pathname
-  LEVEL-LIST-END by parentheses and LIST-BEGIN and LIST-END by squarbe
+Arguments", section 7.4.
-  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]
+For further information on file property/value pairs:  See the
-                    [pathname1 prop1 value1 prop2 value2]
+section "Format of NFILE File Property/Value Pairs", section 7.5.
-                    [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.
 .12  DISABLE-CAPABILITIES Command
-  Command:  (DISABLE-CAPABILITIES tid capability)
+Command:  (DISABLE-CAPABILITIES tid capability)
-  Response: (DISABLE-CAPABILITIES tid cap-1 success-1
+Response: (DISABLE-CAPABILITIES tid cap-1 success-1
-                  cap-2 success-2 cap-3 success-3 ...)
+              cap-2 success-2 cap-3 success-3 ...)
-  DISABLE-CAPABILITIES causes an access capability to be disabled on
+DISABLE-CAPABILITIES causes an access capability to be disabled on
-  the server machine.  capability is a string naming the capability to
+the server machine.  capability is a string naming the capability to
-  be disabled.  The meaning of the capability is dependent on the
+be disabled.  The meaning of the capability is dependent on the
-  operating system.
+operating system.
-  The return values cap-1, cap-2, and so on, are strings specifying
+The return values cap-1, cap-2, and so on, are strings specifying
-  names of capabilities.  If the capability named by cap-1 was
+names of capabilities.  If the capability named by cap-1 was
-  successfully disabled, the corresponding success-1 is supplied as
+successfully disabled, the corresponding success-1 is supplied as
-  Boolean truth; otherwise it is the empty token list.
+Boolean truth; otherwise it is the empty token list.
+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.
-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.
 .13  ENABLE-CAPABILITIES Command
-  Command:  (ENABLE-CAPABILITIES tid capability password)}
+Command:  (ENABLE-CAPABILITIES tid capability password)}
-  Response: (ENABLE-CAPABILITIES tid cap-1 success-1
+Response: (ENABLE-CAPABILITIES tid cap-1 success-1
-              cap-2 success-2 cap-3 success-3 ...)
+          cap-2 success-2 cap-3 success-3 ...)
-  ENABLE-CAPABILITIES causes an access capability to be enabled on the
+ENABLE-CAPABILITIES causes an access capability to be enabled on the
-  server machine.  The password argument is optional, and should be
+server machine.  The password argument is optional, and should be
-  included only if it is needed to enable this particular capability.
+included only if it is needed to enable this particular capability.
-  Both password and capability are strings.  The meaning of the
+Both password and capability are strings.  The meaning of the
-  capability is dependent on the operating system.
+capability is dependent on the operating system.
-  The return values cap-1, cap-2 and so on, are strings specifying
+The return values cap-1, cap-2 and so on, are strings specifying
-  names of capabilities.  If the capability named by cap-1 was
+names of capabilities.  If the capability named by cap-1 was
-  successfully enabled, the corresponding success-1 is supplied as
+successfully enabled, the corresponding success-1 is supplied as
-  Boolean truth; otherwise it is the empty token list.
+Boolean truth; otherwise it is the empty token list.
-  Although the user can specify only one capability to enable, it is
+Although the user can specify only one capability to enable, it is
-  conceivable that the result of enabling that particular capability is
+conceivable that the result of enabling that particular capability is
-  the enabling of other, related capabilities.  That is why the command
+the enabling of other, related capabilities.  That is why the command
-  response can contain information on more than one capability.
+response can contain information on more than one capability.
 .14  EXPUNGE Command
-  Command:  (EXPUNGE tid directory-pathname)
+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
+Response: (EXPUNGE tid server-storage-units-freed)
-  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
+EXPUNGE causes the directory specified by pathname to be expunged.
-  pathname format; it must refer to a directory on the server file
+Expunging means that any files that have been soft deleted are to be
-  system, and not to a file.  See the section "Syntax of File and
+permanently removed.
-  Directory Pathname Arguments", section 7.4.
+For file systems that do not support soft deletion, the command is to
+be ignored; a success command response is sent, but no action is
+performed on the file system.  In this case, the number-of-server-
+storage-units-freed return value should be omitted.
+directory-pathname is a required string argument in the directory
+pathname format; it must refer to a directory on the server file
+system, and not to a file.  See the section "Syntax of File and
+Directory Pathname Arguments", section 7.4.
+The return value server-storage-units-freed is an integer specifying
+how many records, blocks, or whatever unit is used to measure file
+storage on the server host system, were recovered.  This return value
+should be omitted if the server does not know how many storage units
+were freed.
-Greenberg & Keene                                              [Page 28]
+The protocol does not define whether directory-pathname is really a
+pathname as directory or a wildcard pathname of files to be expunged.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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).
-  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).
 .15  FILEPOS Command
-  Command:  (FILEPOS tid handle position resync-uid)
+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
+Response: (FILEPOS tid)
-  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
+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.
-Greenberg & Keene                                              [Page 29]
+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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+If the FILEPOS command is given on an input data channel (that is, a
+data channel currently sending data from server to user), the
+affected data channel must be resynchronized after the FILEPOS is
+accomplished, in order to identify the start of the new data.  The
+resync-uid is a unique identifier associated with the
+resynchronization of the data channel; it is unique with respect to
+this dialogue.  resync-uid must be supplied if handle is an input
+handle, but it is not supplied otherwise.  For more information on
+the resynchronization procedure:  See the section "NFILE Data
+Connection Resynchronization", section 9.2.
+In the output case, the user must somehow indicate to the server, on
+the output data channel, when there is no more data.  The user side
+sends the keyword token EOF to do so.  Upon receiving that control
-  token, the server is required to position the file pointer according
+token, the server is required to position the file pointer according
-  to the position given.  When the new file position is established,
+to the position given.  When the new file position is established,
-  the server resumes accepting data at the new file position.
+the server resumes accepting data at the new file position.
-  In most cases, using the direct access mode of transfer is more
+In most cases, using the direct access mode of transfer is more
-  convenient and efficient than repeated use of FILEPOS with a data
+convenient and efficient than repeated use of FILEPOS with a data
-  stream opening.
+stream opening.
-  There are problems inherent in trying to set a file position of a
+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
+character-oriented file on a foreign host, if one machine is a
-  Symbolics computer and the other is not.  For example, character set
+Symbolics computer and the other is not.  For example, character set
-  translation must take place.  See the section "NFILE Character Set",
+translation must take place.  See the section "NFILE Character Set",
-  section 6.  Because of these difficulties, FILEPOS might not be
+section 6.  Because of these difficulties, FILEPOS might not be
-  supported in the future on character files.  FILEPOS is not
+supported in the future on character files.  FILEPOS is not
-  problematic for binary files.
+problematic for binary files.
 .15.1  Implementation Hint for FILEPOS Command
-  The server processing of this command (by the control connection
+The server processing of this command (by the control connection
-  handler) must not attempt to wait for the resynchronization procedure
+handler) must not attempt to wait for the resynchronization procedure
-  to complete.  It is possible that the user could abort between
+to complete.  It is possible that the user could abort between
-  sending the FILEPOS command and reading for the mark and
+sending the FILEPOS command and reading for the mark and
-  resynchronization identifier.  That scenario could leave the sender
+resynchronization identifier.  That scenario could leave the sender
-  of the resynchronization identifier, on the server side, blocked for
+of the resynchronization identifier, on the server side, blocked for
-  output indefinitely.
+output indefinitely.
-  Only two commands received on the control connection can break the
+Only two commands received on the control connection can break the
-  data channel out of the blocked state described above:  CLOSE with
+data channel out of the blocked state described above:  CLOSE with
-  abort-p supplied as Boolean truth, and RESYNCHRONIZE-DATA-CHANNEL.
+abort-p supplied as Boolean truth, and RESYNCHRONIZE-DATA-CHANNEL.
-  Therefore, the control connection must not wait for the data channel
+Therefore, the control connection must not wait for the data channel
-  to finish performing the resynchronization procedure.  This wait
+to finish performing the resynchronization procedure.  This wait
-  should instead be performed by the process managing the data channel.
+should instead be performed by the process managing the data channel.
 .16  FINISH Command
-  Command:  (FINISH tid handle)
+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
+Response: (FINISH tid truename binary-p other-properties)
+FINISH closes a file and reopens it immediately with the file
+position pointer saved, thus leaving it open for further I/O.  If
+possible, the implementation should do the closing and opening in an
+indivisible operation, such that no other process can get access to
+the file.
-  The arguments, results, and their meaning are identical to those of
+The arguments, results, and their meaning are identical to those of
-  the CLOSE command.  See the section "CLOSE Command", section 8.3.
+the CLOSE command.  See the section "CLOSE Command", section 8.3.
-  FINISH requires a handle, which has the same meaning as the handle of
+FINISH requires a handle, which has the same meaning as the handle of
-  the CLOSE command.
+the CLOSE command.
-  In the output case, for both direct mode and data stream mode of
+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
+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
+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
+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
+server leaves the file in such a state that if the system or server
-  crashes anytime after the FINISH command has completed, it would
+crashes anytime after the FINISH command has completed, it would
-  later appear as though the file had been closed by this command.
+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
+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.
+for further I/O operations.  FINISH is a reliability feature.
-  FINISH is somewhat pointless in the input case, but valid.  The
+FINISH is somewhat pointless in the input case, but valid.  The
-  native Symbolics file system (LMFS) implements FINISH on an output
+native Symbolics file system (LMFS) implements FINISH on an output
-  file by an internal operation that effectively goes through the work
+file by an internal operation that effectively goes through the work
-  of closing but leaves the file open for appending.
+of closing but leaves the file open for appending.
-  ERRORS ON FINISH
+ERRORS ON FINISH
-  After writing every last bit sent by the user to disk, and before
+After writing every last bit sent by the user to disk, and before
-  closing the file, the server checks the data channel specified by
+closing the file, the server checks the data channel specified by
-  handle to see if an asynchronous error is outstanding on that
+handle to see if an asynchronous error is outstanding on that
-  channel.  That is, the server must determine whether it has sent an
+channel.  That is, the server must determine whether it has sent an
-  asynchronous error to the user, to which the user has not yet
+asynchronous error to the user, to which the user has not yet
-  responded with a CONTINUE command.  If so, the server is unable to
+responded with a CONTINUE command.  If so, the server is unable to
-  finish the file, and it must send a command error response response,
+finish the file, and it must send a command error response response,
-  indicating that an error is pending on the channel.  The appropriate
+indicating that an error is pending on the channel.  The appropriate
-  three-letter error code is EPC.  See the section "NFILE Errors and
+three-letter error code is EPC.  See the section "NFILE Errors and
-  Notifications", section 10.
+Notifications", section 10.
 .17  HOME-DIRECTORY Command
-  Command:  (HOME-DIRECTORY tid user)
+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.
+Response: (HOME-DIRECTORY tid directory-pathname)
-Greenberg & Keene                                              [Page 31]
+HOME-DIRECTORY returns the full pathname of the home directory on the
+server machine for the given user.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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.
 .18  LOGIN Command
-  Command:  (LOGIN tid user password FILE-SYSTEM USER-VERSION)
+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
+Response: (LOGIN tid keyword/value-pairs)
-  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.
+LOGIN logs the given user in to the server machine, using the
+password if necessary.  Both user and password are string arguments;
+user is required, password is optional.  An omitted password is valid
+if the host allows the specified user to log in without a password.
+Depending on the operating system and server, it might be necessary
+to log in to run a program (in this case the NFILE server program) on
+the host.  LOGIN establishes a user identity that is used by the
+operating system to establish the file author and determine file
+access rights during the current session.
+The server has the option to reject with an error any command except
+LOGIN if a successful LOGIN command has not been performed.  This is
+recommended.  Many operating systems perform the login function in a
+different process and/or environment than user programs.  The portion
+of the NFILE server running in the special login environment could
+conceivably be capable only of processing the LOGIN command; this is
+the reason for having the LOGIN command in NFILE.
+FILE-SYSTEM and USER-VERSION are optional keyword/value pairs.  The
+FILE-SYSTEM keyword/value pair selects the identity of the file
+system to which all following commands in this session are to be
+directed.  This argument has meaning only if the server host machine
+has multiple file systems, and the targeted file system is other than
+the default file system that a user would get by initiating a
+dialogue with that host.  The FILE-SYSTEM argument is an arbitrary
+token list.  If the server does not recognize it, the server gives an
+appropriate command error response.
+Currently, the only use of FILE-SYSTEM is for Symbolics servers to
+select one of the front-end processor hosts instead of the LMFS,
+which is the default.  In this case, the first element in the token
+list is the keyword FEP, and the second element in the token list is
+an integer, indicating the desired FEP disk unit number.  If the
+server discovers there is no such file system, the server gives a
+command error response including the three-letter code NFS, meaning
+"no file system".  See the section "NFILE Errors and Notifications",
+section 10.
+The user tells the server what version of NFILE it is running by
+including the optional USER-VERSION keyword/value pair.  The value
+associated with USER-VERSION can be a string, an integer, or a token
+list.  This document describes NFILE user version 2 and server
+version 2.
+Upon receiving the representation of the user version, the server can
+either adjust certain parameters to handle this particular version,
+or simply ignore the user version altogether.  Currently, the only
+released versions of NFILE are user version 2 and server version 2.
+LOGIN RETURN VALUES:  keyword/value-pairs
-Greenberg & Keene                                              [Page 32]
+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:
-RFC 1037            NFILE - A File Access Protocol        December 1987
+NAME
+The value associated with NAME is a string specifying the user
+identity, in the server host's terms.
-  The user tells the server what version of NFILE it is running by
+PERSONAL-NAME
-  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
+The value associated with PERSONAL-NAME is a string representing the
-  either adjust certain parameters to handle this particular version,
+user's personal name, last name first.  For example:  "McGillicuddy,
-  or simply ignore the user version altogether.  Currently, the only
+Aloysius X.".
-  released versions of NFILE are user version 2 and server version 2.
-  LOGIN RETURN VALUES:  keyword/value-pairs
+HOMEDIR-PATHNAME
-  The keyword/value-pairs is a token list composed of keywords followed
+The value associated with HOMEDIR-PATHNAME is a string in the
-  by their values.  The server includes any or all of the following
+pathname as directory format, indicating the home directory of the
-  keywords and their values; they are all optional.  The following
+user.  See the section "Syntax of File and Directory Pathname
-  keywords are recognized:
+Arguments", section 7.4.
-  NAME
+GROUP-AFFILIATION
-  The value associated with NAME is a string specifying the user
+The value associated with GROUP-AFFILIATION is a string specifying
-  identity, in the server host's terms.
+the group to which the user belongs, when this concept is
+appropriate.
-  PERSONAL-NAME
+SERVER-VERSION
-  The value associated with PERSONAL-NAME is a string representing the
+The value associated with SERVER-VERSION can be a string, an integer,
-  user's personal name, last name first.  For example:  "McGillicuddy,
+or a token list.  The value is a representation of the version of the
-  Aloysius X.".
+server is running.  Upon receiving the server version, the user can:
+adjust certain parameters to handle this particular version; accept
-  HOMEDIR-PATHNAME
+the version; or close the connection.  Currently, the only released
+versions of NFILE are user version 2 and server version 2.
-  The value associated with HOMEDIR-PATHNAME is a string in the
+PROPERTY-INDEX-TABLE
-  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 PROPERTY-INDEX-TABLE is a token list of
+keywords.  This return value enables the server to inform the user
-  The value associated with GROUP-AFFILIATION is a string specifying
+which file properties are meaningful on its file system.  The
-  the group to which the user belongs, when this concept is
+keywords in PROPERTY-INDEX-TABLE can be used by the DIRECTORY command
-  appropriate.
+(a user request for information on file properties of a specified
+directory or directories).  The server can specify a certain property
-  SERVER-VERSION
+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
-  The value associated with SERVER-VERSION can be a string, an integer,
+directory listings.  The first element in PROPERTY-INDEX-TABLE is
-  or a token list.  The value is a representation of the version of the
+indexed by the number 0.  See the section "DIRECTORY Command",
-  server is running.  Upon receiving the server version, the user can:
+section 8.11.
-  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.
 .19  MULTIPLE-FILE-PLISTS Command
-  Command:  (MULTIPLE-FILE-PLISTS tid input-handle paths
+Command:  (MULTIPLE-FILE-PLISTS tid input-handle paths
-              characters properties)
+          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.
+Response: (MULTIPLE-FILE-PLISTS tid)
-Greenberg & Keene                                              [Page 34]
+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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+characters is either Boolean truth (indicating that each file is a
+character file), the empty token list (each file is a binary file),
+or the keyword DEFAULT.  DEFAULT indicates that the server itself is
+to figure out whether a file is a character or binary file.  For more
+information on the meaning of the DEFAULT keyword:  See the section
+"OPEN Command", section 8.20.  The value of characters can influence
+some servers' idea of a file's length.
+properties is a token list of keywords indicating which properties
+the user wants returned.  The server is always free to return more
+properties than those requested in the properties argument.  If
+properties is supplied as the empty token list, the server should
+transmit all known properties on the files.
-  The server transmits as much of the requested information as possible
+The server transmits as much of the requested information as possible
-  on the given input-handle.  The information is contained in a top-
+on the given input-handle.  The information is contained in a top-
-  level token list of elements.  Each element corresponds with a
+level token list of elements.  Each element corresponds with a
-  supplied pathname; the order of the original pathlist must be
+supplied pathname; the order of the original pathlist must be
-  retained in the returned token list.  An element is an empty token
+retained in the returned token list.  An element is an empty token
-  list if the corresponding file or any of its containing directories
+list if the corresponding file or any of its containing directories
-  does not exist.  The elements that correspond to successfully located
+does not exist.  The elements that correspond to successfully located
-  files are lists composed of truename followed by any properties.
+files are lists composed of truename followed by any properties.
-  properties are keyword/value pairs.  truename is a string in the full
+properties are keyword/value pairs.  truename is a string in the full
-  pathname syntax of the server host.
+pathname syntax of the server host.
-  The following example shows TOP-LEVEL-LIST-BEGIN and TOP-LEVEL-LIST-
+The following example shows TOP-LEVEL-LIST-BEGIN and TOP-LEVEL-LIST-
-  END as parentheses, and LIST-BEGIN and LIST-END with square brackets.
+END as parentheses, and LIST-BEGIN and LIST-END with square brackets.
-  For example, the user supplied a pathlist argument resembling:
+For example, the user supplied a pathlist argument resembling:
-                            [file1 file2 file3]
+                        [file1 file2 file3]
-  The server could not locate file1 or file3, but did locate file2, and
+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
+found the length and author of file2.  The top-level token list
-  transmitted by the server is:
+transmitted by the server is:
-        ( [] [ truename-of-file2 LENGTH 381 AUTHOR williams ] [] )
+    ( [] [ truename-of-file2 LENGTH 381 AUTHOR williams ] [] )
-  For further detail on how file properties and values are expressed:
+For further detail on how file properties and values are expressed:
-  See the section "Format of NFILE File Property/Value Pairs", section
+See the section "Format of NFILE File Property/Value Pairs", section
 .5.
 .20  OPEN Command
-  Command:  (OPEN tid handle pathname direction binary-p
+Command:  (OPEN tid handle pathname direction binary-p
-                TEMPORARY RAW SUPER-IMAGE DELETED PRESERVE-DATES
+            TEMPORARY RAW SUPER-IMAGE DELETED PRESERVE-DATES
-                SUBMIT DIRECT-FILE-ID ESTIMATED-LENGTH BYTE-SIZE
+            SUBMIT DIRECT-FILE-ID ESTIMATED-LENGTH BYTE-SIZE
-                IF-EXISTS IF-DOES-NOT-EXIST)
+            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.
+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.
-Greenberg & Keene                                              [Page 35]
+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.
-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 following arguments are required:  pathname, direction, and
+The OPEN return values reflect information about the file opened,
-  binary-p.  handle is an optional argument, which must either be
+when the opening is successful.  In the case of a probe-type opening,
-  supplied or explicitly omitted by means of substituting in its place
+this information is returned when the given file (or link, or
-  the empty token list.
+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
+.20.2.
-  The OPEN command has many optional keyword/value pairs, which encode
+THE pathname OPEN ARGUMENT
-  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,
+The pathname is a required argument specifying the file to be opened.
-  when the opening is successful.  In the case of a probe-type opening,
+pathname is a string in the full pathname syntax of the server host.
-  this information is returned when the given file (or link, or
+See the section "Syntax of File and Directory Pathname Arguments",
-  directory) exists and is accessible, even though the file (or link,
+section 7.4.
-  or directory) is not actually opened.  For detail on the OPEN return
-  values: See the section "NFILE OPEN Response Return Values", section
-.20.2.
-  THE pathname OPEN ARGUMENT
+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 pathname is a required argument specifying the file to be opened.
+THE handle OPEN ARGUMENT
-  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
+The handle argument of the OPEN command specifies a data channel to
-  supplied as PROBE-DIRECTORY), only the directory specified by this
+be used for the transfer.  Subsequent commands in this session use
-  pathname is utilized.  See the section "NFILE OPEN Optional
+the same handle to specify this opening.  It is the user side's
-  Keyword/Value Pairs", section 8.20.1.
+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 handle OPEN ARGUMENT
+THE direction OPEN ARGUMENT
-  The handle argument of the OPEN command specifies a data channel to
+The direction argument must be supplied as one of these keywords:
-  be used for the transfer.  Subsequent commands in this session use
+INPUT, OUTPUT, IO, PROBE, PROBE-DIRECTORY, and PROBE-LINK.  The
-  the same handle to specify this opening.  It is the user side's
+meanings of the direction keywords are as follows:
-  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
+INPUT
-   The direction argument must be supplied as one of these keywords:
+   Specifies that the file is to be opened for input server-to-user
-   INPUT, OUTPUT, IO, PROBE, PROBE-DIRECTORY, and PROBE-LINK.  The
+   transfer).  To request a direct access opening, supply a value for
-   meanings of the direction keywords are as follows:
+  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.
-Greenberg & Keene                                              [Page 36]
+IO
-RFC 1037            NFILE - A File Access Protocol        December 1987
+  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.
-  INPUT
+PROBE
-      Specifies that the file is to be opened for input server-to-user
+  Specifies that the file is not to be opened at all, but simply
-      transfer).  To request a direct access opening, supply a value for
+  checked for existence.  If the file does not exist or is not
-      DIRECT-FILE-ID. If no DIRECT-FILE-ID is supplied, the opening is a
+  accessible, the error indications and actions are identical to
-      data stream opening.
+  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.
-  OUTPUT
+PROBE-LINK
-      Specifies that the file is to be opened for output user-to-server
+  Like PROBE, with one difference.  PROBE-LINK specifies that if the
-      transfer).  To request a direct access opening, supply a value for
+  pathname is found to refer to a link, that link is not to be
-      DIRECT-FILE-ID. If no DIRECT-FILE-ID is supplied, the opening is a
+  followed, and information about the link itself is to be returned.
-      data stream opening.
-  IO
+PROBE-DIRECTORY
-      Specifies that interspersed input and output will be performed on
+  PROBE-DIRECTORY requests information about the directory
-      the file.  This is only meaningful in direct access mode.  A
+  designated by the pathname argument.  In the PROBE-DIRECTORY case,
-      DIRECT-FILE-ID must also be supplied.  See the section "NFILE OPEN
+  the pathname argument refers to the directory on which information
-      Optional Keyword/Value Pairs", section 8.20.1.
+  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.
-  If direction is supplied as PROBE, PROBE-LINK, or PROBE-DIRECTORY,
+THE binary-p OPEN ARGUMENT
-  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
+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.
-      Specifies that the file is not to be opened at all, but simply
+If binary-p is supplied as the empty token list, the opening is said
-      checked for existence.  If the file does not exist or is not
+to be a character opening.  The server performs character set
-      accessible, the error indications and actions are identical to
+translation between its native character set and the NFILE character
-      those that would be given for an INPUT opening.  If the file does
+set.  The data is transferred over the data connection one character
-      exist, the successful command response contains the same
+per eight-bit byte.  See the section "NFILE Character Set", section
-      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
+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.
-      Like PROBE, with one difference.  PROBE-LINK specifies that if the
+binary-p can also be supplied as the keyword DEFAULT.  DEFAULT
-      pathname is found to refer to a link, that link is not to be
+specifies that the server itself is to determine whether to transfer
-      followed, and information about the link itself is to be returned.
+binary or character data.  DEFAULT is meaningful only for input
+openings; it is an error for OUTPUT, IO, or probe-type openings.  For
+file systems that maintain the innate binary or character nature of a
+file, the server simply asks the file system which case is in force
+for the file specified by pathname.
+When binary-p is supplied as DEFAULT, on file systems that do not
+maintain thisinformation, the server is required to perform a
+heuristic check for Symbolicsobject fileson the first two 16-bit
+bytes of the file.  If the file isdetermined to be aSymbolics object
+file, the server performs a BINARY openingwith BYTE-SIZE of16;
+otherwise, it performs a CHARACTER opening.
+The details of the check are as follows: if the first 16-bit byte is
+the octal number170023 and the second 16-bit byte is any number
+between 0 and 77 octal(inclusive), the file is recognized as a
+Symbolics object file.  In any othercase, it is not.
-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
-.
-  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.
 .20.1  NFILE OPEN Optional Keyword/Value Pairs
-  The OPEN command has many optional keyword/value pairs that encode
+The OPEN command has many optional keyword/value pairs that encode
-  conceptual arguments to the file system for the OPEN operation.
+conceptual arguments to the file system for the OPEN operation.
-  The following options are used often:
+The following options are used often:
-  BYTE-SIZE
+BYTE-SIZE
-      Must be followed by an integer between 1 and 16, inclusive, or the
+  Must be followed by an integer between 1 and 16, inclusive, or the
-      empty token list.  BYTE-SIZE is meaningful only for binary
+  empty token list.  BYTE-SIZE is meaningful only for binary
-      openings.  BYTE-SIZE can be ignored for probe-type openings.  It
+  openings.  BYTE-SIZE can be ignored for probe-type openings.  It
-      can be omitted entirely for character openings, but if supplied,
+  can be omitted entirely for character openings, but if supplied,
-      must be followed by the empty token list.  If binary-p is 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
+  as DEFAULT, BYTE-SIZE can be omitted entirely, or followed by the
-      empty token list.
+  empty token list.
-      If a binary opening is requested and BYTE-SIZE is not supplied,
+  If a binary opening is requested and BYTE-SIZE is not supplied,
-      the assumed value is 16 for output openings. For input binary
+  the assumed value is 16 for output openings. For input binary
-      openings, the default is the host file system's stored conception
+  openings, the default is the host file system's stored conception
-      of the file's byte size (for those hosts that natively support
+  of the file's byte size (for those hosts that natively support
-      byte size).  For file systems that do not natively support
+  byte size).  For file systems that do not natively support
-      natively byte size, the default byte-size on binary input is 16.
+  natively byte size, the default byte-size on binary input is 16.
-      For file systems that maintain the innate byte-size of each file,
+  For file systems that maintain the innate byte-size of each file,
-      the server should supply this number to the appropriate operating
+  the server should supply this number to the appropriate operating
-      system interface that performs the semantics of opening the file.
+  system interface that performs the semantics of opening the file.
-      For other operating systems, a file written with a given byte size
+  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
+  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
+  byte size.  In this case, the server or host operating system can
-      choose any packing scheme that complies with this rule.
+  choose any packing scheme that complies with this rule.
-      Operating systems that do not support byte size must ensure that
+  Operating systems that do not support byte size must ensure that
-      binary files written from user ends of the current protocol can be
+  binary files written from user ends of the current protocol can be
-      read back correctly.  However, the server can choose packing
+  read back correctly.  However, the server can choose packing
-      schemes that allow all bits of the server host's word to be
+  schemes that allow all bits of the server host's word to be
-      accessed and concur with other packing schemes used by native host
+  accessed and concur with other packing schemes used by native host
-      software.
+  software.
-      For example, Multics supports 36 bit words and 9 bit bytes.  A
+  For example, Multics supports 36 bit words and 9 bit bytes.  A
-      packing scheme appropriate for a Multics NFILE server is:
+  packing scheme appropriate for a Multics NFILE server is:
+            Byte Size                Packing Scheme
+, 8, or 9 bits          four per 36-bit word
+, 11, or 12 bits      three per 36-bit word
+, 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
-Greenberg & Keene                                              [Page 39]
+  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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+  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
-              Byte Size                Packing Scheme
+  If supplied, the DIRECT-FILE-ID indicates that the opening is to
+  be a direct access mode opening.  If not supplied, the opening is
-, 8, or 9 bits          four per 36-bit word
+  a data stream opening.  The value of DIRECT-FILE-ID is a string
-, 11, or 12 bits      three per 36-bit word
+  generated by the user, that has not been used as a DIRECT-FILE-ID
-, 14, 15, or 16 bits  two per 36-bit word
+  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.
-      In the first packing scheme in the table, native Multics
+PRESERVE-DATES
-      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, PRESERVE-DATES specifies that the
-      If supplied as Boolean truth, DELETED specifies that deleted"
+  server is to attempt to prevent the operating system from updating
-      files are to be treated as though they were not "deleted".
+  the "reference date" or date-time used" of the file.  This is
-      DELETED is meaningful only for operating systems that support
+  meaningful only for input openings, and is an error otherwise.
-      "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 Symbolics operating system invokes this option for operations
-      the same effect as omitting the DELETED keyword/value pair
+  such as View File in the editor, where it wishes to assert that
-      entirely.  For output openings, DELETED is meaningless and an
+  the user did not "read" the file, but just "looked at it".
-      error if supplied.
+  Servers on operating systems that do not support reference dates
+  or users revising or suppressing update of the reference dates
+  must ignore this option.
-  DIRECT-FILE-ID
+ESTIMATED-LENGTH
-      If supplied, the DIRECT-FILE-ID indicates that the opening is to
+  The value of ESTIMATED-LENGTH is an integer estimating the length
-      be a direct access mode opening.  If not supplied, the opening is
+  of the file to be transferred. This option is meaningful and
-      a data stream opening.  The value of DIRECT-FILE-ID is a string
+  permitted only for output openings.  ESTIMATED-LENGTH enables the
-      generated by the user, that has not been used as a DIRECT-FILE-ID
+  user end to suggest to the server's file system how long the file
-      in this dialogue, and does not designate any data channel.  The
+  is going to be.  This can be useful for file systems that must
-      DIRECT-FILE-ID is a unique identifier for the direct access
+  preallocate files or file maps or that accrue performance benefits
-      opening.  It is used for all operations that identify an opening
+  from knowing this information at nthe time the file is first
-      rather than a data channel.  The DIRECT-FILE-ID is used to
+  opened.  This estimate, if supplied, is not required to be exact.
-      identify a direct access opening, just as a file handle is used to
+  It is ignored by servers to which it is not useful or interesting.
-      identify a data stream opening.  The PROPERTIES, CLOSE, and RENAME
+  The units of the estimate are characters for character openings,
-      commands use the DIRECT-FILE-ID in this way.  There are only two
+  and bytes of the agreed-upon byte size for binary openings.  The
-      NFILE commands applicable to direct access openings (ABORT and
+  character units should be server units, if possible, but since
-      CONTINUE) that do not use the DIRECT-FILE-ID, but use a data
+  this is only an estimate, NFILE character units are acceptable.
-      channel handle instead.
+  See the section "NFILE Character Set", section 6.
-  PRESERVE-DATES
+IF-EXISTS
-      If supplied as Boolean truth, PRESERVE-DATES specifies that the
+  Meaningful only for output openings, ignored otherwise, but not
+  diagnosed as an error.  The value of IF-EXISTS is a keyword that
+  specifies the action to Be taken if a file of the given name
+  already exists.  The semantics of the values are derived from the
+  Common Lisp specification and repeated here for completeness.  If
+  the file does not already exist, the IF-EXISTS option and its
+  value are ignored.
+  If the user side does not give the IF-EXISTS option, The action to
+  be taken if a file of the given name already exists depends on
+  whether or not the file system supports file versions.  If it
+  does, the default is ERROR (if an explicit version is given in the
+  file pathname) or NEW-VERSION (if the version in the file pathname
+  is the newest version).  For file systems not supporting versions,
+  the default is SUPERSEDE.  These actions are described below.
+  IF-EXISTS provides the mechanism for overwriting or appending to
+  files.  With the default setting of IF-EXISTS, new files are
+  created by every output opening.
-Greenberg & Keene                                              [Page 40]
+  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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+  Here are the possible values and their meanings:
+  ERROR
-       server is to attempt to prevent the operating system from updating
+       Reports an error.
-      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
+  NEW-VERSION
-      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
+      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.
-      The value of ESTIMATED-LENGTH is an integer estimating the length
+  RENAME
-      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
+      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.
-      Meaningful only for output openings, ignored otherwise, but not
+  RENAME-AND-DELETE
-      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
+       Renames the existing file to some other name and then deletes
-      be taken if a file of the given name already exists depends on
+      it (but does not expunge it, on those systems that distinguish
-       whether or not the file system supports file versions.  If it
+       deletion from expunging).  Then it creates a new file with the
-      does, the default is ERROR (if an explicit version is given in the
+       specified name.  On most file systems, this renaming happens at
-      file pathname) or NEW-VERSION (if the version in the file pathname
+       the time of a successful close.
-       is the newest version).  For file systems not supporting versions,
-       the default is SUPERSEDE.  These actions are described below.
+  OVERWRITE
+      Output operations on the opening destructively modify the
+      existing file.  New data replaces old data at the beginning of
+      the file; however, the file is not truncated to length zero
+      upon opening.
+  TRUNCATE
+      Output operations on the opening destructively modify the
+      existing file.  The file pointer is initially positioned at the
+      beginning of the file; at that time, TRUNCATE truncates the
+      file to length zero and frees disk storage occupied by it.
+  APPEND
-Greenberg & Keene                                              [Page 41]
+      Output operations on the opening destructively modify the
+      existing file.  New data is placed at the current end of the
+      file.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+  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.
-       IF-EXISTS provides the mechanism for overwriting or appending to
+       There are currently no standards on what a server can do if it
-       files.  With the default setting of IF-EXISTS, new files are
+       cannot implement some of these actions.
-      created by every output opening.
-      Operating systems supporting soft deletion can take different
+IF-DOES-NOT-EXIST
-      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:
+  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.
-      ERROR
+  These are the values for IF-DOES-NOT-EXIST:
-        Reports an error.
+  ERROR
-       NEW-VERSION
+       Reports an error.
-        Creates a new file with the same file name but with a larger
+  CREATE
-        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
+       Creates an empty file with the specified name and then proceeds
+      as if it already existed.
-        Renames the existing file to some other name and then creates a
+The following optional keyword/value pairs are rarely used, if ever:
-        new file with the specified name.  On most file systems, this
-        renaming happens at the time of a successful close.
-      RENAME-AND-DELETE
+RAW
-        Renames the existing file to some other name and then deletes
+  If supplied as Boolean truth, RAW specifies that character set
-        it (but does not expunge it, on those systems that distinguish
+  translation is not to be performed, but that characters are to be
-        deletion from expunging).  Then it creates a new file with the
+  transferred intact, without inspection.  This option is meaningful
-        specified name.  On most file systems, this renaming happens at
+  only for character openings; it is an error otherwise.  It is also
-        the time of a successful close.
+  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.
-      OVERWRITE
+SUPER-IMAGE
-        Output operations on the opening destructively modify the
+  If supplied as Boolean truth, SUPER-IMAGE specifies that Rubout
-        existing file.  New data replaces old data at the beginning of
+  quoting is not to be performed.  This operation is meaningful only
-        the file; however, the file is not truncated to length zero
+  for character openings; it is an error otherwise.  It is also an
-        upon opening.
+  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
-Greenberg & Keene                                              [Page 42]
+  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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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
-      TRUNCATE
+   keyword/value pair were omitted entirely.  Servers that do not
+  implement this option should give an error response if requested
-        Output operations on the opening destructively modify the
+  to submit a file to the operating system.
-        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.
 .20.2  NFILE OPEN Response Return Values
-  The results of a successful OPEN operation are reported in the
+The results of a successful OPEN operation are reported in the
-  command response.  Here is the specification of the OPEN response
+command response.  Here is the specification of the OPEN response
-  format:
+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
+Response Format:
+  (OPEN tid truename binary-p other-properties)
-Greenberg & Keene                                              [Page 45]
+The return values for OPEN and CLOSE are syntactically identical, but
+the values can change in the time interval between open and close.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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.
-  content of the file, not necessarily the agency that actually created
+The return value binary-p indicates whether the opening is a binary
-  the file.
+or character opening.  For binary openings, binary-p is supplied as
+Boolean truth; for character openings it is the empty token list.
-  BYTE-SIZE
+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.
-  The byte-size agreed upon via the rules described for the BYTE-SIZE
+AUTHOR
-  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 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
-  The creation date of the file.  The date is expressed in Universal
+content of the file, not necessarily the agency that actually created
-  Time format, which measures a time as the number of seconds since
+the file.
-  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
+BYTE-SIZE
-  (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
+The byte-size agreed upon via the rules described for the BYTE-SIZE
-  identifier of file contents, for a given file name, type, and
+option.  The value of BYTE-SIZE is an integer.  For details on the
-  version, to prove that a file has not changed since it last recorded
+ramifications of BYTE-SIZE:  See the section "NFILE OPEN Optional
-  this quantity for a file.
+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.
-  FILEPOS
+CREATION-DATE
-  An integer giving the position of the logical file pointer, in
+The creation date of the file.  The date is expressed in Universal
-  characters or bytes as appropriate for the type of opening.  This is
+Time format, which measures a time as the number of seconds since
-  always zero for an input opening and for an output opening creating a
+January 1, 1900, at midnight GMT.  Creation date does not necessarily
-  new file.  For an output opening appending to an existing file,
+mean the time the file system created the directory entry or records
-  FILEPOS is the number of characters or bytes, as appropriate,
+of the file.  For systems that support modification or appending to
-  currently in the file.  This number, for character openings, is
+files, it is usually the modification date of the file.  Creation
-  measured in server units: See the section "NFILE Character Set",
+date can mean the date that the bit count or byte count of the file
-  section 6.
+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.
-Greenberg & Keene                                              [Page 46]
+FILEPOS
-RFC 1037            NFILE - A File Access Protocol        December 1987
+An integer giving the position of the logical file pointer, in
+characters or bytes as appropriate for the type of opening.  This is
+always zero for an input opening and for an output opening creating a
+new file.  For an output opening appending to an existing file,
+FILEPOS is the number of characters or bytes, as appropriate,
+currently in the file.  This number, for character openings, is
+measured in server units: See the section "NFILE Character Set",
+section 6.
+LENGTH
-  LENGTH
+An integer reporting the length of the file, in characters for
+character openings and in bytes of the agreed-upon size for binary
-  An integer reporting the length of the file, in characters for
+openings.  LENGTH should be reported as zero for output openings,
-  character openings and in bytes of the agreed-upon size for binary
+even if appending to an existing file.  The server usually only knows
-  openings.  LENGTH should be reported as zero for output openings,
+the length for a character opening in server units; thus, it reports
-  even if appending to an existing file.  The server usually only knows
+length in server units.
-  the length for a character opening in server units; thus, it reports
-  length in server units.
 .21  PROPERTIES Command
-  Command:  (PROPERTIES tid handle pathname control-keywords
+Command:  (PROPERTIES tid handle pathname control-keywords
-  properties)
+properties)
-  Response: (PROPERTIES tid property-element settable-properties)
+Response: (PROPERTIES tid property-element settable-properties)
-  PROPERTIES requests the property information about one file.  The
+PROPERTIES requests the property information about one file.  The
-  file is identified by the pathname argument or the handle argument,
+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
+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
+pathname syntax of the server host.  See the section "Syntax of File
-  and Directory Pathname Arguments", section 7.4.
+and Directory Pathname Arguments", section 7.4.
-  If handle is supplied, its value is a string identifying an opening,
+If handle is supplied, its value is a string identifying an opening,
-  which implicitly identifies a file.  For direct access mode openings,
+which implicitly identifies a file.  For direct access mode openings,
-  handle must be a direct file identifier.
+handle must be a direct file identifier.
-  control-keywords is reserved in the current design.  However, it is a
+control-keywords is reserved in the current design.  However, it is a
-  required argument, and must be supplied as the empty token list.  Its
+required argument, and must be supplied as the empty token list.  Its
-  presence in the NFILE specification allows for future expansion.  In
+presence in the NFILE specification allows for future expansion.  In
-  the future the value of control-keywords might affect the listing
+the future the value of control-keywords might affect the listing
-  mode.
+mode.
-  properties is a token list of keywords indicating the properties the
+properties is a token list of keywords indicating the properties the
-  user wants returned.  (In command arguments, properties cannot be
+user wants returned.  (In command arguments, properties cannot be
-  specified with integers, such as indices into the Property Index
+specified with integers, such as indices into the Property Index
-  Table).  For a list of keywords associated with file properties:  See
+Table).  For a list of keywords associated with file properties:  See
-  the section "Format of NFILE File Property/Value Pairs", section 7.5.
+the section "Format of NFILE File Property/Value Pairs", section 7.5.
-  The server is always free to return more properties than those
+The server is always free to return more properties than those
-  requested in the properties argument.  If properties is supplied as
+requested in the properties argument.  If properties is supplied as
-  the empty token list, the server transmits all known properties of
+the empty token list, the server transmits all known properties of
-  the file.
+the file.
+PROPERTIES COMMAND RESPONSE
+The server returns the property information for the given file in the
+command response.  The PROPERTIES command does not use any data
+channels.  If the specified file does not exist or is not accessible,
+the server signals an error and includes an appropriate three-letter
+error code in the command error response.  See the section "NFILE
+Errors and Notifications", section 10.
+The return value property-element is a token list.  The first element
+in that token list is the pathname of the file, in the full pathname
+syntax of the server host.  The following elements of the property-
+element token list are property/value pairs.  The server is expected
+to return several property/value pairs; the number of pairs is not
+constrained.  For further details on file properties and their
+associated values:  See the section "Format of NFILE File
+Property/Value Pairs", section 7.5.
+The return value settable-properties is a token list of keywords.
+The number of keywords is not constrained.  (Note that integers
+cannot be used in settable-properties to indicate the file property;
+keywords are to be used instead.)  Each keyword supplied in
+settable-properties identifies a property considered settable by the
+server.  The server is implicitly guaranteeing a mechanism for
+changing the properties reported as settable.  The user can change
+any of the settable properties for this file by using the CHANGE-
+PROPERTIES command.  See the section "CHANGE-PROPERTIES Command",
+section 8.2.
+The following example shows the format of the PROPERTIES command
+response.  Remember that the number of property/value pairs and
+keywords is not constrained; this example has two property/value
+pairs and three settable-properties keywords returned:
+          TOP-LEVEL-LIST-BEGIN
+          PROPERTIES        - name of the command
+          tid                - transaction identifier
+          LIST-BEGIN
+          pathname of file
+          prop1 value1      - file's property/value pairs
+          prop2 value2
+          LIST-END
+          LIST-BEGIN
+          keyword-1          - file's settable properties
+          keyword-2
+          keyword-3
+          LIST-END
+          TOP-LEVEL-LIST-END
+The following example is designed to better show the structure of the
+top-level token list by depicting TOP-LEVEL-LIST-BEGIN and TOP-
+LEVEL-LIST-END by parentheses and LIST-BEGIN and LIST-END by square
+brackets.  The indentation and newlines in the example are not part
+of the token list, but are used here to make the structure of the
+token list clear.
+          (PROPERTIES tid [ pathname prop1 value1 prop2 value2 ...]
-Greenberg & Keene                                              [Page 47]
+                          [ keyword1 keyword2 keyword3 ... ]
-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 ... ]
 .22  READ Command
-  Command: (READ tid direct-file-id input-handle count FILEPOS)
+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]
+Response: (READ tid)
-RFC 1037            NFILE - A File Access Protocol        December 1987
+READ requests input data flow for direct access openings.  The
+direct-file-id is the same as the DIRECT-FILE-ID argument that was
+given when opening the file; it designates the opening from which the
+characters or bytes are to be transferred.  The input-handle
+specifies which data channel should be used for the transfer of data
+from server to user.  The data channel should have been already
+established, cannot have been disestablished, and must not currently
+be in use.
+count is an integer specifying how many bytes (or NFILE characters,
+as appropriate) to read.  count can be supplied as the empty token
+list, meaning read to the end of the file.  If the user specifies the
+empty token list or a count greater than the number of bytes
+remaining in the file, the server sends the keyword EOF to mark the
+end of the file.
-  FILEPOS is an optional keyword/value pair.  If the keyword FILEPOS is
+FILEPOS is an optional keyword/value pair.  If the keyword FILEPOS is
-  supplied, it must be followed by an integer.  Before data is
+supplied, it must be followed by an integer.  Before data is
-  transferred, the opening is positioned to the point specified by the
+transferred, the opening is positioned to the point specified by the
-  value of FILEPOS.  The position of the point is measured in server
+value of FILEPOS.  The position of the point is measured in server
-  units for character openings; for binary openings it is measured in
+units for character openings; for binary openings it is measured in
-  binary bytes.  See the section "FILEPOS NFILE Command".
+binary bytes.  See the section "FILEPOS NFILE Command".
-  Upon receiving the READ command, the server binds the data channel to
+Upon receiving the READ command, the server binds the data channel to
-  the opening and immediately begins transferring data.  The server
+the opening and immediately begins transferring data.  The server
-  stops when all data has been transferred.  After the server sends the
+stops when all data has been transferred.  After the server sends the
-  last requested byte, it unbinds the data channel, freeing it for
+last requested byte, it unbinds the data channel, freeing it for
-  other use.  When the user side has processed the last byte, the user
+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
+side assumes that the data channel can now be reused for another data
-  transfer.
+transfer.
 .23  RENAME Command
-  Command:  (RENAME tid handle pathname to-pathname)
+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.
+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.
-Greenberg & Keene                                              [Page 50]
+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
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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.
 .24  RESYNCHRONIZE-DATA-CHANNEL Command
-  The command and response format for this command varies, depending on
+The command and response format for this command varies, depending on
-  whether the handle argument indicates an input or output data
+whether the handle argument indicates an input or output data
-  channel.
+channel.
-  For an Input Handle:
+For an Input Handle:
-  Command:  (RESYNCHRONIZE-DATA-CHANNEL tid handle)
+Command:  (RESYNCHRONIZE-DATA-CHANNEL tid handle)
-  Response: (RESYNCHRONIZE-DATA-CHANNEL tid identifier)
+Response: (RESYNCHRONIZE-DATA-CHANNEL tid identifier)
-  For an Output Handle:
+For an Output Handle:
-  Command:  (RESYNCHRONIZE-DATA-CHANNEL tid handle identifier)
+Command:  (RESYNCHRONIZE-DATA-CHANNEL tid handle identifier)
-  Response: (RESYNCHRONIZE-DATA-CHANNEL tid)
+Response: (RESYNCHRONIZE-DATA-CHANNEL tid)
-  RESYNCHRONIZE-DATA-CHANNEL begins a prescribed procedure between user
+RESYNCHRONIZE-DATA-CHANNEL begins a prescribed procedure between user
-  and server over the unsafe data channel specified by handle.  The
+and server over the unsafe data channel specified by handle.  The
-  resynchronization procedure clears the data channel of any unwanted
+resynchronization procedure clears the data channel of any unwanted
-  data, and restores the data channel to a safe state, ready to
+data, and restores the data channel to a safe state, ready to
-  transfer data again.
+transfer data again.
-  All arguments to RESYNCHRONIZE-DATA-CHANNEL are required.
+All arguments to RESYNCHRONIZE-DATA-CHANNEL are required.
-  For a detailed description of how the user and server coordinate the
+For a detailed description of how the user and server coordinate the
-  resynchronization of data channels:  See the section "NFILE Data
+resynchronization of data channels:  See the section "NFILE Data
-  Connection Resynchronization", section 9.2.
+Connection Resynchronization", section 9.2.
 .24.1  Implementation Hints for RESYNCHRONIZE-DATA-CHANNEL Command
-  In general, both the user and server should should be implemented
+In general, both the user and server should should be implemented
-  with the knowledge that a transmission can be aborted.  That is, the
+with the knowledge that a transmission can be aborted.  That is, the
-  receiving side must be careful not to act upon a transmission (that
+receiving side must be careful not to act upon a transmission (that
-  is, to perform any action or side effect) until the transmission has
+is, to perform any action or side effect) until the transmission has
-  been successfully received in entirety.  This protects the user
+been successfully received in entirety.  This protects the user
-  program from the possibility that an abort can occur after a
+program from the possibility that an abort can occur after a
-  transmission has been partially sent.
+transmission has been partially sent.
+RESYNCHRONIZING AN OUTPUT DATA CHANNEL
+The server will probably want to dispatch the looping and reading to
+the logical data process.  Looping reading for the resynchronization
+identifier in the control connection handler is not a viable option.
+If the user side fails to send the resynchronization identifier (for
+example, due to a user abort) the control connection handler can
+never be broken out of this loop.
+Should the user side send the control connection handler command
+first, or send the marks and identifiers first?
+Sending the marks first is problematic, because the data channel at
+the other end might not be reading them (for it has not yet been so
+instructed by the control connection handler).  The user might then
+become blocked for output, thus prohibiting sending of the
+RESYNCHRONIZE-DATA-CHANNEL command.
-Greenberg & Keene                                              [Page 51]
+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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+RESYNCHRONIZING AN INPUT DATA CHANNEL
+The server control process should dispatch the data process to send
-  RESYNCHRONIZING AN OUTPUT DATA CHANNEL
+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
-  The server will probably want to dispatch the looping and reading to
+command loop, to possibly receive a command that might break the data
-  the logical data process.  Looping reading for the resynchronization
+process out of that block.
-  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.
 .25  UNDATA-CONNECTION Command
-  Command:  (UNDATA-CONNECTION tid input-handle output-handle)
+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.
-.  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
-.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
-. The user side sends a mark over the control connection to
-          the server.
-. The user side sends the ASCII characters USER-RESYNC-DUMMY
-          (as a data token) to the server.
-. The user side sends a second mark to the server.
-. The user side declares the control connection safe (at the
-          token list level).
-. The user side generates and sends a unique data token to
-          the server.
-. 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
-. The server side detects a mark.  The server is thus alerted
-          that the control connection is unsafe, and that
-          resynchronization is in progress.
-. The server continues to read data coming from the user side
-          until it detects the second mark, and the token following
-          it.
+Response: (UNDATA-CONNECTION tid)
-Greenberg & Keene                                              [Page 54]
+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.
-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.
-. The server checks to see if the token following the mark is
+In the Symbolics implementation, the user side disestablishes data
-          USER-RESYNC-DUMMY.  This rare situation occurs if the user
+connections that have not been used for a long time, such as twenty
-          aborts during the course of the resynchronization itself.
+minutes or so.
-          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.
-. If the token following the mark is not USER-RESYNC-DUMMY
+For more information about data connections:  See the section "NFILE
-          (this is the expected circumstance), the server should have
+Control and Data Connections", section 4.
-          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.
+== NFILE RESYNCHRONIZATION PROCEDURE ==
-              b. The server declares the control connection safe (at
+Ordinarily, the user side sends NFILE commands to the server side
-                  the token list level).
+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.
-              c. The server sends the unique data token to the user
+First, if the server side aborts while sending or receiving data,
-                  side.
+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.
-. If the server detects something following the mark that was
+It is not unusual for the user side to abort file operations, either
-          neither USER-RESYNC-DUMMY nor a single data token, a
+commands or data transfer.  On a Symbolics computer, the user can do
-          protocol error has occurred.
+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.
-.2  NFILE Data Connection Resynchronization
+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 NFILE data channel resynchronization procedure is similar to the
+The resynchronization procedure is somewhat complex, but it fulfills
-  NFILE control connection resynchronization.  Both procedures are
+a genuine need.  For those interested, a brief design discussion is
-  based on a mark signalling the unsafe condition, then a second mark
+included as note <3>.
-  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:
+=== 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
+. The user side sends a mark over the control connection to
+      the server.
+. The user side sends the ASCII characters USER-RESYNC-DUMMY
+      (as a data token) to the server.
+. The user side sends a second mark to the server.
+. The user side declares the control connection safe (at the
+      token list level).
+. The user side generates and sends a unique data token to
+      the server.
+. 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
+. The server side detects a mark.  The server is thus alerted
+        that the control connection is unsafe, and that
+        resynchronization is in progress.
+. The server continues to read data coming from the user side
+        until it detects the second mark, and the token following
+        it.
+. 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.
-Greenberg & Keene                                              [Page 55]
+. 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.
-RFC 1037             NFILE - A File Access Protocol        December 1987
+             a. The server sends a mark to the user side.
+            b. The server declares the control connection safe (at
+              the token list level).
-      - User aborts occur during the file protocol operations that
+            c. The server sends the unique data token to the user
-        assign and deassign data channels.  This is the most common
+              side.
-        cause of data channels becoming unsafe.
-      - A server receives a CLOSE command (with abort-p supplied as
+. If the server detects something following the mark that was
-        Boolean truth) specifying an open file that has not finished
+        neither USER-RESYNC-DUMMY nor a single data token, a
-        transmitting data.  That is, file reading is aborted.
+        protocol error has occurred.
-      - The ABORT command is issued, causing data channels to be
+=== NFILE Data Connection Resynchronization ===
-        made unsafe.
-      - The FILEPOS command is issued, causing the input data
+The NFILE data channel resynchronization procedure is similar to the
-        channel to become unsafe.
+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:
-  The resynchronization clears the data channel of unwanted data from
+    - User aborts occur during the file protocol operations that
-  aborted operations and puts the data channel in a known state.  The
+      assign and deassign data channels.  This is the most common
-  data channel resynchronization procedure is invoked when the user
+      cause of data channels becoming unsafe.
-  side gives the RESYNCHRONIZE-DATA-CHANNEL command over the control
-  connection.
-  The following policies can be used to improve response time, but are
+    - A server receives a CLOSE command (with abort-p supplied as
-  not required by the NFILE protocol:  The user side can initiate
+      Boolean truth) specifying an open file that has not finished
-  resynchronization only if it needs the data channel, having first
+      transmitting data.  That is, file reading is aborted.
-  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
+    - The ABORT command is issued, causing data channels to be
-  indicates which data channel should be resynchronized.  Data channels
+      made unsafe.
-  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.
+    - 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.
+INPUT DATA CHANNEL RESYNCHRONIZATION
+. 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.
+. 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.
+. The server side sends a mark over the data channel.
+. The server side sends the unique identifier token over the
+      data channel.
+. 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
+. 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.
+. The user side of the data channel sends a mark.
+. 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.
-Greenberg & Keene                                              [Page 56]
+. 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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+. The server side reads and discards the first mark and the
+      dummy identifier.
+. The user side sends a second mark.
-   INPUT DATA CHANNEL RESYNCHRONIZATION
+. The user side sends the unique identifier.
-. The user side gives the RESYNCHRONIZE-DATA-CHANNEL command
+. The server side recognizes the mark and the unique
-        on the control connection, with only one argument, the
+      identifier that follows, and the resynchronization is
-        handle of the data channel to be resynchronized.
-. The server side of the data channel generates a unique
+       complete.  The data channel is no longer in the unsafe
-        identifier, and sends that data token in its regular
+       state.
-        command response to the user side.
-. The server side sends a mark over the data channel.
-. The server side sends the unique identifier token over the
-        data channel.
-. 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
-. 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.
-. The user side of the data channel sends a mark.
-. 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.
-. 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.
-. The server side reads and discards the first mark and the
-        dummy identifier.
-. The user side sends a second mark.
-. The user side sends the unique identifier.
-. 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.
 .  NFILE ERRORS AND NOTIFICATIONS
-  NFILE recognizes two types of errors:  command response errors and
+NFILE recognizes two types of errors:  command response errors and
-  asynchronous errors.  In addition to errors, NFILE supports
+asynchronous errors.  In addition to errors, NFILE supports
-  notifications.
+notifications.
-  Command response errors:
+Command response errors:
-      - Signify an error that prevented the successful completion of
+    - Signify an error that prevented the successful completion of
-        the command; when such an error occurs, a command response
+      the command; when such an error occurs, a command response
-        error is sent instead of a normal command response.
+      error is sent instead of a normal command response.
-      - Occur frequently in normal operations
+    - Occur frequently in normal operations
-  Asynchronous errors:
+Asynchronous errors:
-      - Are not related to any specific command
+    - Are not related to any specific command
-      - Are associated with an erring data channel
+    - Are associated with an erring data channel
-      - Typically indicate a problem in the transfer, such as
+    - Typically indicate a problem in the transfer, such as
-        running out of disk space or allocation, or an unreadable
+      running out of disk space or allocation, or an unreadable
-        disk record
+      disk record
-      - Occur rarely in normal operations
+    - Occur rarely in normal operations
-  Notifications:
+Notifications:
-      - Are not associated with an error
+    - Are not associated with an error
-      - Are sent at the server's discretion
+    - Are sent at the server's discretion
-      - Provide general information, such as a warning that the
+    - Provide general information, such as a warning that the
-        system is going down
+      system is going down
 .1  Notifications From the NFILE Server
-  The NFILE server can send asynchronous notifications to the user side
+The NFILE server can send asynchronous notifications to the user side
-  over the control connection.  The text of the notification contains
+over the control connection.  The text of the notification contains
-  information of interest to the person using NFILE, such as a warning
+information of interest to the person using NFILE, such as a warning
-  that the server's operating system will be going down soon.
+that the server's operating system will be going down soon.
-  Notifications can come from the server side at any time that the
+Notifications can come from the server side at any time that the
-  server is not sending something else.
+server is not sending something else.
-  The format of NFILE notifications is:
-            (NOTIFICATION "" text)
-  The empty string "" takes the place of a transaction identifier.
+The format of NFILE notifications is:
-  Notifications are initiated by the server, and are not associated
-  with any transaction originated by the user side.n
+          (NOTIFICATION "" text)
+The empty string "" takes the place of a transaction identifier.
-Greenberg & Keene                                              [Page 58]
+Notifications are initiated by the server, and are not associated
+with any transaction originated by the user side.n
-RFC 1037            NFILE - A File Access Protocol        December 1987
 .2  NFILE Command Response Errors
-  When an error prevents the successful completion of an NFILE command,
+When an error prevents the successful completion of an NFILE command,
-  a command response error is sent instead of the normal command
+a command response error is sent instead of the normal command
-  response.  A normal command response indicates success; a command
+response.  A normal command response indicates success; a command
-  response error indicates failure of the 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.
+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.
-Greenberg & Keene                                              [Page 59]
+message is a string that is displayed to the human user of the
+protocol.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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.
 .3  NFILE Asynchronous Errors
-  When a data channel process, in either direction, encounters an error
+When a data channel process, in either direction, encounters an error
-  condition, the server sends an asynchronous error description. An
+condition, the server sends an asynchronous error description. An
-  asynchronous error description consists of a top-level token list.
+asynchronous error description consists of a top-level token list.
-  Typically, asynchronous errors indicate error conditions in the
+Typically, asynchronous errors indicate error conditions in the
-  transfer, such as running out of disk space or allocation, or a
+transfer, such as running out of disk space or allocation, or a
-  unreadable disk record.
+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,
+The format of asynchronous error descriptions is:
-  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
+      (ASYNC-ERROR handle three-letter-code error-vars message)
-  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
+ASYNC-ERROR is a keyword.  The handle argument identifies the erring
-  channel it was requested to close.  If an asynchronous error
+data channel.  The arguments three-letter-code, error-vars, and
-  description has been sent on the data channel, but not yet processed
+message are all required.  Their meanings are the same as in NFILE
-  by CONTINUE, the server side does not close the channel, but sends a
+command error responses: See the section "NFILE Command Response
-  command error response.  The same thing happens on a FINISH command
+Errors", section 10.2.
-  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.
+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.
-Greenberg & Keene                                              [Page 60]
+On any asynchronous error, either input or output, the data channel
+on the server side enters an "asynchronous error outstanding" state.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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.
 .4  NFILE Three-letter Error Codes
-  Usually the server's operating system provides some description of an
+Usually the server's operating system provides some description of an
-  error that occurs.  NFILE has a mechanism for conveying that
+error that occurs.  NFILE has a mechanism for conveying that
-  information to the user side.  Upon detecting an error, the NFILE
+information to the user side.  Upon detecting an error, the NFILE
-  server should characterize the error by choosing the three-letter
+server should characterize the error by choosing the three-letter
-  code that best describes the error.  The three-letter code is an
+code that best describes the error.  The three-letter code is an
-  argument in both the command response error and asynchronous error
+argument in both the command response error and asynchronous error
-  messages from the server to the user.
+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
+Each of the NFILE three-letter codes represents some system error.
-          because the user's access rights to it did not permit this
+The set of codes enables all operating systems to use one error-
-          type of access.
+reporting mechanism.  Some operating systems will never encounter
+certain of the error conditions.
-    BUG  File system bug.  This includes all protocol violations
+Some errors fit logically into two error codes.  For example, suppose
-          detected by the server, as well as by the host file system.
+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.
-    CCD  Cannot create directory.  An error occurred in attempting to
+This is the set of three-letter codes:
-          create a directory.
-    CDF   Cannot delete file.  The file system reported that it cannot
+   ACC  Access error.  This indicates a protection-violation error.
-          delete a file.
-    CCL   Cannot create link.  An error occurred in attempting to
+   ATD  Incorrect access to directory.  A directory could not be
-          create a link.
+        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.
-Greenberg & Keene                                              [Page 61]
+  CDF  Cannot delete file.  The file system reported that it cannot
+        delete a file.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+  CCL  Cannot create link.  An error occurred in attempting to
+        create a link.
+  CIR  Circular link.  An operation was attempted on a pathname that
+        designates a link that eventually links back to itself.
-    CIR   Circular link.  An operation was attempted on a pathname that
+   CRF  Cannot rename file.  An error occurred in attempting to
-          designates a link that eventually links back to itself.
+        rename a file.
-    CRF   Cannot rename file.  An error occurred in attempting to
+  CSP   Cannot set property.  An error occurred in attempting to
-          rename a file.
+        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.
-    CSP   Cannot set property.  An error occurred in attempting to
+   DAE  Directory already exists.  A directory could not be created
-          change the properties of a file.  This could mean that you
+        because a directory or file of this name already exists.
-          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
+   DAT  Data error.  The file system contains unreadable data.  This
-          because a directory or file of this name already exists.
+        could mean data errors detected by hardware or inconsistent
+        data inside the file system.
-    DAT   Data error.  The file system contains unreadable data.  This
+   DEV  Device not found.  The device of the file was not found or
-          could mean data errors detected by hardware or inconsistent
+        does not exist.
-          data inside the file system.
-    DEV   Device not found.  The device of the file was not found or
+   DND  "Do Not Delete" flag set.  An attempt was made to delete a
-          does not exist.
+        file that is marked by a "Do Not Delete" flag.
-    DND   "Do Not Delete" flag set.  An attempt was made to delete a
+   DNE  Directory not empty.  An invalid deletion of a nonempty
-          file that is marked by a "Do Not Delete" flag.
+        directory was attempted.
-    DNE   Directory not empty.  An invalid deletion of a nonempty
+  DNF   Directory not found.  The directory was not found or does not
-          directory was attempted.
+        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.
-    DNF   Directory not found.  The directory was not found or does not
+   EPC  Error pending on channel.  The server cannot close the
-          exist.  This refers specifically to the containing directory;
+        channel in attempting to close or finish the channel.
-          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
+   FAE  File already exists.  The file could not be created because a
-          channel in attempting to close or finish the channel.
+        file or directory of this name already exists.
-    FAE   File already exists.  The file could not be created because a
+  FNF   File not found.  The file was not found in the containing
-          file or directory of this name already exists.
+        directory.  The TOPS-20 and TENEX "no such file type" and "no
+        such file version" errors should also report this condition.
-    FNF   File not found.  The file was not found in the containing
+  FOO   File open for output.  Opening a file that was already opened
-          directory.  The TOPS-20 and TENEX "no such file type" and "no
+        for output was attempted.
-          such file version" errors should also report this condition.
-    FOO   File open for output.  Opening a file that was already opened
+   FOR  Filepos out of range.  Setting the file pointer past the
-          for output was attempted.
-    FOR  Filepos out of range.  Setting the file pointer past the
+        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.
-Greenberg & Keene                                              [Page 62]
+  IBS    Invalid byte size.  The value of the "byte size" option was
+        not valid.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+  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.
-          end-of-file position or to a negative position was attempted.
+  IOL  Invalid operation for link.  The specified operation is
+        invalid for links, and this pathname is the name of a link.
-    FTB   File too big.  File is larger than the maximum file size
+   IP?  Invalid password.  The specified password was invalid.
-          supported by the file system.
-    HNA    Host not available The file server or file system is
+  IPS  Invalid pathname syntax.  This includes all invalid pathname
-          intentionally denying service to user.  This does not mean
+        syntax errors.
-          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
+  IPV  Invalid property value.  The new value provided for the
-          not valid.
+        property is invalid.
-    ICO   Inconsistent options.  Some of the options given in this
+   IWC  Invalid wildcard.  The pathname is not a valid wildcard
-          operation are inconsistent with others.
+        pathname.
-    IOD   Invalid operation for directory.  The specified operation is
+   LCK  File locked.  The file is locked.  It cannot be accessed,
-          invalid for directories, and the given pathname specifies a
+        possibly because it is in use by some other process.
-          directory, in directory pathname as file format.
-    IOL   Invalid operation for link.  The specified operation is
+   LIP  Login problems.  A problem was encountered while trying to
-          invalid for links, and this pathname is the name of a link.
+        log in to the file system.
-    IP?   Invalid password.  The specified password was invalid.
+   MSC  Miscellaneous problems.
-    IPS   Invalid pathname syntax.  This includes all invalid pathname
+   NAV  Not available.  The file or device exists but is not
-          syntax errors.
+        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.
-    IPV   Invalid property value.  The new value provided for the
+   NER  Not enough resources.  For example, a system limit on the
-          property is invalid.
+        number of open files or network connections has been reached.
-    IWC   Invalid wildcard.  The pathname is not a valid wildcard
+   NET  Network problem.  The file server had some sort of trouble
-          pathname.
+        trying to create a new data connection, or perform some other
+        network operation, and was unable to do so.
-    LCK   File locked.  The file is locked.  It cannot be accessed,
+   NFS  No file system.  The file system was not available.  For
-          possibly because it is in use by some other process.
+        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.
-    LIP   Login problems.  A problem was encountered while trying to
+   NLI  Not logged in.  A file operation was attempted before logging
-          log in to the file system.
+        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.
-    MSC   Miscellaneous problems.
+   NMR  No more room.  The file system is out of room.  This can mean
+        any of several things:
-    NAV  Not available.  The file or device exists but is not
+                  - The entire file system is full.
-          available.  Typically, the disk pack is not mounted on a
+                  - The particular volume involved is full.
-          drive, the drive is broken, or the like.  Operator
+                  - The particular directory involved is full.
-          intervention is probably required to fix the problem, but
+                  - The user's allocated quota has been exceeded.
-          retrying the operation is likely to succeed after the problem
-          is solved.
+  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.
-Greenberg & Keene                                              [Page 63]
+  UKC  Unknown operation. An unsupported file system operation was
+        attempted, or an unsupported command was attempted.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+  UKP  Unknown property.  The property is unknown.
+  UNK  Unknown user.  The specified user name is unknown to this
+        host.
-    NER   Not enough resources.  For example, a system limit on the
+   UUO  Unimplemented option.  An option to a command is not
-          number of open files or network connections has been reached.
+        implemented.
-    NET   Network problem.  The file server had some sort of trouble
+   WKF  Wrong kind of file.  This includes errors in which an invalid
-          trying to create a new data connection, or perform some other
+        operation for a file, directory, or link was attempted.
-          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
+  WNA  Wildcard not allowed.
 .  TOKEN LIST TRANSPORT LAYER
-  PURPOSE:  The Token List Transport Layer is a protocol that
+PURPOSE:  The Token List Transport Layer is a protocol that
-  facilitates the transmission of simple structured data, such as
+facilitates the transmission of simple structured data, such as
-  lists.
+lists.
 .1  Introduction to the Token List Transport Layer
-  The Token List Transport Layer is a general-purpose protocol.  The
+The Token List Transport Layer is a general-purpose protocol.  The
-  Token List Transport Layer sends "tokens" through its underlying
+Token List Transport Layer sends "tokens" through its underlying
-  stream.  Each token usually represents a simple quantity, such as a
+stream.  Each token usually represents a simple quantity, such as a
-  string or integer.
+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
+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
-Greenberg & Keene                                              [Page 65]
+  Example
+  of use:      NFILE data channels        NFILE control
+                                            connection
-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
-  NFILE uses the the Token List Transport Layer, and provides an
+stream.  File data is sent across each data channel in a token list
-  excellent example of its usefulness.  The NFILE commands and command
+data stream.
-  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.
 .2  Token List Stream
@@ Line 3,655: / Line 3,014: @@
 .2.1  Types of Tokens and Token Lists
-  All numbers in the token list documentation are represented in
+All numbers in the token list documentation are represented in
-  decimal notation.  Bytes are 8 bits long.
+decimal notation.  Bytes are 8 bits long.
-  TYPES OF TOKENS
+TYPES OF TOKENS
-  Tokens are of the following types:
+Tokens are of the following types:
 . Atomic tokens.
-              Atomic tokens are of the following subtypes:
+            Atomic tokens are of the following subtypes:
-              - Data tokens.  A data token consists of a sequence of
+          - Data tokens.  A data token consists of a sequence of
-                bytes with an effectively infinite maximum length.  In
+            bytes with an effectively infinite maximum length.  In
-                some contexts a data token represents a string; in
+            some contexts a data token represents a string; in
-                other contexts, a data token is other arbitrary data.
+            other contexts, a data token is other arbitrary data.
-                Each data token is preceded in the token list stream
+            Each data token is preceded in the token list stream
-                by a representation of its length in bytes.
+            by a representation of its length in bytes.
-                Data tokens that are under 200 bytes long are preceded
+            Data tokens that are under 200 bytes long are preceded
-                by one byte containing their length in bytes.  That
+            by one byte containing their length in bytes.  That
-                is, a data token of 34 bytes is preceded by one byte
+            is, a data token of 34 bytes is preceded by one byte
-                of value 34.
+            of value 34.
-                Data tokens 200 bytes or over are preceded by the byte
+            Data tokens 200 bytes or over are preceded by the byte
-                known as PUNCTUATION-LONG, of value 201.  After the
+            known as PUNCTUATION-LONG, of value 201.  After the
 comes a four-byte-long number (least significant
-                byte first) containing the length of the data token
+            byte first) containing the length of the data token
-                that follows.
+            that follows.
-              - Numeric tokens.  A sequence of bytes that represent
+          - Numeric tokens.  A sequence of bytes that represent
-                and encode a nonnegative binary integer.  The largest
+            and encode a nonnegative binary integer.  The largest
-                valid integer is 2^63 - 1.
+            valid integer is 2^63 - 1.
-                Numeric tokens are either short integers (less than
+            Numeric tokens are either short integers (less than
 ) or long integers (greater than or equal to 256).
-                Short integers are preceded by the byte known as
+            Short integers are preceded by the byte known as
-                PUNCTUATION-SHORT-INTEGER, of value 206.
+            PUNCTUATION-SHORT-INTEGER, of value 206.
+            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.
-Greenberg & Keene                                              [Page 66]
+            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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+          - Boolean truth.  A special token that represents the
+            Boolean truth value.  This token is known as
+            BOOLEAN-TRUTH, of value 209 <4>.
+. Control tokens.
-                Long integers are begun by PUNCTUATION-LONG-INTEGER,
+The token list stream supports four control tokens to delimit token
-                of value 207.  One byte follows, containing the length
+lists, and one padding token.
-                (in bytes) of the long integer.  The integer itself is
-                next, least significant byte first.
-              - Keyword tokens.  A sequence of bytes that represent
+            TOP-LEVEL-LIST-BEGIN  202  This control token
-                and encode a named identifier of the implemented
+                                        appears at the start of
-                protocol.  Keyword tokens are used by the client
+                                        each top-level token list.
-                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
+            TOP-LEVEL-LIST-END    203  This control token
-                PUNCTUATION-KEYWORD, of value 208.  The data token
+                                        appears at the end of
-                following PUNCTUATION-KEYWORD represents the name of
+                                        each top-level token list.
-                the keyword as a string.  The characters are in
+            LIST-BEGIN            204  This control token
-                upper-case standard ASCII.
+                                        appears at the start of
+                                        each embedded token list.
-              - Boolean truth.  A special token that represents the
+            LIST-END              205  This control token
-                Boolean truth value.  This token is known as
+                                        appears at the end of
-                BOOLEAN-TRUTH, of value 209 <4>.
+                                        each embedded token list.
-. Control tokens.
+            PUNCTUATION-PAD      200  This padding token should
+                                        be ignored by the token
+                                        list stream.  It can be
+                                        sent to fill buffers.
-  The token list stream supports four control tokens to delimit token
+TOKEN LISTS
-  lists, and one padding token.
-              TOP-LEVEL-LIST-BEGIN  202  This control token
+A token list consists of a sequence of atomic tokens or token lists.
-                                          appears at the start of
+Token lists are begun and ended by control tokens that delimit the
-                                          each top-level token list.
+token lists.  There are three types of token lists:
-              TOP-LEVEL-LIST-END    203  This control token
+. Top-level token lists.
-                                          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
+        Top-level token lists begin with TOP-LEVEL-LIST-BEGIN and
-                                          appears at the end of
+        end with TOP-LEVEL-LIST-END.  Top-level token lists are not
-                                          each embedded token list.
+        contained in other lists.
-              PUNCTUATION-PAD       200  This padding token should
+. Embedded token lists.
-                                          be ignored by the token
-                                          list stream.  It can be
-                                          sent to fill buffers.
+        These token lists occur inside other token lists.  They
+        begin with LIST-BEGIN and end with LIST-END.
+. 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
-Greenberg & Keene                                              [Page 67]
+        LIST-BEGIN followed immediately by a LIST-END.  A top-level
+        empty token list is composed of TOP-LEVEL-LIST-BEGIN
-RFC 1037            NFILE - A File Access Protocol        December 1987
+        followed immediately by TOP-LEVEL-LIST-END.
-  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:
-. 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.
-. Embedded token lists.
-            These token lists occur inside other token lists.  They
-            begin with LIST-BEGIN and end with LIST-END.
-. 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.
 .2.2  Token List Stream Example
-  This section contains an example of some data that can appear on a
+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
+token list stream.  The example is a top-level token list encoding an
-  NFILE DELETE command.
+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:
-. TOP-LEVEL-LIST-BEGIN
-. The keyword token whose name is DELETE
-. The data token containing the characters:  t105
-. LIST-BEGIN
-. LIST-END
-Greenberg & Keene                                              [Page 68]
-RFC 1037            NFILE - A File Access Protocol        December 1987
-. The data token containing the characters:  /usr/max/temp
+The DELETE command is composed of the following pieces:  a TOP-
-. TOP-LEVEL-LIST-END
+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.
-  Now, let's translate each piece of the command into the bytes that
+All numbers in this section are expressed in decimal notation.
-  are transmitted through the token list stream.
-. TOP-LEVEL-LIST-BEGIN
+The pieces of the command are displayed here in order:
-    represents TOP-LEVEL-LIST-BEGIN
+. TOP-LEVEL-LIST-BEGIN
+. The keyword token whose name is DELETE
+. The data token containing the characters:  t105
+. LIST-BEGIN
+. LIST-END
-. The keyword token whose name is DELETE.
+. The data token containing the characters:  /usr/max/temp
+. TOP-LEVEL-LIST-END
-          A keyword token is introduced by PUNCTUATION-KEYWORD, which
+Now, let's translate each piece of the command into the bytes that
-          is represented in the token list stream as the byte 208.
+are transmitted through the token list stream.
-          A data token follows, containing the string "DELETE".  A
+. TOP-LEVEL-LIST-BEGIN
-          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
+    represents TOP-LEVEL-LIST-BEGIN
-          set representation of each character in the string DELETE:
-    represents PUNCTUATION-KEYWORD
+. The keyword token whose name is DELETE.
-    represents the length of this data token
-    represents "D"
-    represents "E"
-    represents "L"
-    represents "E"
-    represents "T"
-    represents "E"
-. The data token containing the characters:  t105
+         A keyword token is introduced by PUNCTUATION-KEYWORD, which
+        is represented in the token list stream as the byte 208.
-          This data token is begun by its length in bytes (4), and
+        A data token follows, containing the string "DELETE".  A
-          continues with the NFILE character set representation of
+        data token under 200 bytes long is introduced by one byte
-          each character in the string:
+        containing its length in bytes.  The length of this data
+        token is 6 bytes.
-    represents the length of this data token
+        The data token continues with the standard ASCII character
-    represents "t"
+        set representation of each character in the string DELETE:
-    represents "1"
-    represents "0"
-    represents "5"
-. LIST-BEGIN
+    represents PUNCTUATION-KEYWORD
+    represents the length of this data token
+    represents "D"
+    represents "E"
+    represents "L"
+    represents "E"
+    represents "T"
+    represents "E"
-    represents LIST-BEGIN
+. 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:
+    represents the length of this data token
+    represents "t"
+    represents "1"
+    represents "0"
+    represents "5"
+. LIST-BEGIN
-Greenberg & Keene                                              [Page 69]
+    represents LIST-BEGIN
-RFC 1037            NFILE - A File Access Protocol        December 1987
+. LIST-END
+    represents LIST-END
-. LIST-END
+. The data token containing the characters:  /usr/max/temp
-    represents LIST-END
+    represents length of this data token
+    represents "/"
+    represents "u"
+    represents "s"
+    represents "r"
+    represents "/"
+    represents "m"
+    represents "a"
+    represents "x"
+    represents "/"
+    represents "t"
+    represents "e"
+    represents "m"
+    represents "p"
-. The data token containing the characters:  /usr/max/temp
+. TOP-LEVEL-LIST-END
-    represents length of this data token
+    represents TOP-LEVEL-LIST-END
-    represents "/"
-    represents "u"
-    represents "s"
-    represents "r"
-    represents "/"
-    represents "m"
-    represents "a"
-    represents "x"
-    represents "/"
-    represents "t"
-    represents "e"
-    represents "m"
-    represents "p"
-. TOP-LEVEL-LIST-END
-    represents TOP-LEVEL-LIST-END
 .2.3  Mapping of Lisp Objects to Token List Stream Representation
-  The Symbolics interface to the token list stream sends Lisp objects
+The Symbolics interface to the token list stream sends Lisp objects
-  through the underlying Byte Stream with Mark and produces Lisp
+through the underlying Byte Stream with Mark and produces Lisp
-  objects on the other end.  Not all Lisp objects can be sent in this
+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.
+way.  For example, compound objects other than lists are not handled.
-  An appropriate analogy is the sending and reconstruction of list
+An appropriate analogy is the sending and reconstruction of list
-  structure via printed representation.  These are the types of objects
+structure via printed representation.  These are the types of objects
-  that can be sent, and their representations:
+that can be sent, and their representations:
-        - Lisp strings are represented as data tokens in the NFILE
+    - Lisp strings are represented as data tokens in the NFILE
-          character set.  Only 8-bit strings can be sent <5>.
+      character set.  Only 8-bit strings can be sent <5>.
-        - Keyword symbols are represented as keyword tokens.  Although
+    - Keyword symbols are represented as keyword tokens.  Although
-          identifiable and reconstructable as keyword symbols, only
+      identifiable and reconstructable as keyword symbols, only
-          their names are sent.  Any properties, bindings, and the
+      their names are sent.  Any properties, bindings, and the
-          like are not sent.
+      like are not sent.
-        - T is represented as BOOLEAN-TRUTH.
+    - T is represented as BOOLEAN-TRUTH.
-        - NIL is represented as the empty token list.
+    - NIL is represented as the empty token list.
-        - Lists are represented as token lists.  Circular lists cannot
+    - Lists are represented as token lists.  Circular lists cannot
+      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.
-Greenberg & Keene                                              [Page 70]
+    - Integers are represented as numeric tokens.  Only
+      nonnegative integers less than 2^63 can be sent.
-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.
 .2.4  Aborting and the Token List Stream
-  A token list stream accrues the benefits of the abort management
+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
+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
+to fully realize this benefit, some simple rules must be obeyed by
-  any implementation of the token list stream.
+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".
+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.
-Greenberg & Keene                                              [Page 71]
+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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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".
-  Depending on the client protocol, the receipt of a mark might cause
+Depending on the client protocol, the receipt of a mark might cause
-  the reading side to read for further marks.  NFILE implements the
+the reading side to read for further marks.  NFILE implements the
-  resynchronization of token list streams, and serves as a useful
+resynchronization of token list streams, and serves as a useful
-  example: See the section "NFILE Control Connection
+example: See the section "NFILE Control Connection
-  Resynchronization", section 9.1.
+Resynchronization", section 9.1.
-  The Symbolics implementation provides the two mark-handling
+The Symbolics implementation provides the two mark-handling
-  primitives in this way:
+primitives in this way:
+. 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).
-. Send token (or list) preceded by a mark.  When the stream
+. Read through to a mark and read the token (or list)
-        is in the unsafe state (on the output side), this is the
+      following the mark.  When the stream is in the unsafe state
-        only permitted output operation (other than closing).
+      (on the input side), this is the only permitted input
+      operation (other than closing).
-. 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).
 .3  Token List Data Stream
-  The token list data stream is a facility to transmit stream data
+The token list data stream is a facility to transmit stream data
-  through a token list stream.  The token list data stream imposes the
+through a token list stream.  The token list data stream imposes the
-  following protocol on the data transmitted:
+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.
+        - Data is sent in the format of loose data tokens, not
-  It is expected (but not required) that its typical mode of use is to
+          contained in token lists.
-  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
+        - 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.
-Greenberg & Keene                                              [Page 72]
+        - Boundaries between data tokens are not signification.
+          The data is considered to be a continuous stream, with
+          the possible exception of marks.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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
-  the token list stream documentation:  See the section "Types of
+the token list stream documentation:  See the section "Types of
-  Tokens and Token Lists", section 11.2.1.
+Tokens and Token Lists", section 11.2.1.
-  The NFILE file protocol provides a good example of the use of token
+The NFILE file protocol provides a good example of the use of token
-  list data streams.  NFILE sends file data through token list data
+list data streams.  NFILE sends file data through token list data
-  streams; each NFILE data channel is a token list data stream.  Errors
+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
+such as disk errors during the reading of a file are conveyed as
-  token lists through the token list data stream.
+token lists through the token list data stream.
 .  BYTE STREAM WITH MARK
-  PURPOSE:  Byte Stream with Mark is a simple layer of protocol that
+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
+guarantees that an out-of-band signal can be transmitted in the case
-  of program interruption.  Byte Stream with Mark is designed to
+of program interruption.  Byte Stream with Mark is designed to
-  provide end-to-end stream consistency in the face of user program
+provide end-to-end stream consistency in the face of user program
-  aborts.
+aborts.
 .1  Discussion of Byte Stream with Mark
-  INTRODUCTION
+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
--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 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
+-bit bytes.  Byte Stream with Mark has been implemented to run on
+TCP and Chaos.  Marks are implemented differently on the two
+protocols.
-  BYTE STREAM WITH MARK ON CHAOSNET
+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.
-  A mark is recognized on Chaosnet by a packet bearing the opcode 201
+In the context of this document, "aborting" is defined as follows:
-  (octal).  There is no data in a mark packet, so the data portion of
+Aborting the current execution of a program means to halt that
-  the packet is ignored.  Byte Stream with Mark transmits all data in
+execution and to abandon it, never to complete it.  The data
-  packets bearing opcode 200 (octal).
+representing the state of the execution are irrevocably discarded.
-  If Byte Stream with Mark is implemented on another (non-Chaos) stream
+EXAMPLE OF USE
-  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
+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.
-  The purpose of Byte Stream with Mark is to guarantee that marks can
+BYTE STREAM WITH MARK ON CHAOSNET
-  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
+A mark is recognized on Chaosnet by a packet bearing the opcode 201
-  the integrity of the record boundaries.  A writer to the stream must
+(octal).  There is no data in a mark packet, so the data portion of
-  never output a byte count without that number of data bytes
+the packet is ignored.  Byte Stream with Mark transmits all data in
-  following.  Similarly, a reader of the stream, after reading a byte
+packets bearing opcode 200 (octal).
-  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
+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.
-  This subsection deals with maintaining record integrity on non-Chaos
+BYTE STREAM WITH MARK ON TCP:  RECORD MODE
-  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
+The purpose of Byte Stream with Mark is to guarantee that marks can
-  stream must guarantee data integrity.
+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.
-  The basic design of Byte Stream with Mark on TCP (and other transport
+Both the sending side and the receiving side must rigorously maintain
-  layers that do not implement packets natively) is to preserve record
+the integrity of the record boundaries.  A writer to the stream must
-  integrity by putting clearly demarcated, byte-counted records in the
+never output a byte count without that number of data bytes
-  natural records of the encapsulated stream.  Therefore, when the
+following.  Similarly, a reader of the stream, after reading a byte
-  outer stream requests a buffer's worth of file data from the
+count, has effectively contracted to read that many bytes from the
-  encapsulated stream, it expects to receive a buffer containing one
+encapsulated stream, regardless of whether those bytes are requested
-  entire, ntegral, record of that stream, complete with byte count.
+by the application layer.
-  Because of diverse network implementations on different operating
+MAINTAINING RECORD INTEGRITY
-  systems, the software that implements the encapsulated stream might
+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.
-Greenberg & Keene                                              [Page 74]
+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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+Because of diverse network implementations on different operating
+systems, the software that implements the encapsulated stream might
+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.
-  not be able to provide integral record buffers to the Byte Stream
+In this case, if the program reading from the Byte Stream with Mark
-  with Mark implementation.  For example, the writing stream could have
+aborts while reading data, the implementation of Byte Stream with
-  written records that are much longer than available buffers on the
+Mark must continue to read through the remaining buffers of the Byte
-  receiving system.  In this case, a request to read from the
+Stream with Mark record that has been subdivided in this fashion.
-  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
+The user side program will have determined that an abort has
-  aborts while reading data, the implementation of Byte Stream with
+occurred, and will request the Byte Stream with Mark to read up to
-  Mark must continue to read through the remaining buffers of the Byte
+and through the next mark.  The Byte Stream with Mark will have
-  Stream with Mark record that has been subdivided in this fashion.
+processed a fractional record, and must discard the remaining buffers
+of the record now being read.
-  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.
 .2  Byte Stream with Mark Abortable States
-  Byte Stream with Mark is designed to provide end-to-end stream
+Byte Stream with Mark is designed to provide end-to-end stream
-  consistency in the face of user program aborts.  This section
+consistency in the face of user program aborts.  This section
-  describes user program aborts, and how Byte Stream with Mark handles
+describes user program aborts, and how Byte Stream with Mark handles
-  them.  In the context of this document, "aborting" is defined as
+them.  In the context of this document, "aborting" is defined as
-  follows:  Aborting the current execution of a program means to halt
+follows:  Aborting the current execution of a program means to halt
-  that execution and to abandon it, never to complete it.  The data
+that execution and to abandon it, never to complete it.  The data
-  representing the state of the execution are irrevocably discarded.
+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
+USER PROGRAM ABORTS AND I/O STREAMS
-  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
+Aborting the execution of the code that manipulates I/O streams, in
-  occurs:
+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.
-. Abort occurs when the user program is not manipulating the
+Many operating systems solve this problem by manipulating a large
-            stream.
+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,
-            This case presents no problem.
+the Symbolics computer environment has no supervisor or executive
+program, and is thus vulnerable to aborts everywhere.
-. Abort occurs after a transmission has been partially sent,
+BYTE STREAM WITH MARK HANDLING OF USER PROGRAM ABORTS
-            at a packet or record boundary.
-            This implies that the datum that would indicate the
+Byte Stream with Mark is designed to be nearly impervious to the
-            successful complete sending of that transmission has been
+aborting of programs using it.  Its design is based on careful
-            not yet been sent.
+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.
-            The Byte Stream with Mark state is consistent, but the
+A "transmission" is a collection of user data sent by the application
-            application level state is not.  The application level must
+level through the Byte Stream with Mark whose end is well-defined,
-            determine that the execution of the code composing and
+once its start has been recognized.  For instance, the token list
-            sending its transmission was, in fact, aborted, and
+stream, when using Byte Stream with Mark, sends token lists.  When a
-            initiate resynchronization via marks.
+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 receiving side must be careful not to act upon a
+The following cases are possible states of the stream when an abort
-            transmission (that is, to perform any action or side
+occurs:
-            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.
+. Abort occurs when the user program is not manipulating the
+        stream.
+        This case presents no problem.
+. 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.
-Greenberg & Keene                                              [Page 76]
+        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.
-RFC 1037            NFILE - A File Access Protocol        December 1987
+        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.
+. Abort occurs during the sending or receiving of a record.
-. 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 is the most vulnerable state of the mechanism.  This
+        This case is handled by minimizing the extent of this
-            case does not occur on packet-oriented media; it is
+        window, and killing the connection when and if the
-            subsumed by the next case.
+        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.
-            This case is handled by minimizing the extent of this
+        For buffered streams, input and output waiting can be done
-            window, and killing the connection when and if the
+        in consistent states, thus minimizing the amount of time
-            situation is detected.  Depending on the operating system
+        manipulating the actual encapsulated stream.  For
-            involved, this window could be minimized by using
+        unbuffered streams, a lot of time can be spent in this
-            interrupt-disabling mechanisms, auxiliary processes or
+        window.  It is expected that unbuffered streams will be
-            tasks, or some other technique.
+        exceedingly uncommon.  Nevertheless, the implementation of
+        Byte Stream with Mark must detect this case.
-            For buffered streams, input and output waiting can be done
+. Abort occurs during the sending or receiving of fundamental
-            in consistent states, thus minimizing the amount of time
+        units of the lowest-level underlying stream (packets,
-            manipulating the actual encapsulated stream.  For
+        buffers, or bytes).
-            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.
-. Abort occurs during the sending or receiving of fundamental
+         This case is usually handled by inhibiting interrupts, or
-            units of the lowest-level underlying stream (packets,
+        other forms of masking, in the code implementing the
-            buffers, or bytes).
+        encapsulated stream, since no waiting is possible at
+        unexpected times.
-            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.
 .  POSSIBLE FUTURE EXTENSIONS
-  NFILE was designed to be extended as the needs of its clients grow,
+NFILE was designed to be extended as the needs of its clients grow,
-  or as new clients with different needs appear.  Currently it meets
+or as new clients with different needs appear.  Currently it meets
-  the needs of the Symbolics Genera 7.0 operating system, although its
+the needs of the Symbolics Genera 7.0 operating system, although its
-  design is intentionally general.  If users of other operating systems
+design is intentionally general.  If users of other operating systems
-  identify new features that would be useful, they could be added to
+identify new features that would be useful, they could be added to
-  NFILE.  This section illustrates some areas areas where the design of
+NFILE.  This section illustrates some areas areas where the design of
-  NFILE intentionally accommodates extensions.
+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
-                  377
-            x in 200..207        x
-            x in 210..211        x - 200
-                  015
-            x in 213..214        x - 200
-                  012
-            x in 216..376        x
-                  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
-                  215
-            x in 013..014        x + 200
-                  212
-            x in 016..176        x
-                  377
-            x in 200..207        x
-            x in 210..215        x - 200
-            x in 216..376        x
-                  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
-            x in 014..015        177 x
-            x in 016..176        x
-                  177 177
-            x in 200..207        177 x - 200
-            x in 210..212        x - 200
-                  177 013
-                  014
-                  015 012
-            x in 216..376        177 x - 200
-                  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
-                  214
-012              215
-not-012          115
-            x in 016..176        x
-x in 000..007    x + 200
-x in 010..012    x
-013              213
-x in 014..015    x
-x in 016..176    x + 200
-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>
-              015 012
-            x in 216..376    <x - 200>
-              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
-              214
-012          215
-not-012      115
-            x in <016..176>  x
-              177
+      - 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
+        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.
+                            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".
+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
+                  377
+        x in 200..207        x
+        x in 210..211        x - 200
+                  015
+        x in 213..214        x - 200
+                  012
+        x in 216..376        x
+                  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
+                  215
+        x in 013..014        x + 200
+                  212
+        x in 016..176        x
+                  377
+        x in 200..207        x
+        x in 210..215        x - 200
+        x in 216..376        x
+                  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.
+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)
-Greenberg & Keene                                              [Page 85]
+        x in 000..007        x
+        x in 010..012        177 x
+                  013
+        x in 014..015        177 x
+        x in 016..176        x
+                  177 177
+        x in 200..207        177 x - 200
+        x in 210..212        x - 200
+                  177 013
+                  014
+                  015 012
+        x in 216..376        177 x - 200
+                  no corresponding code
-RFC 1037            NFILE - A File Access Protocol        December 1987
+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
-                                  NOTES
+  TABLE 4.  TRANSLATIONS FROM PDP-10 CHARACTERS TO NFILE CHARACTERS
-. NFILE's requirement for using the NFILE character set is
+        PDP-10 character     NFILE character
-      recognized as a drawback for non-Symbolics machines.  A useful
-      extension to NFILE would be a provision to make the character set
-      negotiable.
-. Implementation note:  Care must be taken that the freeing is done
+        x in 000..007        x
-      before the control connection is allowed to process another
+        x in 010..012        x + 200
-      command, or else the control connection may find the data channel
+                  013
-      to be falsely indicated as being in use.
+                  214
+012              215
+not-012          115
+        x in 016..176        x
+x in 000..007    x + 200
+x in 010..012    x
+013              213
+x in 014..015    x
+x in 016..176    x + 200
+177              177
-. The Symbolics operating system has the policy that whenever the
+of a carriage that doesn't go to a new line, so if there is one in a
-      user side is waiting for the server side, a user abort can occur.
+server file, it must be translated to something else.  When
-      This user side waiting can occur in any context, such awaiting a
+converting ASCII characters to NFILE characters, an 015 followed by
-      response, waiting in the middle of reading network input, or
+an 012 therefore turns into a 215.  A stray CR is arbitrarily
-      waiting in the middle of transmitting network output.  Thus there
+translated into a single M (115).
-      are no "hung" states.
-. Note that the Token List Transport Layer supplies a special token
+                            APPENDIX B
-      to indicate Boolean truth, but no corresponding token to indicate
+                        RAW TRANSLATION MODE
-      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.
-. No so-called "fat strings" can be sent.
+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.
+                            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>
+              015 012
+        x in 216..376    <x - 200>
+              no corresponding code
+      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
+              214
+012          215
+not-012      115
+        x in <016..176>  x
+              177
+                                NOTES
+. 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.
+. 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.
+. 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.
+. 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.
-Greenberg & Keene                                              [Page 86]
+. No so-called "fat strings" can be sent.

Anonymous

Search

Difference between revisions of "RFC1037"

Latest revision as of 11:55, 29 November 2020

Contents

INTRODUCTION

NFILE PROTOCOL LAYERING

OVERVIEW OF AN NFILE SESSION

NFILE CONTROL AND DATA CONNECTIONS

NFILE FILE OPENING MODES

NFILE CHARACTER SET

CONVENTIONS USED IN THIS DOCUMENT

Mapping Data Types Into Token List Representation

Format of NFILE Commands and Responses

Data Channel Handles and Direct File Identifiers

Syntax of File and Directory Pathname Arguments

Format of NFILE File Property/Value Pairs

NFILE COMMANDS

ABORT Command

CHANGE-PROPERTIES Command

CLOSE Command

COMPLETE Command

CONTINUE Command

CREATE-DIRECTORY Command

CREATE-LINK Command

DATA-CONNECTION Command

DELETE Command

NFILE RESYNCHRONIZATION PROCEDURE

NFILE Control Connection Resynchronization

NFILE Data Connection Resynchronization

Navigation

Wiki tools

Page tools