rfc1037.txt

RFC 的详细文档！

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

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

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

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










Greenberg & Keene                                               [Page 6]

RFC 1037             NFILE - A File Access Protocol        December 1987


   DATA CONNECTIONS

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

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

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

5.  NFILE FILE OPENING MODES

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

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

   DATA STREAM MODE:

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





Greenberg & Keene                                               [Page 7]

RFC 1037             NFILE - A File Access Protocol        December 1987


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

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

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

   DIRECT ACCESS MODE:

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

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

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












Greenberg & Keene                                               [Page 8]

RFC 1037             NFILE - A File Access Protocol        December 1987


6.  NFILE CHARACTER SET

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

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

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

   The details of each translation mode are given in Appendices:

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

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






Greenberg & Keene                                               [Page 9]

RFC 1037             NFILE - A File Access Protocol        December 1987


7.  CONVENTIONS USED IN THIS DOCUMENT

7.1  Mapping Data Types Into Token List Representation

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

    Conceptual Type     Token List Representation

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

    Keyword             A keyword token

    Keyword list        A token list of keyword tokens

    Integer             A numeric data token

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

    Boolean Truth       The token known as BOOLEAN-TRUTH.

    Boolean False       The empty token list.

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

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

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

7.2  Format of NFILE Commands and Responses

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



Greenberg & Keene                                              [Page 10]

RFC 1037             NFILE - A File Access Protocol        December 1987


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

   Response: (DATA-CONNECTION tid connection-identifier)

   The command descriptions follow these conventions:

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

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

    2. NFILE command names are keywords.

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

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

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

   OPTIONAL ARGUMENTS

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

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

         (DELETE tid handle pathname)