tech-invite   World Map
3GPP     Specs     Glossaries     UICC       IETF     RFCs     Groups     SIP     ABNFs       T+       Search     Home

RFC 1037

Historic
Pages: 86
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: ~proto

NFILE - a file access protocol

Part 1 of 3, p. 1 to 28
None       Next RFC Part

 


Top       Page 1 
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

Top       Page 2 
       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

Top       Page 3 
       11.3  Token List Data Stream                                   72

   12.  BYTE STREAM WITH MARK                                         73

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

   13.  POSSIBLE FUTURE EXTENSIONS                                    77

   APPENDIX A.  NORMAL TRANSLATION MODE                               79

   APPENDIX B.  RAW TRANSLATION MODE                                  83

   APPENDIX C.  SUPER-IMAGE TRANSLATION MODE                          84

   NOTES                                                              86

LIST OF TABLES

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

1.  INTRODUCTION

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

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

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

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

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

   NFILE supports file transfer of binary or character files.

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

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

2.  NFILE PROTOCOL LAYERING

   NFILE is a layered file protocol.  The layers are:

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

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

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

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

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

3.  OVERVIEW OF AN NFILE SESSION

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

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

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

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

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

Top       Page 6 
4.  NFILE CONTROL AND DATA CONNECTIONS

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

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

   THE CONTROL CONNECTION

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

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

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

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

Top       Page 7 
   DATA CONNECTIONS

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

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

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

5.  NFILE FILE OPENING MODES

   The NFILE OPEN command opens a file for reading, writing, or "direct
   access" at the server host.  That means, in general, asking the host
   file system to access the file and obtaining a file number, pointer,
   or other quantity for subsequent rapid access to the file; this is
   called an "opening".  The term "opening" translates to a file stream
   in Symbolics terminology, a JFN in TOPS-20 terminology, and a file
   descriptor in UNIX terminology.  An opening usually keeps track of
   how many bytes have been read or written, and other bookkeeping
   information.

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

   DATA STREAM MODE:

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

Top       Page 8 
   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.

Top       Page 9 
6.  NFILE CHARACTER SET

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

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

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

   The details of each translation mode are given in Appendices:

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

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

Top       Page 10 
7.  CONVENTIONS USED IN THIS DOCUMENT

7.1  Mapping Data Types Into Token List Representation

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

    Conceptual Type     Token List Representation

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

    Keyword             A keyword token

    Keyword list        A token list of keyword tokens

    Integer             A numeric data token

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

    Boolean Truth       The token known as BOOLEAN-TRUTH.

    Boolean False       The empty token list.

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

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

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

7.2  Format of NFILE Commands and Responses

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

Top       Page 11 
   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)

Top       Page 12 
    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).

Top       Page 13 
7.3  Data Channel Handles and Direct File Identifiers

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


   Data Stream

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

   Direct Access

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

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

7.4  Syntax of File and Directory Pathname Arguments

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

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

   Server Host     Example of File Pathname

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

      UNIX            /usr/max/life.c

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

      VMS             MACD:[MAX]LIFE.FOR;3

      Symbolics LMFS  >max>life.lisp.newest

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

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

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

   Server Host     Example of Directory Pathname

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

      UNIX            /usr/max/

      TOPS-20         <max>

      VMS             MACD:[MAX]

      Symbolics LMFS  >max>hacks>

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

7.5  Format of NFILE File Property/Value Pairs

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

Top       Page 15 
   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

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

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

8.  NFILE COMMANDS

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

8.1  ABORT Command

   Command:  (ABORT tid input-handle)

   Response: (ABORT tid)

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

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

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

8.2  CHANGE-PROPERTIES Command

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

   Response: (CHANGE-PROPERTIES tid)

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

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

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

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

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

8.3  CLOSE Command

   Command:  (CLOSE tid handle abort-p)

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

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

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

Top       Page 18 
   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.

Top       Page 19 
8.4  COMPLETE Command

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

   Response: (COMPLETE tid new-string success)

   COMPLETE performs file pathname completion.

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

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

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

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

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

   Value               Meaning

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

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

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

   Empty token list    Failure due to one of these reasons:

                       The file is on a file system that does not

Top       Page 20 
                       support completion.  new-string is supplied as
                       the unchanged string.

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

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

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

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

8.5  CONTINUE Command

   Command:  (CONTINUE tid handle)

   Response: (CONTINUE tid)

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

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

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

Top       Page 21 
8.6  CREATE-DIRECTORY Command

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

   Response: (CREATE-DIRECTORY tid dir-truename)

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

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

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

8.7  CREATE-LINK Command

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

   Response: (CREATE-LINK tid link-truename)

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

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

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

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

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

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

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

8.8  DATA-CONNECTION Command

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

   Response: (DATA-CONNECTION tid connection-identifier)

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

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

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

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

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

8.9  DELETE Command

   Command:  (DELETE tid handle pathname)

   Response: (DELETE tid)

   DELETE deletes a file on the remote file system.

   Either a handle or a pathname must be supplied, but not both.  If
   given, the handle must be a data channel handle for a data stream
   opening, or a direct file identifier for a direct access opening.
   pathname is a string in the full pathname syntax of the server host.
   See the section "Syntax of File and Directory Pathname Arguments",
   section 7.4.

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

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

8.10  DIRECT-OUTPUT Command

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

   Response: (DIRECT-OUTPUT tid)

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

Top       Page 24 
   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.

Top       Page 25 
   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.

Top       Page 26 
   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

Top       Page 27 
             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.

Top       Page 28 
   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.



(page 28 continued on part 2)

Next RFC Part