summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc1037.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc1037.txt')
-rw-r--r--doc/rfc/rfc1037.txt4819
1 files changed, 4819 insertions, 0 deletions
diff --git a/doc/rfc/rfc1037.txt b/doc/rfc/rfc1037.txt
new file mode 100644
index 0000000..12e6f64
--- /dev/null
+++ b/doc/rfc/rfc1037.txt
@@ -0,0 +1,4819 @@
+
+
+
+
+
+
+Network Working Group B. Greenberg
+Request for Comments: 1037 S. Keene
+ December 1987
+
+
+ NFILE - A File Access Protocol
+
+
+STATUS OF THIS MEMO
+
+ This document includes a specification of the NFILE file access
+ protocol and its underlying levels of protocol, the Token List
+ Transport Layer and Byte Stream with Mark. The goal of this
+ specification is to promote discussion of the ideas described here,
+ and to encourage designers of future file protocols to take advantage
+ of these ideas. A secondary goal is to make the specification
+ available to sites that might benefit from implementing NFILE. The
+ distribution of this document is unlimited.
+
+ TABLE OF CONTENTS
+ Page
+ 1. INTRODUCTION 3
+
+ 2. NFILE PROTOCOL LAYERING 4
+
+ 3. OVERVIEW OF AN NFILE SESSION 5
+
+ 4. NFILE CONTROL AND DATA CONNECTIONS 6
+
+ 5. NFILE FILE OPENING MODES 7
+
+ 6. NFILE CHARACTER SET 9
+
+ 7. CONVENTIONS USED IN THIS DOCUMENT 10
+
+ 7.1 Mapping Data Types Into Token List Representation 10
+ 7.2 Format of NFILE Commands and Responses 10
+ 7.3 Data Channel Handles and Direct File Identifiers 13
+ 7.4 Syntax of File and Directory Pathname Arguments 13
+ 7.5 Format of NFILE File Property/Value Pairs 14
+
+ 8. NFILE COMMANDS 16
+
+ 8.1 ABORT Command 16
+ 8.2 CHANGE-PROPERTIES Command 16
+ 8.3 CLOSE Command 17
+ 8.4 COMPLETE Command 19
+ 8.5 CONTINUE Command 20
+
+
+
+Greenberg & Keene [Page 1]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ 8.6 CREATE-DIRECTORY Command 21
+ 8.7 CREATE-LINK Command 21
+ 8.8 DATA-CONNECTION Command 22
+ 8.9 DELETE Command 23
+ 8.10 DIRECT-OUTPUT Command 23
+ 8.11 DIRECTORY Command 24
+ 8.11.1 NFILE DIRECTORY Data Format 26
+ 8.12 DISABLE-CAPABILITIES Command 27
+ 8.13 ENABLE-CAPABILITIES Command 28
+ 8.14 EXPUNGE Command 28
+ 8.15 FILEPOS Command 29
+ 8.15.1 Implementation Hint for FILEPOS Command 30
+ 8.16 FINISH Command 30
+ 8.17 HOME-DIRECTORY Command 31
+ 8.18 LOGIN Command 32
+ 8.19 MULTIPLE-FILE-PLISTS Command 34
+ 8.20 OPEN Command 35
+ 8.20.1 NFILE OPEN Optional Keyword/Value Pairs 39
+ 8.20.2 NFILE OPEN Response Return Values 45
+ 8.21 PROPERTIES Command 47
+ 8.22 READ Command 49
+ 8.23 RENAME Command 50
+ 8.24 RESYNCHRONIZE-DATA-CHANNEL Command 51
+ 8.24.1 Implementation Hints for RESYNCHRONIZE-DATA- 51
+ CHANNEL Command
+ 8.25 UNDATA-CONNECTION Command 52
+
+ 9. NFILE RESYNCHRONIZATION PROCEDURE 53
+
+ 9.1 NFILE Control Connection Resynchronization 54
+ 9.2 NFILE Data Connection Resynchronization 55
+
+ 10. NFILE ERRORS AND NOTIFICATIONS 58
+
+ 10.1 Notifications From the NFILE Server 58
+ 10.2 NFILE Command Response Errors 59
+ 10.3 NFILE Asynchronous Errors 60
+ 10.4 NFILE Three-letter Error Codes 61
+
+ 11. TOKEN LIST TRANSPORT LAYER 65
+
+ 11.1 Introduction to the Token List Transport Layer 65
+ 11.2 Token List Stream 66
+ 11.2.1 Types of Tokens and Token Lists 66
+ 11.2.2 Token List Stream Example 68
+ 11.2.3 Mapping of Lisp Objects to Token List Stream 70
+ Representation
+ 11.2.4 Aborting and the Token List Stream 71
+
+
+
+Greenberg & Keene [Page 2]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ 11.3 Token List Data Stream 72
+
+ 12. BYTE STREAM WITH MARK 73
+
+ 12.1 Discussion of Byte Stream with Mark 73
+ 12.2 Byte Stream with Mark Abortable States 75
+
+ 13. POSSIBLE FUTURE EXTENSIONS 77
+
+ APPENDIX A. NORMAL TRANSLATION MODE 79
+
+ APPENDIX B. RAW TRANSLATION MODE 83
+
+ APPENDIX C. SUPER-IMAGE TRANSLATION MODE 84
+
+ NOTES 86
+
+ LIST OF TABLES
+
+ TABLE 1. TRANSLATIONS FROM NFILE CHARACTERS TO UNIX CHARACTERS 80
+ TABLE 2. TRANSLATIONS FROM UNIX CHARACTERS TO NFILE CHARACTERS 80
+ TABLE 3. TRANSLATIONS FROM NFILE TO PDP-10 CHARACTERS 81
+ TABLE 4. TRANSLATIONS FROM PDP-10 CHARACTERS TO NFILE 82
+ CHARACTERS
+ TABLE 5. SUPER-IMAGE TRANSLATION FROM NFILE TO ASCII 84
+ TABLE 6. SUPER-IMAGE TRANSLATION FROM ASCII TO NFILE 85
+
+1. INTRODUCTION
+
+ NFILE stands for "New File Protocol". NFILE was originally designed
+ as a replacement for an older protocol named QFILE, with the goal of
+ solving robustness problems of QFILE, hence the name "New File
+ Protocol".
+
+ NFILE was designed and implemented at Symbolics by Bernard S.
+ Greenberg. Mike McMahon made important contributions, especially in
+ the design and implementation of the Byte Stream with Mark and Token
+ List Transport layers. NFILE has been used successfully for file
+ access between Symbolics computers since 1985. NFILE servers have
+ been written for UNIX hosts as well. NFILE is intended for use by
+ any type of file system, not just the native Symbolics file system.
+
+ NFILE is a file access protocol that supports a large set of
+ operations on files and directories on remote systems, including:
+
+ - Reading and writing entire files
+ - Reading and writing selected portions of files
+ - Deleting and renaming files
+
+
+
+Greenberg & Keene [Page 3]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ - Creating links
+ - Listing, creating, and expunging directories
+ - Listing and changing the properties of files
+ - Enabling and disabling access capabilities on a remote
+ host
+
+ NFILE supports file transfer of binary or character files.
+
+ The NFILE server provides information about any errors that occur in
+ the course of a command. In addition, NFILE has a robust scheme for
+ handling aborts on the user side.
+
+ This specification defines NFILE user version 2 and server version 2.
+ We do not envision NFILE as an unchanging protocol, but rather as a
+ protocol that could continue to develop if additional requirements
+ are identified though the process of this Request for Comments. The
+ design of NFILE makes room for various useful extensions. Some of
+ the extensions that we are considering are described later on in this
+ document: See the section "Possible Future Extensions", section 13.
+
+2. NFILE PROTOCOL LAYERING
+
+ NFILE is a layered file protocol. The layers are:
+
+ +-----------------------------------------------+
+ |client program or user interface |
+ +-----------------------------------------------+
+ |NFILE |
+ +-----------------------------------------------+
+ |Token List Transport Layer |
+ +-----------------------------------------------+
+ |Byte Stream with Mark |
+ +-----------------------------------------------+
+ |reliable host-host byte transmission protocol |
+ +-----------------------------------------------+
+
+ Byte Stream with Mark is a simple protocol that guarantees that an
+ out-of-band signal can be transmitted in the case of program
+ interruption. Byte Stream with Mark is to be layered upon extant
+ byte stream protocols. An important goal of the NFILE design was
+ that NFILE could be built on any byte stream. It is currently
+ implemented on TCP and Chaosnet. See the section "Byte Stream with
+ Mark", section 12.
+
+ The Token List Transport Layer is a protocol that facilitates the
+ transmission of simple structured data, such as lists. See the
+ section "Token List Transport Layer", section 11.
+
+
+
+
+Greenberg & Keene [Page 4]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The NFILE commands and command responses are transmitted in "token
+ lists". See the section "NFILE Commands", section 8.
+
+ This specification does not include a client program or user
+ interface to the protocol. In the Symbolics implementation, the
+ normal file operations transparently invoke NFILE, when the remote
+ host is known to support NFILE. Another possible interface to NFILE
+ would be through a dedicated client program that would issue NFILE
+ commands in response to explicit requests by the user.
+
+3. OVERVIEW OF AN NFILE SESSION
+
+ An NFILE session is a dialogue between two hosts. The host that
+ initiates the NFILE session is known as the "user side", and the
+ other host is the "server side". The user side sends all NFILE
+ commands. The server receives each command, processes it, and
+ responds to it, indicating the success or failure of the command.
+
+ The user side keeps track of commands sent and command responses
+ received by using "transaction identifiers" to identify each command.
+ The user side generates a transaction identifier (which must be
+ unique per this dialogue) for each command, and sends the transaction
+ identifier to the server along with the command. Each NFILE server
+ response includes the transaction identifier of the command with
+ which the response is associated. The server is not required to
+ respond to commands in the same order that the user gave them.
+
+ The user side sends NFILE commands over a bidirectional network
+ connection called the "control connection". The server sends its
+ command responses on the same control connection. The control
+ connection governing the NFILE session is established at the
+ beginning of the session. If the control connection is ever broken,
+ the NFILE session is ended.
+
+ Whereas NFILE commands and responses are transmitted on the control
+ connection, file data is transferred over "data channels". An "input
+ data channel" transfers data from server to user. An "output data
+ channel" transfers data from user to server. Each input data channel
+ is associated with an output data channel; together these two
+ channels comprise a "data connection".
+
+ Often more than one NFILE activity is occurring at any given time.
+ For example, several files can be open and transferring data
+ simultaneously; one or more commands can be in process at the same
+ time; and the server can be simultaneously transmitting directory
+ lists and processing further commands. This happens in an
+ implementation in which the user side has multiple processes, and
+ several processes share a single NFILE server.
+
+
+
+Greenberg & Keene [Page 5]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+4. NFILE CONTROL AND DATA CONNECTIONS
+
+ The user and server communicate through a single control connection
+ and a set of data connections. Data connections are established and
+ disestablished by NFILE commands. The user side sends NFILE commands
+ to the server over the control connection. The server responds to
+ every user command over this control connection. The actual file
+ data is transmitted over the data connections.
+
+ User aborts can disrupt the normal flow of data on the control
+ connection and data connections. An important aspect of any file
+ protocol is the way it handles user aborts. NFILE uses a
+ resynchronization procedure to bring the affected control connection
+ or data channel from an unknown, unsafe state into a known state.
+ After resynchronization, the control connection or data channel can
+ be reused. See the section "NFILE Resynchronization Procedure",
+ section 9.
+
+ THE CONTROL CONNECTION
+
+ An NFILE session is begun when the NFILE user program connects to a
+ remote host and establishes a network connection. This initial
+ connection is the control conection of the dialogue. If TCP is used
+ as the underlying protocol, contact NFILE's well-known port, 59. If
+ Chaos is used, use the contact name "NFILE".
+
+ The control connection is the vehicle used by the user to send its
+ commands, and the server to send its command responses. These types
+ of communication occur over the NFILE control connection:
+
+ - The user side sends NFILE commands.
+ - The server sends command responses.
+ - The server sends "notifications" and "asynchronous errors".
+ See the section "NFILE Errors and Notifications", section 10.
+ - During resynchronization (a special circumstance) either the
+ user or server sends a mark.
+
+ All commands, command responses, and other data flowing over the
+ NFILE control connection are transmitted in the format of "top-level
+ token lists". The control connection expects never to receive "loose
+ tokens"; that is, tokens not contained in token lists.
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 6]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ DATA CONNECTIONS
+
+ Data connections are established and discarded at user request, by
+ means of two NFILE commands: DATA-CONNECTION and UNDATA-CONNECTION.
+ Each data connection is associated with a specific control
+ connection, which is the same control connection that caused the data
+ connection to be established.
+
+ Each data connection is composed of two "data channels". Each data
+ channel is capable of sending data in one direction. The term "input
+ channel" refers to the data channel that transmits data from the
+ server to the user side; "output channel" refers to the data channel
+ that transmits data from the user to the server side. Throughout the
+ NFILE documentation, the terms "input channel" and "output channel"
+ are seen from the perspective of the user side. A single data
+ channel can be used for one data transfer after another.
+
+ The format of the data transferred on the data channels is defined as
+ a "token list data stream". See the section "Token List Data
+ Stream", section 11.3. When the end of data is reached, the keyword
+ token EOF is sent. Occasionally, token lists are transmitted over
+ the data channels, such as asynchronous error descriptions.
+
+5. NFILE FILE OPENING MODES
+
+ The NFILE OPEN command opens a file for reading, writing, or "direct
+ access" at the server host. That means, in general, asking the host
+ file system to access the file and obtaining a file number, pointer,
+ or other quantity for subsequent rapid access to the file; this is
+ called an "opening". The term "opening" translates to a file stream
+ in Symbolics terminology, a JFN in TOPS-20 terminology, and a file
+ descriptor in UNIX terminology. An opening usually keeps track of
+ how many bytes have been read or written, and other bookkeeping
+ information.
+
+ NFILE supports two ways of transferring file data, "data stream mode"
+ and "direct access mode". A single mode is associated with each
+ opening. Note that an NFILE dialogue can have more than one opening,
+ and thus use both modes.
+
+ DATA STREAM MODE:
+
+ Data stream mode of file transfer is the default mode of NFILE's OPEN
+ command. Data stream mode is appropriate when the entire file is
+ transferred, either from user to server, or from server to user.
+ Data stream mode is used more often than direct access mode.
+
+
+
+
+
+Greenberg & Keene [Page 7]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The OPEN command includes a "handle" argument, which identifies the
+ data channel to be used to transfer the data. The handle is used in
+ subsequent commands to reference this particular opening. When a
+ data stream opening is requested with the OPEN command, the file is
+ opened and the data begins to flow immediately.
+
+ The sending side transmits the entire contents of the specified file
+ over the specified data channel as rapidly as the network permits.
+ When the sending side reaches the end of the file, it transmits a
+ special control token to signal end of file. The receiving side
+ expects an uninterrupted stream of bytes to appear immediately on its
+ side of the data channel.
+
+ The user gives the CLOSE command to terminate a data stream transfer.
+ CLOSE results in closing the file.
+
+ DIRECT ACCESS MODE:
+
+ Direct access mode enables reading or writing data from a given
+ starting point in a file through a specified number of bytes. In
+ direct access mode, data is requested and sent in individual
+ transactions. To request a direct access mode opening, the OPEN
+ command is used with a DIRECT-FILE-ID argument. (In data stream
+ mode, no DIRECT-FILE-ID is supplied.) The direct file identifier is
+ used in subsequent commands to reference the direct access opening.
+
+ When a file is opened in direct access mode, the flow of data does
+ not start immediately. Rather, the user gives either a READ command
+ (to request data to flow from server to user) or a DIRECT-OUTPUT
+ command (to request data to flow from user to server). When reading,
+ the READ command allows the user to specify the starting point and
+ the number of bytes of data to transfer. When writing, the FILEPOS
+ command can be used to specify the starting point, before the
+ DIRECT-OUTPUT command is given. The user can give many READ and
+ DIRECT-OUTPUT commands, one after another.
+
+ The user side terminates the direct access transfer by using the
+ CLOSE command. The ABORT command can be given to terminate without
+ transmitting all of the specified bytes.
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 8]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+6. NFILE CHARACTER SET
+
+ The NFILE character set <1> is an extension of standard ASCII. NFILE
+ command and response names use only the standard ASCII characters.
+ However, the protocol supports the transfer of the non-ASCII
+ characters in the NFILE character set; these characters might be
+ stored in files, or might be used in pathnames.
+
+ Servers on machines that do not natively use the NFILE character set
+ must perform character set translations for character openings,
+ depending on the requested translation mode. No translation is
+ required for binary openings. There are three translation modes for
+ character openings: NORMAL, RAW, and SUPER-IMAGE. Each mode
+ specifies a way to translate between the server's native set and the
+ NFILE character set.
+
+ NORMAL mode is the default of the OPEN command. The translation for
+ NORMAL mode ensures that a file containing characters in the NFILE
+ character set can be written to a remote host and read back intact.
+ OPEN has optional keyword arguments to specify RAW or SUPER-IMAGE.
+ RAW mode means to perform no translation whatsoever. SUPER-IMAGE
+ mode is intended for use by PDP-10 family machines only. It is
+ included largely as an illustration of a system-dependent extension.
+
+ The details of each translation mode are given in Appendices:
+
+ See the section "NORMAL Translation Mode", Appendix A. See the
+ section "RAW Translation Mode", Appendix B. See the section
+ "SUPER-IMAGE Translation Mode", Appendix C.
+
+ The use of the NFILE character set brings up a difficulty involved
+ with determining an exact position within a character file. Some
+ NFILE characters expand to more than one native character on some
+ servers. Thus, for character files, when we speak of a given
+ position in a file or the length of a file, we must specify whether
+ we are speaking in "NFILE units" or "server units", because the
+ counting of characters is different. This causes major problems in
+ file position reckoning for character files. Specifically, it is
+ futile for a user side to carefully monitor file position during
+ output by counting characters, when character translation is in
+ effect. The server's operating system interface for "position to
+ point x in a file" necessarily operates in server units, but the user
+ side has counted in NFILE units. The user side cannot try to
+ second-guess the translation-counting process without losing host-
+ independence. See the section "FILEPOS NFILE Command".
+
+
+
+
+
+
+Greenberg & Keene [Page 9]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+7. CONVENTIONS USED IN THIS DOCUMENT
+
+7.1 Mapping Data Types Into Token List Representation
+
+ Throughout this NFILE specification, the data types of arguments,
+ return values, asynchronous error descriptions, and notifications are
+ described as being strings, integers, dates, time intervals, and so
+ on. However, each conceptual data type must be mapped into the
+ appropriate token list representation for transmission. The mapping
+ of conceptual data types to token list representation is shown here:
+
+ Conceptual Type Token List Representation
+
+ ----------------------------------------------------------------
+
+ Keyword A keyword token
+
+ Keyword list A token list of keyword tokens
+
+ Integer A numeric data token
+
+ String A data token containing the characters of the
+ string in the NFILE character set.
+
+ Boolean Truth The token known as BOOLEAN-TRUTH.
+
+ Boolean False The empty token list.
+
+ Date A numeric data token. The date is expressed in
+ Universal Time format, which measures a time as
+ the number of seconds since January 1, 1900, at
+ midnight GMT.
+
+ Date-or-never Can be either a date or the empty token list,
+ representing "never". "Never" is used for
+ values such as the time a directory was last
+ expunged, if it has never been expunged.
+
+ Time interval A numeric data token. The time interval is
+ expressed in seconds. A time interval
+ indicating "never" is represented by the empty
+ token list.
+
+7.2 Format of NFILE Commands and Responses
+
+ Each command description begins by giving the command format and
+ response format. Here is the beginning of the DATA-CONNECTION
+ command description:
+
+
+
+Greenberg & Keene [Page 10]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ Command: (DATA-CONNECTION tid new-input-handle new-output-handle)
+
+ Response: (DATA-CONNECTION tid connection-identifier)
+
+ The command descriptions follow these conventions:
+
+ 1. NFILE commands and responses are transmitted as top-level token
+ lists.
+
+ Top-level token lists are enclosed in parentheses in these
+ command descriptions. These parentheses are not sent literally
+ across the control or data connections, but are a shorthand
+ representation of special control tokens that delimit top-level
+ token lists. Specifically, TOP-LEVEL-LIST-BEGIN starts a top-
+ level token list; TOP-LEVEL-LIST-END ends a top-level token list.
+
+ 2. NFILE command names are keywords.
+
+ The command name is required in every command and command
+ response. All NFILE command names are keywords. Keywords appear
+ in the NFILE documentation as their names in uppercase. For
+ example, DATA-CONNECTION and DELETE are two command names.
+
+ 3. A unique transaction identifier (tid) identifies each command.
+
+ The transaction identifier is a string made up by the user side
+ to identify this particular transaction, which is composed of the
+ command and the response associated with this command. The
+ transaction identifier is abbreviated in the command descriptions
+ as tid. Transaction identifiers are limited to fifteen
+ characters in length. The transaction identifier is required in
+ every command and command response.
+
+ OPTIONAL ARGUMENTS
+
+ Many NFILE commands have "optional arguments". Optional arguments
+ can be supplied (with appropriate values), or left out. If optional
+ arguments are left out, their omission must be made explicit by means
+ of substituting the empty token list in their place. The only
+ exception to that rule is for trailing optional arguments or return
+ values, which can be omitted without including the empty token list.
+
+ For example, the text of the DELETE command description explains that
+ either a handle or a pathname must be supplied, but not both;
+ therefore, one of them is an optional argument. Here is the command
+ format of DELETE:
+
+ (DELETE tid handle pathname)
+
+
+
+Greenberg & Keene [Page 11]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ If you supply a handle and no pathname, the command format is:
+
+ (DELETE tid handle)
+
+ If you supply a pathname and no handle, the command format is:
+
+ (DELETE tid empty-token-list pathname)
+
+ The empty token list in the token list stream appears as a LIST-BEGIN
+ followed immediately by a LIST-END.
+
+ OPTIONAL KEYWORD/VALUE PAIRS
+
+ Four NFILE commands have "optional keyword/value pairs". These
+ commands are: COMPLETE, LOGIN, OPEN, and READ. Optional
+ keyword/value pairs can be either included in the command or omitted
+ entirely. There is no need to substitute the empty token list for
+ ommitted optional keyword tokens, unlike optional arguments. The
+ order of the option keyword/value pairs is not significant.
+
+ If included, optional keyword/value pairs are a sequence of
+ alternating keywords and values. The values associated with the
+ keywords can be keywords, lists, strings, Booleans, integers, dates,
+ date-or-never's, and time intervals. The text of each command
+ description states what type of value is appropriate for each
+ optional keyword.
+
+ Optional keyword/value pairs appear in the text as the keyword only,
+ in uppercase letters. For example, here is the format of the LOGIN
+ command:
+
+ Command Format:
+
+ (LOGIN tid user password FILE-SYSTEM USER-VERSION)
+
+ FILE-SYSTEM and USER-VERSION are two optional keywords associated
+ with the LOGIN command. The user side can supply USER-VERSION, and
+ omit FILE-SYSTEM as shown in this example:
+
+ (LOGIN x105 tjones let-me-in USER-VERSION 2)
+
+ As seen above, the optional keyword/value pair USER-VERSION, if
+ supplied in a command, consists of the keyword USER-VERSION followed
+ by the value to be used for that keyword (in this example, 2).
+
+
+
+
+
+
+
+Greenberg & Keene [Page 12]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+7.3 Data Channel Handles and Direct File Identifiers
+
+ Several NFILE commands require an argument that specifies an opening.
+ This kind of argument is called a handle in the command description.
+ It is always a string type argument. A handle can be either a data
+ channel handle or a direct file identifier, depending on the mode of
+ the opening:
+
+
+ Data Stream
+
+ The handle must identify a data channel that is bound to an opening.
+
+ Direct Access
+
+ In general, the handle must be a direct file identifier. A direct
+ file identifier specifies a direct access opening. It is the same as
+ the value supplied in the DIRECT-FILE-ID keyword/value pair in the
+ OPEN command. It is used for all operations that identify an opening
+ rather than a data channel.
+
+ Two NFILE commands applicable to direct access openings are
+ exceptions to the general rule. The handle supplied in ABORT and
+ CONTINUE cannot be a direct file identifier, but must be a data
+ channel handle instead.
+
+7.4 Syntax of File and Directory Pathname Arguments
+
+ Some arguments and return values in the NFILE command descriptions
+ represent file pathnames. These are strings in the pathname syntax
+ native to the server host. These pathnames contain no host
+ identifiers of any kind. These pathnames must be fully defaulted, in
+ the sense that they have a directory and file name (and file type, if
+ the server operating system supports file types). If appropriate, a
+ device is referenced in the pathname. If the server file system
+ supports version numbers, there is always an explicit version number,
+ even if that number or other specification is that system's
+ representation of "newest" or "oldest".
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 13]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ Here are some examples of file pathnames, for different server hosts:
+
+ Server Host Example of File Pathname
+
+ ------------------------------------------------------------
+
+ UNIX /usr/max/life.c
+
+ TOPS-20 ps:<max>life.bin.17
+
+ VMS MACD:[MAX]LIFE.FOR;3
+
+ Symbolics LMFS >max>life.lisp.newest
+
+ ------------------------------------------------------------
+
+ The CREATE-DIRECTORY and HOME-DIRECTORY commands take a directory as
+ an argument. In NFILE commands, a directory is represented by a
+ string that names the directory. In most cases this string is in the
+ syntax native to the server host. However in some cases the native
+ format is modified somewhat to clarify that the string names a
+ directory, and not a file. For example, a directory on UNIX is
+ represented by "/usr/max/", not "/usr/max".
+
+ Here are some examples of directory pathnames for different server
+ hosts:
+
+ Server Host Example of Directory Pathname
+
+ ------------------------------------------------------------
+
+ UNIX /usr/max/
+
+ TOPS-20 <max>
+
+ VMS MACD:[MAX]
+
+ Symbolics LMFS >max>hacks>
+
+ ------------------------------------------------------------
+
+7.5 Format of NFILE File Property/Value Pairs
+
+ Several NFILE commands request information regarding the properties
+ of files or directories. These commands include: DIRECTORY,
+ MULTIPLE-FILE-PLISTS, PROPERTIES, and CHANGE-PROPERTIES. This
+ section describes how file property information is conveyed over the
+ token list stream.
+
+
+
+Greenberg & Keene [Page 14]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ File property information is usually sent in property/value pairs,
+ where the property identifies the property, and the following value
+ gives the value of that property for the specified file.
+
+ Each property is denoted either by a keyword or an integer. You can
+ mix both ways of specifying properties (keyword or integer) within a
+ single description. An integer is interpreted as an index into the
+ Property Index Table, an array of property keywords. The server can
+ optionally send a Property Index Table to the user during the
+ execution of the LOGIN command, although it is not required. This
+ greatly reduces the length of transmissions.
+
+ In command arguments, file properties cannot be specified with
+ integers; keywords must be used to specify file properties in command
+ arguments. Integers can be used to denote file properties only in
+ command responses.
+
+ We now list the keywords associated with file properties. This list
+ is not intended to be restrictive. If a programmer implementing
+ NFILE needs a new keyword, a new keyword (not on this list) can be
+ invented. The type of value of any new keywords is by default
+ string. The keywords are sorted here by conceptual data type:
+
+ Data type Keywords denoting file properties
+
+ ----------------------------------------------------------------
+
+ Integers BLOCK-SIZE, BYTE-SIZE, GENERATION-RETENTION-COUNT,
+ LENGTH-IN-BLOCKS, LENGTH-IN-BYTES,
+ DEFAULT-GENERATION-RETENTION-COUNT
+
+ Dates CREATION-DATE, MODIFICATION-DATE
+
+ Date-or-never's REFERENCE-DATE, INCREMENTAL-DUMP-DATE,
+ COMPLETE-DUMP-DATE, DATE-LAST-EXPUNGED,
+ EXPIRATION-DATE
+
+ Time intervals AUTO-EXPUNGE-INTERVAL
+
+ Keyword Lists SETTABLE-PROPERTIES, LINK-TRANSPARENCIES,
+ DEFAULT-LINK-TRANSPARENCIES
+
+ Boolean values DELETED, DONT-DELETE, DONT-DUMP, DONT-REAP,
+ SUPERSEDE-PROTECT, NOT-BACKED-UP, OFFLINE,
+ TEMPORARY, CHARACTERS, DIRECTORY
+
+
+
+
+
+
+Greenberg & Keene [Page 15]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ Strings ACCOUNT, AUTHOR, LINK-TO, PHYSICAL-VOLUME,
+ PROTECTION, VOLUME-NAME, PACK-NUMBER, READER,
+ DISK-SPACE-DESCRIPTION, and any keywords not
+ on this list
+
+ Note that these keyword names are intended to imply the semantics of
+ the properties. For a discussion of the semantics of CREATION-DATE:
+ See the section "NFILE OPEN Response Return Values", section 8.20.2.
+ The "Reference Guide to Streams, Files, and I/O" in the Symbolics
+ documentation set details the semantics that Symbolics associates
+ with these properties.
+
+8. NFILE COMMANDS
+
+ It is important to understand the conventions used in each of the
+ following command descriptions. See the section "Conventions Used in
+ This Document", section 7.
+
+8.1 ABORT Command
+
+ Command: (ABORT tid input-handle)
+
+ Response: (ABORT tid)
+
+ ABORT cleanly interrupts and prematurely terminates a single direct
+ access mode data transfer initiated with READ. The required input-
+ handle string argument identifies a data channel on which an input
+ transfer is currently taking place; this must be a direct access
+ transfer. input-handle must identify a data channel; it cannot be a
+ direct file identifier.
+
+ Upon receiving the ABORT command, the server checks to see if a
+ transfer is still active on that channel. If so, the server
+ terminates the transfer by telling the data connection logical
+ process to stop transferring bytes of data. The user side needs to
+ issue this command only when there are outstanding unread bytes.
+ This excludes the case of the data channel having been disestablished
+ or reallocated by the user side.
+
+ Whether or not a transfer is active on that channel, the user side
+ puts the data channel into the unsafe state. Before the data channel
+ can be used again, it must be resynchronized.
+
+8.2 CHANGE-PROPERTIES Command
+
+ Command: (CHANGE-PROPERTIES tid handle pathname property-pairs)
+
+ Response: (CHANGE-PROPERTIES tid)
+
+
+
+Greenberg & Keene [Page 16]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ CHANGE-PROPERTIES changes one or more properties of a file. Either a
+ handle or a pathname must be given, but not both. Whichever one is
+ given must be supplied as a string. handle identifies a data channel
+ that is bound to an open file; it can be a direct file identifier.
+ pathname identifies a file on the server machine.
+
+ property-pairs is a required token list of keyword/value pairs, where
+ the name of the property to be changed is the keyword, and the
+ desired new property value is the value.
+
+ The properties that can be changed are host-dependent, as are any
+ restrictions on the values of those properties. The properties that
+ can be changed are the same as those returned as settable-properties,
+ in the command response for the PROPERTIES command.
+
+ The server tries to modify all the properties listed in property-
+ pairs to the desired new values. There is currently no definition
+ about what should be done if the server can successfully change some
+ properties but not others.
+
+ For further information on file property keywords and associated
+ values: See the section "Format of NFILE File Property/Value Pairs",
+ section 7.5.
+
+8.3 CLOSE Command
+
+ Command: (CLOSE tid handle abort-p)
+
+ Response: (CLOSE tid truename binary-p other-properties)
+
+ CLOSE terminates a data transfer, and frees a data channel. The
+ handle must be a data channel handle for a data stream opening, or a
+ direct file identifier for a direct access opening. If a data
+ channel is given, a transfer must be active on that handle. If
+ abort-p is supplied as Boolean truth, the file is close-aborted, as
+ described below.
+
+ "Closing the file" has different implications specific to each
+ operating system. It generally implies invalidation of the pointer
+ or logical identifier obtained from the operating system when the
+ file was "opened", and freeing of operating system and/or job
+ resources associated with active file access. For output files, it
+ involves ensuring that every last bit sent by the user has been
+ successfully written to disk. The server should not send a
+ successful response until all these things have completed
+ successfully.
+
+
+
+
+
+Greenberg & Keene [Page 17]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ In either data stream or direct access mode, the user can request the
+ server to close-abort the file, instead of simply closing it. To
+ close-abort a file means to close it in such a way, if possible, that
+ it is as if the file had never been opened. In the specific case of
+ a file being created, it must appear as if the file had never been
+ created. This might be more difficult to implement on certain
+ operating systems than others, but tricks with temporary names and
+ close-time renamings by the server can usually be used to implement
+ close-abort in these cases. In the case of a file being appended to,
+ close-abort means to forget the appended data.
+
+ AN UNSUCCESSFUL CLOSE OPERATION
+
+ For the normal CLOSE operation (not a close-abort), after writing
+ every last bit sent by the user to disk, and before closing the file,
+ the server checks the data channel specified by handle to see if an
+ asynchronous error is outstanding on that channel. That is, the
+ server must determine whether it has sent an asynchronous error
+ description to the user, to which the user has not yet responded with
+ a CONTINUE command. If so, the server is unable to close the file,
+ and therefore sends a command error response indicating that an error
+ is pending on the channel. The appropriate three-letter error code
+ is EPC. See the section "NFILE Errors and Notifications", section
+ 10.
+
+ A SUCCESSFUL CLOSE OPERATION
+
+ The return values for OPEN and CLOSE are syntactically identical, but
+ the values might change between the time of the file being opened and
+ when it is closed. For example, the truename return value is
+ supplied after all the close-time renaming of output files is done
+ and the version numbers resolved (for operating systems supporting
+ version numbers). Therefore, on some systems the truename of a file
+ has one value at the time it is opened, and a different value when it
+ has been closed. For a description of the CLOSE return values: See
+ the section "NFILE OPEN Response Return Values", section 8.20.2.
+
+ If the user gives the CLOSE command with abort-p supplied as Boolean
+ truth, thus requesting a close-abort of the file, the server need not
+ check whether an asynchronous error description is outstanding on the
+ channel. The server simply close-aborts the file.
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 18]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+8.4 COMPLETE Command
+
+ Command: (COMPLETE tid string pathname DIRECTION NEW-OK DELETED)
+
+ Response: (COMPLETE tid new-string success)
+
+ COMPLETE performs file pathname completion.
+
+ string is a partial filename typed by the user and pathname is the
+ default name against which it is being typed. Both string and
+ pathname are required arguments, and are of type string. The
+ remaining arguments are optional keyword/value pairs.
+
+ NEW-OK is Boolean; if followed by Boolean truth, the server should
+ allow either a file that already exists, or a file that does not yet
+ exist. The default of NEW-OK is false; that is, the server does not
+ consider files that do not already exist.
+
+ DELETED is a Boolean type argument; if followed by Boolean truth, the
+ server is instructed to look for files that have been deleted but not
+ yet expunged, as well as non-deleted files. The default is to ignore
+ soft-deleted files.
+
+ DIRECTION can be followed by READ, to indicate that the file is to be
+ read. If the file is to be written, DIRECTION can be followed by
+ WRITE. The default is READ.
+
+ The filename is completed according to the files present in the host
+ file system, and the expanded string new-string is returned. New-
+ string is always a string containing a file name: either the
+ original string, or a new, more specific string. The value of
+ success indicates the status of the completion. The keyword value OLD
+ or NEW means complete success, whereas the empty token list means
+ failure. The following values of success are possible:
+
+ Value Meaning
+
+ ----------------------------------------------------------------
+
+ OLD Success: the string completed to the name of
+ a file that exists.
+
+ NEW Success: the string completed to the name of
+ a file that could be created.
+
+ Empty token list Failure due to one of these reasons:
+
+ The file is on a file system that does not
+
+
+
+Greenberg & Keene [Page 19]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ support completion. new-string is supplied as
+ the unchanged string.
+
+ There is no possible completion. new-string
+ is supplied as the unchanged string.
+
+ There is more than one possible completion.
+ The given string is completed up to the first
+ point of ambiguity, and the result is supplied
+ as new-string.
+
+ A directory name was completed. Completion
+ was not successful because additional
+ components to the right of this directory
+ remain to be specified. The string is
+ completed through the directory name and the
+ delimiter that follows it, and the result is
+ returned in new-string.
+
+ The semantics of COMPLETE are not documented here. See the
+ "Reference Guide to Streams, Files, and I/O" in the Symbolics
+ documentation set for the recommended semantics of COMPLETE.
+
+8.5 CONTINUE Command
+
+ Command: (CONTINUE tid handle)
+
+ Response: (CONTINUE tid)
+
+ CONTINUE resumes a data transfer that was temporarily suspended due
+ to an asynchronous error. Each asynchronous error description has an
+ optional argument of RESTARTABLE, indicating whether it makes any
+ sense to try to continue after this particular error occurred.
+ CONTINUE tries to resume the data transfer if the error is
+ potentially recoverable, according to the RESTARTABLE argument in the
+ asynchronous error description. For a discussion of asynchronous
+ errors: See the section "NFILE Errors and Notifications", section
+ 10.
+
+ handle is a required string-type argument that refers to the handle
+ of the data channel that received an asynchronous error. That data
+ channel could have been in use for a data stream or direct access
+ transfer. handle cannot be a direct file identifier.
+
+ If the asynchronous error description does not contain the
+ RESTARTABLE argument, and the user issues the CONTINUE command
+ anyway, the server gives a command error response.
+
+
+
+
+Greenberg & Keene [Page 20]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+8.6 CREATE-DIRECTORY Command
+
+ Command: (CREATE-DIRECTORY tid pathname property-pairs)
+
+ Response: (CREATE-DIRECTORY tid dir-truename)
+
+ CREATE-DIRECTORY creates a directory on the remote file system. The
+ required pathname argument is a string identifying the pathname of
+ the directory to be created. The return value dir-truename is the
+ pathname of the directory that was successfully created. Both of
+ these pathnames are directory pathnames: See the section "Syntax of
+ File and Directory Pathname Arguments", section 7.4.
+
+ property-pairs is a keyword/value list of properties that further
+ define the attributes of the directory to be created. The allowable
+ keywords and associated values are operating system dependent;
+ typically they indicate arguments to be given to the native primitive
+ for creating directories.
+
+ If property-pairs is supplied as the empty token list, default access
+ and creation attributes apply and should be assured by the server.
+ See the section "Format of NFILE File Property/Value Pairs", section
+ 7.5.
+
+8.7 CREATE-LINK Command
+
+ Command: (CREATE-LINK tid pathname target-pathname properties)
+
+ Response: (CREATE-LINK tid link-truename)
+
+ CREATE-LINK creates a link on the remote file system.
+
+ pathname is the pathname of the link to be created; target-pathname
+ is the place in the file system to which the link points. Both are
+ required arguments. The return value link-truename names the
+ resulting link.
+
+ If a server on a file system that does not support links receives the
+ CREATE-LINK command, it sends a command error response.
+
+ The arguments pathname and target-pathname, and the return value
+ link-truename, are all strings in the full pathname syntax of the
+ server host. See the section "Syntax of File and Directory Pathname
+ Arguments", section 7.4.
+
+ The required properties argument is a token list of keyword/value
+ pairs. These properties and their values specify certain attributes
+ to be given to the link. The allowable keywords and associated
+
+
+
+Greenberg & Keene [Page 21]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ values are operating system dependent; typically they indicate
+ arguments to be given to the native primitive for creating links.
+
+ If no property pairs are given in the command, the server should
+ apply a reasonable default set of attributes to the link. See the
+ section "Format of NFILE File Property/Value Pairs", section 7.5.
+
+8.8 DATA-CONNECTION Command
+
+ Command: (DATA-CONNECTION tid new-input-handle new-output-handle)
+
+ Response: (DATA-CONNECTION tid connection-identifier)
+
+ DATA-CONNECTION enablesthe user side to initiate the establishment of
+ a new data connection. The user side supplies two required string
+ arguments, new-input-handle and new-output-handle. These arguments
+ are used by subsequent commands to reference the two data channels
+ that constitute the data connection now being created. new-input-
+ handle describes the server-to-user data channel, and new-output-
+ handle describes the user-to-server channel. new-input-handle and
+ new-output-handle cannot refer to any data channels already in use.
+
+ Upon receiving the DATA-CONNECTION command, the server arranges for a
+ logical port (called socket or contact name on some networks) to be
+ made available on the foreign host machine. When the server has made
+ that port available, it must inform the user of its identity. The
+ server relays that information in the command response, in the
+ required connection-identifier, a string. The server then listens on
+ the port named by connection-identifier, and waits for the user side
+ to connect to it.
+
+ Upon receiving the success command response, the user side supplies
+ the connection-identifier to the local network implementation, in
+ order to connect to the specified port. The data connection is not
+ fully established until the user side connects successfully to that
+ port. This command is unusual in that the successful command
+ response does not signify the completion of the command; it indicates
+ only that the server has fulfilled its responsibility in the process
+ of establishing a data connection.
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 22]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The connection-identifier informs the user of the correct identity of
+ the logical port that the server has provided. NFILE expects the
+ connection-identifier to be a string. For TCP this string is the
+ port number represented in decimal. For Chaosnet, this string is the
+ contact name. The connection-identifier is used only once; in all
+ subsequent NFILE commands that need to reference either of the data
+ channels that constitute this data connection, the new-input-handle
+ and new-output-handle are used.
+
+ For background information: See the section "NFILE Control and Data
+ Connections", section 4.
+
+8.9 DELETE Command
+
+ Command: (DELETE tid handle pathname)
+
+ Response: (DELETE tid)
+
+ DELETE deletes a file on the remote file system.
+
+ Either a handle or a pathname must be supplied, but not both. If
+ given, the handle must be a data channel handle for a data stream
+ opening, or a direct file identifier for a direct access opening.
+ pathname is a string in the full pathname syntax of the server host.
+ See the section "Syntax of File and Directory Pathname Arguments",
+ section 7.4.
+
+ With a pathname supplied, the DELETE command causes the specified
+ file to be deleted. DELETE has different results depending on the
+ operating system involved. That is, DELETE causes soft deletion on
+ TOPS-20 and LMFS, and hard deletion on UNIX and Multics. If an
+ attempt is made to delete a delete-through link on a Symbolics LMFS,
+ its target is deleted instead.
+
+ If the handle argument is supplied to DELETE, the server deletes the
+ open file bound to the data channel specified by handle at close
+ time. This is true in both the output and input cases.
+
+8.10 DIRECT-OUTPUT Command
+
+ Command: (DIRECT-OUTPUT tid direct-handle output-handle)
+
+ Response: (DIRECT-OUTPUT tid)
+
+ DIRECT-OUTPUT starts and stops output data flow for a direct access
+ file opening. DIRECT-OUTPUT explicitly controls binding and
+ unbinding of an output data channel to a direct access opening.
+
+
+
+
+Greenberg & Keene [Page 23]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ direct-handle is a required argument, and output-handle is optional.
+
+ If supplied, output-handle is a request to bind an output data
+ channel (indicated by output-handle) to the direct access opening
+ designated by the direct-handle. The specified output data channel
+ must be free. The server binds the data channel and begins accepting
+ data from that connection and writing it to the opening.
+
+ If the output-handle is omitted, this is a request to unbind the
+ channel and terminate the active output transfer.
+
+8.11 DIRECTORY Command
+
+ Command: (DIRECTORY tid input-handle pathname control-keywords
+ properties)
+
+ Response: (DIRECTORY tid)
+
+ DIRECTORY returns a directory listing including the identities and
+ attributes for logically related groups of files, directories, and
+ links. If the command is successful, a single token list containing
+ the requested information is sent over the data channel specified by
+ input-handle, and the data channel is then implicitly freed by both
+ sides <2>. For details on the format of the token list: See the
+ section "NFILE DIRECTORY Data Format", section 8.11.1.
+
+ pathname specifies the files that are to be described; it is a string
+ in the full pathname syntax of the server host. See the section
+ "Syntax of File and Directory Pathname Arguments", section 7.4.
+
+ The pathname generally contains wildcard characters, in operating-
+ system-specific format, describing potential file name matches. Most
+ operating systems provide a facility that accepts such a pathname and
+ returns information about all files matching this pathname. Some
+ operating systems allow wildcard (potential multiple) matches in the
+ directory or device portions of the pathname; other operating systems
+ do not. There is no clear contract at this time about what is
+ expected of servers on systems that do not allow wildcard matches (or
+ some kinds of wild card matches), when presented with a wildcard.
+
+ properties is a token list of keywords that are the names of
+ properties. If properties is omitted or supplied as the empty token
+ list, the server sends along all properties. If any properties are
+ supplied, the user is requesting the server to send only those
+ properties.
+
+
+
+
+
+
+Greenberg & Keene [Page 24]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ control-keywords ARGUMENT TO DIRECTORY
+
+ control-keywords is a token list of keywords. The control-keywords
+ affect the way the DIRECTORY command works on the server machine.
+ Although some of the options below request the server to limit (by
+ some filter) the data to be returned, it is never an error if the
+ server returns more information than is requested.
+
+ The following keywords are recognized:
+
+ DELETED
+
+ Includes soft-deleted files in the directory list. Without this
+ option, they must not be included. Such files have the DELETED
+ property indicated as true" among their properties. DELETED is
+ ignored on systems that do not support soft deletion.
+
+ DIRECTORIES-ONLY
+
+ This option changes the semantics of DIRECTORY fairly drastically.
+ Normally, the server returns information about all files,
+ directories, and links whose pathnames match the supplied pathname.
+ This means that for each file, directory, or link to be listed, its
+ directory name must match the potentially wildcarded) directory name
+ in the supplied pathname, its file name must match the file name in
+ the supplied pathname, and so on.
+
+ When DIRECTORIES-ONLY is supplied, the server is to list only
+ directories, not whose pathnames match the supplied pathname, but
+ whose pathnames expressed as directory pathnames match the
+ (potentially wildcarded) directory portion of the supplied pathname.
+ The description of the PROBE-DIRECTORY keyword that can be supplied
+ as the direction argument of the OPEN command discusses this: See
+ the section "OPEN Command", section 8.20.
+
+ It is not yet established what servers on hosts that do not support
+ this type of action natively are to do when presented with
+ DIRECTORIES-ONLY and a pathname with a wildcard directory component.
+
+ FAST Speeds up the operation and data transmission by not listing any
+ properties at all for the files concerned; that is, only the
+ truenames are returned.
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 25]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ NO-EXTRA-INFO
+
+ Specifies that the server is to suppress listing those properties
+ that are generally more difficult or expensive to obtain. This
+ typically eliminates listing of directory-specific properties such as
+ information about default generation counts and expunge dates.
+
+ SORTED
+
+ This causes the directory listing to be sorted. The sorting is done
+ alphabetically by directory, then by file name, then file type, then
+ file version (by increasing version number).
+
+8.11.1 NFILE DIRECTORY Data Format
+
+ If the NFILE DIRECTORY command completes successfully, a single token
+ list containing the requested directory information is sent on the
+ data channel specified by the input-handle argument in the DIRECTORY
+ command. This section describes the format of that single token
+ list, and gives further detail on the properties argument to
+ DIRECTORY.
+
+ The token list is a top-level token list, so it is delimited by TOP-
+ LEVEL-LIST-BEGIN and TOP-LEVEL-LIST-END. The top-level token list
+ contains embedded token lists. The first embedded token list
+ contains the empty token list followed by property/value pairs
+ describing property information of the file system as a whole rather
+ than of a specific file. NFILE requires one property of the file
+ system to be present: DISK-SPACE-DESCRIPTION is a string describing
+ the amount of free file space available on the system. The following
+ embedded token lists contain the pathname of a file, followed by
+ property/value pairs describing the properties of that file.
+
+ The following example shows the format of the top-level token list
+ returned by DIRECTORY, for two files. It is expected that the server
+ return several property/value pairs for each file; the number of
+ pairs returned is not constrained. In this example, two
+ property/value pairs are returned for the file system, two pairs are
+ returned for the first file, and only one pair is returned for the
+ second file.
+
+ TOP-LEVEL-LIST-BEGIN
+ LIST-BEGIN - first embedded token list starts
+ LIST-BEGIN - an empty embedded token list starts
+ LIST-END - the empty embedded token list ends
+ prop1 value1 - property/value pairs of file system
+ prop2 value2
+ LIST-END
+
+
+
+Greenberg & Keene [Page 26]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ LIST-BEGIN
+ pathname1 - pathname of the first file
+ prop1 value1 - property/value pairs of first file
+ prop2 value2
+ LIST-END
+ LIST-BEGIN
+ pathname2 - pathname of the second file
+ prop1 value1 - property/value pairs of second file
+ LIST-END
+ TOP-LEVEL-LIST-END
+
+ The following example is designed to illustrate the structure of the
+ top-level token list by depicting TOP-LEVEL-LIST-BEGIN and TOP-
+ LEVEL-LIST-END by parentheses and LIST-BEGIN and LIST-END by squarbe
+ rackets. respectively. The indentation, blank spaces, and newlines
+ in the example are not part of the token list, but are used here to
+ make the structure of the token list clear.
+
+ ([ [ ] prop1 value1 prop2 value2]
+ [pathname1 prop1 value1 prop2 value2]
+ [pathname2 prop1 value1])
+
+ The pathname is a string in the full pathname syntax of the server
+ host. See the section "Syntax of File and Directory Pathname
+ Arguments", section 7.4.
+
+ For further information on file property/value pairs: See the
+ section "Format of NFILE File Property/Value Pairs", section 7.5.
+
+8.12 DISABLE-CAPABILITIES Command
+
+ Command: (DISABLE-CAPABILITIES tid capability)
+
+ Response: (DISABLE-CAPABILITIES tid cap-1 success-1
+ cap-2 success-2 cap-3 success-3 ...)
+
+ DISABLE-CAPABILITIES causes an access capability to be disabled on
+ the server machine. capability is a string naming the capability to
+ be disabled. The meaning of the capability is dependent on the
+ operating system.
+
+ The return values cap-1, cap-2, and so on, are strings specifying
+ names of capabilities. If the capability named by cap-1 was
+ successfully disabled, the corresponding success-1 is supplied as
+ Boolean truth; otherwise it is the empty token list.
+
+
+
+
+
+
+Greenberg & Keene [Page 27]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ Although the user can specify only one capability to disable, it is
+ conceivable that the result of disabling that particular capability
+ is the disabling of other, related capabilities. That is why the
+ command response can contain information on more than one capability.
+
+8.13 ENABLE-CAPABILITIES Command
+
+ Command: (ENABLE-CAPABILITIES tid capability password)}
+
+ Response: (ENABLE-CAPABILITIES tid cap-1 success-1
+ cap-2 success-2 cap-3 success-3 ...)
+
+ ENABLE-CAPABILITIES causes an access capability to be enabled on the
+ server machine. The password argument is optional, and should be
+ included only if it is needed to enable this particular capability.
+ Both password and capability are strings. The meaning of the
+ capability is dependent on the operating system.
+
+ The return values cap-1, cap-2 and so on, are strings specifying
+ names of capabilities. If the capability named by cap-1 was
+ successfully enabled, the corresponding success-1 is supplied as
+ Boolean truth; otherwise it is the empty token list.
+
+ Although the user can specify only one capability to enable, it is
+ conceivable that the result of enabling that particular capability is
+ the enabling of other, related capabilities. That is why the command
+ response can contain information on more than one capability.
+
+8.14 EXPUNGE Command
+
+ Command: (EXPUNGE tid directory-pathname)
+
+ Response: (EXPUNGE tid server-storage-units-freed)
+
+ EXPUNGE causes the directory specified by pathname to be expunged.
+ Expunging means that any files that have been soft deleted are to be
+ permanently removed.
+
+ For file systems that do not support soft deletion, the command is to
+ be ignored; a success command response is sent, but no action is
+ performed on the file system. In this case, the number-of-server-
+ storage-units-freed return value should be omitted.
+
+ directory-pathname is a required string argument in the directory
+ pathname format; it must refer to a directory on the server file
+ system, and not to a file. See the section "Syntax of File and
+ Directory Pathname Arguments", section 7.4.
+
+
+
+
+Greenberg & Keene [Page 28]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The return value server-storage-units-freed is an integer specifying
+ how many records, blocks, or whatever unit is used to measure file
+ storage on the server host system, were recovered. This return value
+ should be omitted if the server does not know how many storage units
+ were freed.
+
+ The protocol does not define whether directory-pathname is really a
+ pathname as directory or a wildcard pathname of files to be expunged.
+ The protocol does not define whether or not wildcards are permitted,
+ or required to be supported, in the directory portion of the pathname
+ (representing an implicit request to expunge many directories).
+
+8.15 FILEPOS Command
+
+ Command: (FILEPOS tid handle position resync-uid)
+
+ Response: (FILEPOS tid)
+
+ FILEPOS sets the file access pointer to a given position, relative to
+ the beginning of the file. FILEPOS is used to indicate the position
+ of the next byte of data to be transferred.
+
+ The handle indicates the file to be affected. handle must be a data
+ channel handle for a data stream opening, or a direct file identifier
+ for a direct access opening. Both handle and position are required
+ arguments.
+
+ position is an integer indicating to which point in the file the file
+ access pointer is to be reset. position is either a byte number
+ according to the current byte size being used, or characters for
+ character openings. Position zero is the beginning of the file. If
+ this is a character opening, position is measured in server units,
+ not in NFILE character set units.
+
+ If the FILEPOS command is given on an input data channel (that is, a
+ data channel currently sending data from server to user), the
+ affected data channel must be resynchronized after the FILEPOS is
+ accomplished, in order to identify the start of the new data. The
+ resync-uid is a unique identifier associated with the
+ resynchronization of the data channel; it is unique with respect to
+ this dialogue. resync-uid must be supplied if handle is an input
+ handle, but it is not supplied otherwise. For more information on
+ the resynchronization procedure: See the section "NFILE Data
+ Connection Resynchronization", section 9.2.
+
+ In the output case, the user must somehow indicate to the server, on
+ the output data channel, when there is no more data. The user side
+ sends the keyword token EOF to do so. Upon receiving that control
+
+
+
+Greenberg & Keene [Page 29]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ token, the server is required to position the file pointer according
+ to the position given. When the new file position is established,
+ the server resumes accepting data at the new file position.
+
+ In most cases, using the direct access mode of transfer is more
+ convenient and efficient than repeated use of FILEPOS with a data
+ stream opening.
+
+ There are problems inherent in trying to set a file position of a
+ character-oriented file on a foreign host, if one machine is a
+ Symbolics computer and the other is not. For example, character set
+ translation must take place. See the section "NFILE Character Set",
+ section 6. Because of these difficulties, FILEPOS might not be
+ supported in the future on character files. FILEPOS is not
+ problematic for binary files.
+
+8.15.1 Implementation Hint for FILEPOS Command
+
+ The server processing of this command (by the control connection
+ handler) must not attempt to wait for the resynchronization procedure
+ to complete. It is possible that the user could abort between
+ sending the FILEPOS command and reading for the mark and
+ resynchronization identifier. That scenario could leave the sender
+ of the resynchronization identifier, on the server side, blocked for
+ output indefinitely.
+
+ Only two commands received on the control connection can break the
+ data channel out of the blocked state described above: CLOSE with
+ abort-p supplied as Boolean truth, and RESYNCHRONIZE-DATA-CHANNEL.
+ Therefore, the control connection must not wait for the data channel
+ to finish performing the resynchronization procedure. This wait
+ should instead be performed by the process managing the data channel.
+
+8.16 FINISH Command
+
+ Command: (FINISH tid handle)
+
+ Response: (FINISH tid truename binary-p other-properties)
+
+ FINISH closes a file and reopens it immediately with the file
+ position pointer saved, thus leaving it open for further I/O. If
+ possible, the implementation should do the closing and opening in an
+ indivisible operation, such that no other process can get access to
+ the file.
+
+
+
+
+
+
+
+Greenberg & Keene [Page 30]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The arguments, results, and their meaning are identical to those of
+ the CLOSE command. See the section "CLOSE Command", section 8.3.
+ FINISH requires a handle, which has the same meaning as the handle of
+ the CLOSE command.
+
+ In the output case, for both direct mode and data stream mode of
+ openings, the server writes out all buffers and sets the byte count
+ of the file. The user sends the keyword token EOF on the data
+ channel, to indicate that the end of data has been reached. The
+ server leaves the file in such a state that if the system or server
+ crashes anytime after the FINISH command has completed, it would
+ later appear as though the file had been closed by this command.
+ However, the file is not left in a closed state now; it is left open
+ for further I/O operations. FINISH is a reliability feature.
+
+ FINISH is somewhat pointless in the input case, but valid. The
+ native Symbolics file system (LMFS) implements FINISH on an output
+ file by an internal operation that effectively goes through the work
+ of closing but leaves the file open for appending.
+
+ ERRORS ON FINISH
+
+ After writing every last bit sent by the user to disk, and before
+ closing the file, the server checks the data channel specified by
+ handle to see if an asynchronous error is outstanding on that
+ channel. That is, the server must determine whether it has sent an
+ asynchronous error to the user, to which the user has not yet
+ responded with a CONTINUE command. If so, the server is unable to
+ finish the file, and it must send a command error response response,
+ indicating that an error is pending on the channel. The appropriate
+ three-letter error code is EPC. See the section "NFILE Errors and
+ Notifications", section 10.
+
+8.17 HOME-DIRECTORY Command
+
+ Command: (HOME-DIRECTORY tid user)
+
+ Response: (HOME-DIRECTORY tid directory-pathname)
+
+ HOME-DIRECTORY returns the full pathname of the home directory on the
+ server machine for the given user.
+
+ user is a string that should be recognizable as a user's login name
+ on the server operating system. directory-pathname is a string in
+ the directory pathname format. See the section "Syntax of File and
+ Directory Pathname Arguments", section 7.4.
+
+
+
+
+
+Greenberg & Keene [Page 31]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+8.18 LOGIN Command
+
+ Command: (LOGIN tid user password FILE-SYSTEM USER-VERSION)
+
+ Response: (LOGIN tid keyword/value-pairs)
+
+ LOGIN logs the given user in to the server machine, using the
+ password if necessary. Both user and password are string arguments;
+ user is required, password is optional. An omitted password is valid
+ if the host allows the specified user to log in without a password.
+ Depending on the operating system and server, it might be necessary
+ to log in to run a program (in this case the NFILE server program) on
+ the host. LOGIN establishes a user identity that is used by the
+ operating system to establish the file author and determine file
+ access rights during the current session.
+
+ The server has the option to reject with an error any command except
+ LOGIN if a successful LOGIN command has not been performed. This is
+ recommended. Many operating systems perform the login function in a
+ different process and/or environment than user programs. The portion
+ of the NFILE server running in the special login environment could
+ conceivably be capable only of processing the LOGIN command; this is
+ the reason for having the LOGIN command in NFILE.
+
+ FILE-SYSTEM and USER-VERSION are optional keyword/value pairs. The
+ FILE-SYSTEM keyword/value pair selects the identity of the file
+ system to which all following commands in this session are to be
+ directed. This argument has meaning only if the server host machine
+ has multiple file systems, and the targeted file system is other than
+ the default file system that a user would get by initiating a
+ dialogue with that host. The FILE-SYSTEM argument is an arbitrary
+ token list. If the server does not recognize it, the server gives an
+ appropriate command error response.
+
+ Currently, the only use of FILE-SYSTEM is for Symbolics servers to
+ select one of the front-end processor hosts instead of the LMFS,
+ which is the default. In this case, the first element in the token
+ list is the keyword FEP, and the second element in the token list is
+ an integer, indicating the desired FEP disk unit number. If the
+ server discovers there is no such file system, the server gives a
+ command error response including the three-letter code NFS, meaning
+ "no file system". See the section "NFILE Errors and Notifications",
+ section 10.
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 32]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The user tells the server what version of NFILE it is running by
+ including the optional USER-VERSION keyword/value pair. The value
+ associated with USER-VERSION can be a string, an integer, or a token
+ list. This document describes NFILE user version 2 and server
+ version 2.
+
+ Upon receiving the representation of the user version, the server can
+ either adjust certain parameters to handle this particular version,
+ or simply ignore the user version altogether. Currently, the only
+ released versions of NFILE are user version 2 and server version 2.
+
+ LOGIN RETURN VALUES: keyword/value-pairs
+
+ The keyword/value-pairs is a token list composed of keywords followed
+ by their values. The server includes any or all of the following
+ keywords and their values; they are all optional. The following
+ keywords are recognized:
+
+ NAME
+
+ The value associated with NAME is a string specifying the user
+ identity, in the server host's terms.
+
+ PERSONAL-NAME
+
+ The value associated with PERSONAL-NAME is a string representing the
+ user's personal name, last name first. For example: "McGillicuddy,
+ Aloysius X.".
+
+ HOMEDIR-PATHNAME
+
+ The value associated with HOMEDIR-PATHNAME is a string in the
+ pathname as directory format, indicating the home directory of the
+ user. See the section "Syntax of File and Directory Pathname
+ Arguments", section 7.4.
+
+ GROUP-AFFILIATION
+
+ The value associated with GROUP-AFFILIATION is a string specifying
+ the group to which the user belongs, when this concept is
+ appropriate.
+
+ SERVER-VERSION
+
+ The value associated with SERVER-VERSION can be a string, an integer,
+ or a token list. The value is a representation of the version of the
+ server is running. Upon receiving the server version, the user can:
+ adjust certain parameters to handle this particular version; accept
+
+
+
+Greenberg & Keene [Page 33]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ the version; or close the connection. Currently, the only released
+ versions of NFILE are user version 2 and server version 2.
+
+ PROPERTY-INDEX-TABLE
+
+ The value associated with PROPERTY-INDEX-TABLE is a token list of
+ keywords. This return value enables the server to inform the user
+ which file properties are meaningful on its file system. The
+ keywords in PROPERTY-INDEX-TABLE can be used by the DIRECTORY command
+ (a user request for information on file properties of a specified
+ directory or directories). The server can specify a certain property
+ by giving an integer that is the index of that file property into the
+ PROPERTY-INDEX-TABLE. This reduces the volume of data sent during
+ directory listings. The first element in PROPERTY-INDEX-TABLE is
+ indexed by the number 0. See the section "DIRECTORY Command",
+ section 8.11.
+
+8.19 MULTIPLE-FILE-PLISTS Command
+
+ Command: (MULTIPLE-FILE-PLISTS tid input-handle paths
+ characters properties)
+
+ Response: (MULTIPLE-FILE-PLISTS tid)
+
+ MULTIPLE-FILE-PLISTS returns file property information of one or more
+ files. The server sends the information in a data structure (the
+ format is described later in this section) on the given input-handle.
+ paths is an embedded token list composed of the pathnames in which
+ the user is interested. Each pathname in this list is a string in
+ the full pathname syntax of the server host. Unlike for the
+ DIRECTORY command, wildcards are not allowed in these pathnames. See
+ the section "Syntax of File and Directory Pathname Arguments",
+ section 7.4.
+
+ characters is either Boolean truth (indicating that each file is a
+ character file), the empty token list (each file is a binary file),
+ or the keyword DEFAULT. DEFAULT indicates that the server itself is
+ to figure out whether a file is a character or binary file. For more
+ information on the meaning of the DEFAULT keyword: See the section
+ "OPEN Command", section 8.20. The value of characters can influence
+ some servers' idea of a file's length.
+
+ properties is a token list of keywords indicating which properties
+ the user wants returned. The server is always free to return more
+ properties than those requested in the properties argument. If
+ properties is supplied as the empty token list, the server should
+ transmit all known properties on the files.
+
+
+
+
+Greenberg & Keene [Page 34]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The server transmits as much of the requested information as possible
+ on the given input-handle. The information is contained in a top-
+ level token list of elements. Each element corresponds with a
+ supplied pathname; the order of the original pathlist must be
+ retained in the returned token list. An element is an empty token
+ list if the corresponding file or any of its containing directories
+ does not exist. The elements that correspond to successfully located
+ files are lists composed of truename followed by any properties.
+ properties are keyword/value pairs. truename is a string in the full
+ pathname syntax of the server host.
+
+ The following example shows TOP-LEVEL-LIST-BEGIN and TOP-LEVEL-LIST-
+ END as parentheses, and LIST-BEGIN and LIST-END with square brackets.
+
+ For example, the user supplied a pathlist argument resembling:
+
+ [file1 file2 file3]
+
+ The server could not locate file1 or file3, but did locate file2, and
+ found the length and author of file2. The top-level token list
+ transmitted by the server is:
+
+ ( [] [ truename-of-file2 LENGTH 381 AUTHOR williams ] [] )
+
+ For further detail on how file properties and values are expressed:
+ See the section "Format of NFILE File Property/Value Pairs", section
+ 7.5.
+
+8.20 OPEN Command
+
+ Command: (OPEN tid handle pathname direction binary-p
+ TEMPORARY RAW SUPER-IMAGE DELETED PRESERVE-DATES
+ SUBMIT DIRECT-FILE-ID ESTIMATED-LENGTH BYTE-SIZE
+ IF-EXISTS IF-DOES-NOT-EXIST)
+
+ Response: (OPEN tid truename binary-p other-properties)
+
+ OPEN opens a file for reading, writing, or direct access at the
+ server host. That means, in general, asking the host file system to
+ access the file and obtaining a file number, pointer, or other
+ quantity for subsequent rapid access to the file; this is called an
+ "opening". See the section "NFILE File Opening Modes", section 5.
+
+ The OPEN command has the most complicated syntax of any NFILE
+ command. The OPEN command has required arguments, an optional
+ argument, and many optional keyword/value pairs. For details on the
+ syntax of each of these parts of the OPEN command: See the section
+ "Conventions Used in This Document", section 7.
+
+
+
+Greenberg & Keene [Page 35]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The following arguments are required: pathname, direction, and
+ binary-p. handle is an optional argument, which must either be
+ supplied or explicitly omitted by means of substituting in its place
+ the empty token list.
+
+ The OPEN command has many optional keyword/value pairs, which encode
+ conceptual arguments to the server file system for the OPEN
+ operation. A detailed description of all the supported OPEN optional
+ keywords is given below.
+
+ The OPEN return values reflect information about the file opened,
+ when the opening is successful. In the case of a probe-type opening,
+ this information is returned when the given file (or link, or
+ directory) exists and is accessible, even though the file (or link,
+ or directory) is not actually opened. For detail on the OPEN return
+ values: See the section "NFILE OPEN Response Return Values", section
+ 8.20.2.
+
+ THE pathname OPEN ARGUMENT
+
+ The pathname is a required argument specifying the file to be opened.
+ pathname is a string in the full pathname syntax of the server host.
+ See the section "Syntax of File and Directory Pathname Arguments",
+ section 7.4.
+
+ For some purposes (for example, when the OPEN argument direction is
+ supplied as PROBE-DIRECTORY), only the directory specified by this
+ pathname is utilized. See the section "NFILE OPEN Optional
+ Keyword/Value Pairs", section 8.20.1.
+
+ THE handle OPEN ARGUMENT
+
+ The handle argument of the OPEN command specifies a data channel to
+ be used for the transfer. Subsequent commands in this session use
+ the same handle to specify this opening. It is the user side's
+ responsibility to ensure that handle refers to an existing and free
+ data channel that does not require resynchronization before use. A
+ handle must be supplied, unless a probe-type opening is desired (that
+ is, the direction is supplied as PROBE, PROBE-DIRECTORY, or PROBE-
+ LINK) or a direct access opening is being requested (that is, a
+ DIRECT-FILE-ID is supplied). In those cases, the empty token list is
+ supplied for handle.
+
+ THE direction OPEN ARGUMENT
+
+ The direction argument must be supplied as one of these keywords:
+ INPUT, OUTPUT, IO, PROBE, PROBE-DIRECTORY, and PROBE-LINK. The
+ meanings of the direction keywords are as follows:
+
+
+
+Greenberg & Keene [Page 36]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ INPUT
+
+ Specifies that the file is to be opened for input server-to-user
+ transfer). To request a direct access opening, supply a value for
+ DIRECT-FILE-ID. If no DIRECT-FILE-ID is supplied, the opening is a
+ data stream opening.
+
+ OUTPUT
+
+ Specifies that the file is to be opened for output user-to-server
+ transfer). To request a direct access opening, supply a value for
+ DIRECT-FILE-ID. If no DIRECT-FILE-ID is supplied, the opening is a
+ data stream opening.
+
+ IO
+
+ Specifies that interspersed input and output will be performed on
+ the file. This is only meaningful in direct access mode. A
+ DIRECT-FILE-ID must also be supplied. See the section "NFILE OPEN
+ Optional Keyword/Value Pairs", section 8.20.1.
+
+ If direction is supplied as PROBE, PROBE-LINK, or PROBE-DIRECTORY,
+ the opening is said to be a probe-type opening. The DIRECT-FILE-ID
+ option is meaningless and an error for probe-type openings. The file
+ handle must be supplied as an empty token list for probe-type
+ openings.
+
+ PROBE
+
+ Specifies that the file is not to be opened at all, but simply
+ checked for existence. If the file does not exist or is not
+ accessible, the error indications and actions are identical to
+ those that would be given for an INPUT opening. If the file does
+ exist, the successful command response contains the same
+ information as it would have if the file had been opened for
+ INPUT. If it is a link, the link is followed to its target.
+
+ PROBE-LINK
+
+ Like PROBE, with one difference. PROBE-LINK specifies that if the
+ pathname is found to refer to a link, that link is not to be
+ followed, and information about the link itself is to be returned.
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 37]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ PROBE-DIRECTORY
+
+ PROBE-DIRECTORY requests information about the directory
+ designated by the pathname argument. In the PROBE-DIRECTORY case,
+ the pathname argument refers to the directory on which information
+ is requested. In all other cases, the pathname refers to a file
+ to be opened. If pathname contains a file name and file type,
+ these parts of the pathname are ignored for PROBE-DIRECTORY
+ openings as long as they are syntactically valid.
+
+ THE binary-p OPEN ARGUMENT
+
+ The value of binary-p affects the mode in which the server opens the
+ file, as well as informing it whether or not character set
+ translation must be performed.
+
+ If binary-p is supplied as the empty token list, the opening is said
+ to be a character opening. The server performs character set
+ translation between its native character set and the NFILE character
+ set. The data is transferred over the data connection one character
+ per eight-bit byte. See the section "NFILE Character Set", section
+ 6.
+
+ If binary-p is supplied as Boolean truth, the opening is said to be a
+ binary opening. The user side supplies the byte size via the BYTE-
+ SIZE option; if not supplied, the default byte size is 16 bits. If
+ byte size is less than 9, the file data is transferred byte by byte.
+ If the byte size is 9 or greater, the server transfers each byte of
+ the file as two eight-bit bytes, low-order first.
+
+ binary-p can also be supplied as the keyword DEFAULT. DEFAULT
+ specifies that the server itself is to determine whether to transfer
+ binary or character data. DEFAULT is meaningful only for input
+ openings; it is an error for OUTPUT, IO, or probe-type openings. For
+ file systems that maintain the innate binary or character nature of a
+ file, the server simply asks the file system which case is in force
+ for the file specified by pathname.
+
+ When binary-p is supplied as DEFAULT, on file systems that do not
+ maintain thisinformation, the server is required to perform a
+ heuristic check for Symbolicsobject fileson the first two 16-bit
+ bytes of the file. If the file isdetermined to be aSymbolics object
+ file, the server performs a BINARY openingwith BYTE-SIZE of16;
+ otherwise, it performs a CHARACTER opening.
+
+
+
+
+
+
+
+Greenberg & Keene [Page 38]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The details of the check are as follows: if the first 16-bit byte is
+ the octal number170023 and the second 16-bit byte is any number
+ between 0 and 77 octal(inclusive), the file is recognized as a
+ Symbolics object file. In any othercase, it is not.
+
+8.20.1 NFILE OPEN Optional Keyword/Value Pairs
+
+ The OPEN command has many optional keyword/value pairs that encode
+ conceptual arguments to the file system for the OPEN operation.
+
+ The following options are used often:
+
+ BYTE-SIZE
+
+ Must be followed by an integer between 1 and 16, inclusive, or the
+ empty token list. BYTE-SIZE is meaningful only for binary
+ openings. BYTE-SIZE can be ignored for probe-type openings. It
+ can be omitted entirely for character openings, but if supplied,
+ must be followed by the empty token list. If binary-p is supplied
+ as DEFAULT, BYTE-SIZE can be omitted entirely, or followed by the
+ empty token list.
+
+ If a binary opening is requested and BYTE-SIZE is not supplied,
+ the assumed value is 16 for output openings. For input binary
+ openings, the default is the host file system's stored conception
+ of the file's byte size (for those hosts that natively support
+ byte size). For file systems that do not natively support
+ natively byte size, the default byte-size on binary input is 16.
+
+ For file systems that maintain the innate byte-size of each file,
+ the server should supply this number to the appropriate operating
+ system interface that performs the semantics of opening the file.
+ For other operating systems, a file written with a given byte size
+ must produce the same bytes in the same order when read with that
+ byte size. In this case, the server or host operating system can
+ choose any packing scheme that complies with this rule.
+
+ Operating systems that do not support byte size must ensure that
+ binary files written from user ends of the current protocol can be
+ read back correctly. However, the server can choose packing
+ schemes that allow all bits of the server host's word to be
+ accessed and concur with other packing schemes used by native host
+ software.
+
+ For example, Multics supports 36 bit words and 9 bit bytes. A
+ packing scheme appropriate for a Multics NFILE server is:
+
+
+
+
+
+Greenberg & Keene [Page 39]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ Byte Size Packing Scheme
+
+ 7, 8, or 9 bits four per 36-bit word
+ 10, 11, or 12 bits three per 36-bit word
+ 13, 14, 15, or 16 bits two per 36-bit word
+
+ In the first packing scheme in the table, native Multics
+ character-oriented software can access each logical byte
+ sequentially. In the last packing scheme, each Symbolics byte is
+ in a halfword, easily accessible and visible in an octal
+ representation. To achieve maximum data transfer rate and access
+ all bits of a Multics word, a byte size of 12 must be specified.
+
+ DELETED
+
+ If supplied as Boolean truth, DELETED specifies that deleted"
+ files are to be treated as though they were not "deleted".
+ DELETED is meaningful only for operating systems that support
+ "soft deletion" and subsequent "undeletion" of files. Other
+ operating systems must ignore this option. Normally, deleted
+ files are not visible to the OPEN operation; this option makes
+ them visible.
+
+ DELETED can also be followed by the empty token list, which has
+ the same effect as omitting the DELETED keyword/value pair
+ entirely. For output openings, DELETED is meaningless and an
+ error if supplied.
+
+ DIRECT-FILE-ID
+
+ If supplied, the DIRECT-FILE-ID indicates that the opening is to
+ be a direct access mode opening. If not supplied, the opening is
+ a data stream opening. The value of DIRECT-FILE-ID is a string
+ generated by the user, that has not been used as a DIRECT-FILE-ID
+ in this dialogue, and does not designate any data channel. The
+ DIRECT-FILE-ID is a unique identifier for the direct access
+ opening. It is used for all operations that identify an opening
+ rather than a data channel. The DIRECT-FILE-ID is used to
+ identify a direct access opening, just as a file handle is used to
+ identify a data stream opening. The PROPERTIES, CLOSE, and RENAME
+ commands use the DIRECT-FILE-ID in this way. There are only two
+ NFILE commands applicable to direct access openings (ABORT and
+ CONTINUE) that do not use the DIRECT-FILE-ID, but use a data
+ channel handle instead.
+
+ PRESERVE-DATES
+
+ If supplied as Boolean truth, PRESERVE-DATES specifies that the
+
+
+
+Greenberg & Keene [Page 40]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ server is to attempt to prevent the operating system from updating
+ the "reference date" or date-time used" of the file. This is
+ meaningful only for input openings, and is an error otherwise.
+
+ The Symbolics operating system invokes this option for operations
+ such as View File in the editor, where it wishes to assert that
+ the user did not "read" the file, but just "looked at it".
+ Servers on operating systems that do not support reference dates
+ or users revising or suppressing update of the reference dates
+ must ignore this option.
+
+ ESTIMATED-LENGTH
+
+ The value of ESTIMATED-LENGTH is an integer estimating the length
+ of the file to be transferred. This option is meaningful and
+ permitted only for output openings. ESTIMATED-LENGTH enables the
+ user end to suggest to the server's file system how long the file
+ is going to be. This can be useful for file systems that must
+ preallocate files or file maps or that accrue performance benefits
+ from knowing this information at nthe time the file is first
+ opened. This estimate, if supplied, is not required to be exact.
+ It is ignored by servers to which it is not useful or interesting.
+ The units of the estimate are characters for character openings,
+ and bytes of the agreed-upon byte size for binary openings. The
+ character units should be server units, if possible, but since
+ this is only an estimate, NFILE character units are acceptable.
+ See the section "NFILE Character Set", section 6.
+
+ IF-EXISTS
+
+ Meaningful only for output openings, ignored otherwise, but not
+ diagnosed as an error. The value of IF-EXISTS is a keyword that
+ specifies the action to Be taken if a file of the given name
+ already exists. The semantics of the values are derived from the
+ Common Lisp specification and repeated here for completeness. If
+ the file does not already exist, the IF-EXISTS option and its
+ value are ignored.
+
+ If the user side does not give the IF-EXISTS option, The action to
+ be taken if a file of the given name already exists depends on
+ whether or not the file system supports file versions. If it
+ does, the default is ERROR (if an explicit version is given in the
+ file pathname) or NEW-VERSION (if the version in the file pathname
+ is the newest version). For file systems not supporting versions,
+ the default is SUPERSEDE. These actions are described below.
+
+
+
+
+
+
+Greenberg & Keene [Page 41]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ IF-EXISTS provides the mechanism for overwriting or appending to
+ files. With the default setting of IF-EXISTS, new files are
+ created by every output opening.
+
+ Operating systems supporting soft deletion can take different
+ actions if a "deleted" file already exists with the same name (and
+ type and version, where appropriate) as a file to be created. The
+ Symbolics file system (LMFS) effectively uses SUPERSEDE, even if
+ not asked to do so. Other servers and file systems are urged to
+ do similarly. Recommended action is to not allow deleted files to
+ prevent successful file creation (with specific version number)
+ even if an IF-EXISTS option weaker than SUPERSEDE, RENAME, or
+ RENAME-AND-DELETE is specified or implied.
+
+ Here are the possible values and their meanings:
+
+ ERROR
+
+ Reports an error.
+
+ NEW-VERSION
+
+ Creates a new file with the same file name but with a larger
+ version number. This is the default when the version component
+ of the filename is newest. File systems without version
+ numbers can implement this by effectively treating it as
+ SUPERSEDE.
+
+ RENAME
+
+ Renames the existing file to some other name and then creates a
+ new file with the specified name. On most file systems, this
+ renaming happens at the time of a successful close.
+
+ RENAME-AND-DELETE
+
+ Renames the existing file to some other name and then deletes
+ it (but does not expunge it, on those systems that distinguish
+ deletion from expunging). Then it creates a new file with the
+ specified name. On most file systems, this renaming happens at
+ the time of a successful close.
+
+ OVERWRITE
+
+ Output operations on the opening destructively modify the
+ existing file. New data replaces old data at the beginning of
+ the file; however, the file is not truncated to length zero
+ upon opening.
+
+
+
+Greenberg & Keene [Page 42]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ TRUNCATE
+
+ Output operations on the opening destructively modify the
+ existing file. The file pointer is initially positioned at the
+ beginning of the file; at that time, TRUNCATE truncates the
+ file to length zero and frees disk storage occupied by it.
+
+ APPEND
+
+ Output operations on the opening destructively modify the
+ existing file. New data is placed at the current end of the
+ file.
+
+ SUPERSEDE
+
+ Supersedes the existing file. This means that the old file is
+ removed or deleted and expunged. The new file takes its place.
+ If possible, the file system does not destroy the old file
+ until the new file is closed, against the possibility that the
+ file will be close-aborted. This differs from NEW-VERSION in
+ that SUPERSEDE creates a new file with the same name as the old
+ one, rather than a file name with a higher version number.
+
+ There are currently no standards on what a server can do if it
+ cannot implement some of these actions.
+
+ IF-DOES-NOT-EXIST
+
+ Meaningful for input openings, never meaningful for probe-type
+ openings, and sometimes meaningful for output openings. IF-DOES-
+ NOT-EXIST takes a value token, which specifies the action to be
+ taken if the file does not already exist. Like IF-EXISTS, it is a
+ derivative of Common Lisp. The default is as follows: If this is
+ a probe-type opening or read opening, or if the IF-EXISTS option
+ is specified as OVERWRITE, TRUNCATE, or APPEND, the default is
+ ERROR. Otherwise, the default is CREATE.
+
+ These are the values for IF-DOES-NOT-EXIST:
+
+ ERROR
+
+ Reports an error.
+
+ CREATE
+
+ Creates an empty file with the specified name and then proceeds
+ as if it already existed.
+
+
+
+
+Greenberg & Keene [Page 43]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The following optional keyword/value pairs are rarely used, if ever:
+
+ RAW
+
+ If supplied as Boolean truth, RAW specifies that character set
+ translation is not to be performed, but that characters are to be
+ transferred intact, without inspection. This option is meaningful
+ only for character openings; it is an error otherwise. It is also
+ an error to supply RAW as Boolean truth for probe-type openings.
+ RAW can also be followed by the empty token list, which has the
+ same effect as if the RAW keyword/value pair were omitted
+ entirely. See the section "RAW Translation Mode", Appendix B.
+
+ SUPER-IMAGE
+
+ If supplied as Boolean truth, SUPER-IMAGE specifies that Rubout
+ quoting is not to be performed. This operation is meaningful only
+ for character openings; it is an error otherwise. It is also an
+ error for probe-type openings. SUPER-IMAGE can also be followed
+ by the empty token list, which has the same effect as if the
+ SUPER-IMAGE keyword/value pair were omitted entirely.
+
+ SUPER-IMAGE mode causes the server to read or write character
+ files where ASCII Rubout characters are a significant part of the
+ file content, not where they are an escape for this protocol.
+ However, other translations must still be performed: See the
+ section SUPER-IMAGE Translation Mode", Appendix C.
+
+ TEMPORARY
+
+ Used by the TOPS-20 server only. TEMPORARY says to use GJ%TMP in
+ the GTJFN. This is useful mainly when writing files, and
+ indicates that the foreign operating system is to treat the file
+ as temporary. See TOPS-20 documentation for more about the
+ implications of this option. Other servers can ignore it. This
+ option is meaningless and an error for input or probe-type
+ openings. TEMPORARY can also be followed by the empty token list,
+ which has the same effect as if the TEMPORARY keyword/value pair
+ were omitted entirely.
+
+ SUBMIT
+
+ SUBMIT is meaningful for output only. If supplied as Boolean
+ truth, SUBMIT causes the server to submit the contents of the file
+ being written to the operating system as a job, after the file is
+ closed. VMS is an example of an operating system that could
+ conveniently support SUBMIT. SUBMIT can also be followed by the
+ empty token list, which has the same effect as if the SUBMIT
+
+
+
+Greenberg & Keene [Page 44]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ keyword/value pair were omitted entirely. Servers that do not
+ implement this option should give an error response if requested
+ to submit a file to the operating system.
+
+8.20.2 NFILE OPEN Response Return Values
+
+ The results of a successful OPEN operation are reported in the
+ command response. Here is the specification of the OPEN response
+ format:
+
+ Response Format:
+
+ (OPEN tid truename binary-p other-properties)
+
+ The return values for OPEN and CLOSE are syntactically identical, but
+ the values can change in the time interval between open and close.
+
+ truename is a string representing the pathname of the file in the
+ full pathname syntax of the server host. It should be determined by
+ the server once it has opened the file, via some request to its
+ operating system. The request can be of the form: "What file
+ corresponds to this JFN, file number, pointer, etc.?" If the
+ operating system supports version numbers, this string always
+ contains an explicit version number. It always contains a directory
+ name, a file name, and so on.
+
+ Some operating systems might not know the truename of an output file
+ until it is closed. It is permissible not to supply an explicit
+ version number in the pathname in the OPEN response in this specific
+ case. On these systems the truename when the file is opened is
+ different than the truename after it has been closed.
+
+ The return value binary-p indicates whether the opening is a binary
+ or character opening. For binary openings, binary-p is supplied as
+ Boolean truth; for character openings it is the empty token list.
+
+ other-properties is a list of keyword/value pairs. other-properties
+ must contain CREATION-DATE and LENGTH. AUTHOR should be included if
+ the server operating system has a convenient mechanism for
+ determining the author of the sfile. The other properties described
+ here can be included if desired.
+
+ AUTHOR
+
+ The value of AUTHOR is a string representing the name of the author
+ of the file. This is some kind of user identifier, whose format is
+ system-specific. As with CREATION-DATE (see below), AUTHOR is
+ supposed to represent the logical determinor of the current data
+
+
+
+Greenberg & Keene [Page 45]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ content of the file, not necessarily the agency that actually created
+ the file.
+
+ BYTE-SIZE
+
+ The byte-size agreed upon via the rules described for the BYTE-SIZE
+ option. The value of BYTE-SIZE is an integer. For details on the
+ ramifications of BYTE-SIZE: See the section "NFILE OPEN Optional
+ Keyword/Value Pairs", section 8.20.1. This parameter is only
+ meaningful for BINARY openings. However, if FILEPOS is returned in
+ the other-properties list, BYTE-SIZE should also be included, even
+ for character openings.
+
+ CREATION-DATE
+
+ The creation date of the file. The date is expressed in Universal
+ Time format, which measures a time as the number of seconds since
+ January 1, 1900, at midnight GMT. Creation date does not necessarily
+ mean the time the file system created the directory entry or records
+ of the file. For systems that support modification or appending to
+ files, it is usually the modification date of the file. Creation
+ date can mean the date that the bit count or byte count of the file
+ was set by an application program.
+
+ Some types of file systems support a user-settable quantity
+ (CREATION-DATE) which the user can set to an arbitrary time, to
+ indicate that the contents of this file were written a long time ago
+ by someone else on another computer. The default value of this
+ quantity, if the user has not set it, is the time someone last
+ modified the information in the file. This quantity, in the OPEN
+ response for an output file, is disregarded by the user side, but
+ nevertheless must be present.
+
+ The Symbolics computer system software uses this quantity as a unique
+ identifier of file contents, for a given file name, type, and
+ version, to prove that a file has not changed since it last recorded
+ this quantity for a file.
+
+ FILEPOS
+
+ An integer giving the position of the logical file pointer, in
+ characters or bytes as appropriate for the type of opening. This is
+ always zero for an input opening and for an output opening creating a
+ new file. For an output opening appending to an existing file,
+ FILEPOS is the number of characters or bytes, as appropriate,
+ currently in the file. This number, for character openings, is
+ measured in server units: See the section "NFILE Character Set",
+ section 6.
+
+
+
+Greenberg & Keene [Page 46]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ LENGTH
+
+ An integer reporting the length of the file, in characters for
+ character openings and in bytes of the agreed-upon size for binary
+ openings. LENGTH should be reported as zero for output openings,
+ even if appending to an existing file. The server usually only knows
+ the length for a character opening in server units; thus, it reports
+ length in server units.
+
+8.21 PROPERTIES Command
+
+ Command: (PROPERTIES tid handle pathname control-keywords
+ properties)
+
+ Response: (PROPERTIES tid property-element settable-properties)
+
+ PROPERTIES requests the property information about one file. The
+ file is identified by the pathname argument or the handle argument,
+ but not both. If pathname is supplied, it is a string in the full
+ pathname syntax of the server host. See the section "Syntax of File
+ and Directory Pathname Arguments", section 7.4.
+
+ If handle is supplied, its value is a string identifying an opening,
+ which implicitly identifies a file. For direct access mode openings,
+ handle must be a direct file identifier.
+
+ control-keywords is reserved in the current design. However, it is a
+ required argument, and must be supplied as the empty token list. Its
+ presence in the NFILE specification allows for future expansion. In
+ the future the value of control-keywords might affect the listing
+ mode.
+
+ properties is a token list of keywords indicating the properties the
+ user wants returned. (In command arguments, properties cannot be
+ specified with integers, such as indices into the Property Index
+ Table). For a list of keywords associated with file properties: See
+ the section "Format of NFILE File Property/Value Pairs", section 7.5.
+
+ The server is always free to return more properties than those
+ requested in the properties argument. If properties is supplied as
+ the empty token list, the server transmits all known properties of
+ the file.
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 47]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ PROPERTIES COMMAND RESPONSE
+
+ The server returns the property information for the given file in the
+ command response. The PROPERTIES command does not use any data
+ channels. If the specified file does not exist or is not accessible,
+ the server signals an error and includes an appropriate three-letter
+ error code in the command error response. See the section "NFILE
+ Errors and Notifications", section 10.
+
+ The return value property-element is a token list. The first element
+ in that token list is the pathname of the file, in the full pathname
+ syntax of the server host. The following elements of the property-
+ element token list are property/value pairs. The server is expected
+ to return several property/value pairs; the number of pairs is not
+ constrained. For further details on file properties and their
+ associated values: See the section "Format of NFILE File
+ Property/Value Pairs", section 7.5.
+
+ The return value settable-properties is a token list of keywords.
+ The number of keywords is not constrained. (Note that integers
+ cannot be used in settable-properties to indicate the file property;
+ keywords are to be used instead.) Each keyword supplied in
+ settable-properties identifies a property considered settable by the
+ server. The server is implicitly guaranteeing a mechanism for
+ changing the properties reported as settable. The user can change
+ any of the settable properties for this file by using the CHANGE-
+ PROPERTIES command. See the section "CHANGE-PROPERTIES Command",
+ section 8.2.
+
+ The following example shows the format of the PROPERTIES command
+ response. Remember that the number of property/value pairs and
+ keywords is not constrained; this example has two property/value
+ pairs and three settable-properties keywords returned:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 48]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ TOP-LEVEL-LIST-BEGIN
+ PROPERTIES - name of the command
+ tid - transaction identifier
+ LIST-BEGIN
+ pathname of file
+ prop1 value1 - file's property/value pairs
+ prop2 value2
+ LIST-END
+ LIST-BEGIN
+ keyword-1 - file's settable properties
+ keyword-2
+ keyword-3
+ LIST-END
+ TOP-LEVEL-LIST-END
+
+ The following example is designed to better show the structure of the
+ top-level token list by depicting TOP-LEVEL-LIST-BEGIN and TOP-
+ LEVEL-LIST-END by parentheses and LIST-BEGIN and LIST-END by square
+ brackets. The indentation and newlines in the example are not part
+ of the token list, but are used here to make the structure of the
+ token list clear.
+
+ (PROPERTIES tid [ pathname prop1 value1 prop2 value2 ...]
+ [ keyword1 keyword2 keyword3 ... ]
+
+8.22 READ Command
+
+ Command: (READ tid direct-file-id input-handle count FILEPOS)
+
+ Response: (READ tid)
+
+ READ requests input data flow for direct access openings. The
+ direct-file-id is the same as the DIRECT-FILE-ID argument that was
+ given when opening the file; it designates the opening from which the
+ characters or bytes are to be transferred. The input-handle
+ specifies which data channel should be used for the transfer of data
+ from server to user. The data channel should have been already
+ established, cannot have been disestablished, and must not currently
+ be in use.
+
+ count is an integer specifying how many bytes (or NFILE characters,
+ as appropriate) to read. count can be supplied as the empty token
+ list, meaning read to the end of the file. If the user specifies the
+ empty token list or a count greater than the number of bytes
+ remaining in the file, the server sends the keyword EOF to mark the
+ end of the file.
+
+
+
+
+
+Greenberg & Keene [Page 49]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ FILEPOS is an optional keyword/value pair. If the keyword FILEPOS is
+ supplied, it must be followed by an integer. Before data is
+ transferred, the opening is positioned to the point specified by the
+ value of FILEPOS. The position of the point is measured in server
+ units for character openings; for binary openings it is measured in
+ binary bytes. See the section "FILEPOS NFILE Command".
+
+ Upon receiving the READ command, the server binds the data channel to
+ the opening and immediately begins transferring data. The server
+ stops when all data has been transferred. After the server sends the
+ last requested byte, it unbinds the data channel, freeing it for
+ other use. When the user side has processed the last byte, the user
+ side assumes that the data channel can now be reused for another data
+ transfer.
+
+8.23 RENAME Command
+
+ Command: (RENAME tid handle pathname to-pathname)
+
+ Response: (RENAME tid from-pathname to-pathname)
+
+ RENAME requests the server to give a file a new name. This is
+ NFILE's interface to the system's native rename operation, with all
+ of its system-specific semantics and constraints.
+
+ Either a handle or a pathname (but not both) specifies the file that
+ is to receive a new name. The argument to-pathname designates that
+ new name. The return value from-pathname gives the full original
+ name of the file, and to-pathname gives the full new name of the
+ file. For systems that support version numbers, the return values
+ can differ in version number from the values of the arguments given
+ to RENAME.
+
+ The arguments pathname and to-pathname and the return values from-
+ pathname and to-pathname are strings in the full pathname syntax of
+ the server host. See the section "Syntax of File and Directory
+ Pathname Arguments", section 7.4.
+
+ If the file to be renamed is specified by a pathname, the file should
+ be renamed immediately. If the file is specified by handle, it is
+ acceptable to wait until close-time to rename the file.
+
+ Some operating systems can rename only within a directory.
+ Nevertheless, the to-pathname of the RENAME must be fully specified;
+ the server on these systems must check for and reject an attempted
+ cross-directory rename.
+
+
+
+
+
+Greenberg & Keene [Page 50]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+8.24 RESYNCHRONIZE-DATA-CHANNEL Command
+
+ The command and response format for this command varies, depending on
+ whether the handle argument indicates an input or output data
+ channel.
+
+ For an Input Handle:
+
+ Command: (RESYNCHRONIZE-DATA-CHANNEL tid handle)
+
+ Response: (RESYNCHRONIZE-DATA-CHANNEL tid identifier)
+
+ For an Output Handle:
+
+ Command: (RESYNCHRONIZE-DATA-CHANNEL tid handle identifier)
+
+ Response: (RESYNCHRONIZE-DATA-CHANNEL tid)
+
+ RESYNCHRONIZE-DATA-CHANNEL begins a prescribed procedure between user
+ and server over the unsafe data channel specified by handle. The
+ resynchronization procedure clears the data channel of any unwanted
+ data, and restores the data channel to a safe state, ready to
+ transfer data again.
+
+ All arguments to RESYNCHRONIZE-DATA-CHANNEL are required.
+
+ For a detailed description of how the user and server coordinate the
+ resynchronization of data channels: See the section "NFILE Data
+ Connection Resynchronization", section 9.2.
+
+8.24.1 Implementation Hints for RESYNCHRONIZE-DATA-CHANNEL Command
+
+ In general, both the user and server should should be implemented
+ with the knowledge that a transmission can be aborted. That is, the
+ receiving side must be careful not to act upon a transmission (that
+ is, to perform any action or side effect) until the transmission has
+ been successfully received in entirety. This protects the user
+ program from the possibility that an abort can occur after a
+ transmission has been partially sent.
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 51]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ RESYNCHRONIZING AN OUTPUT DATA CHANNEL
+
+ The server will probably want to dispatch the looping and reading to
+ the logical data process. Looping reading for the resynchronization
+ identifier in the control connection handler is not a viable option.
+ If the user side fails to send the resynchronization identifier (for
+ example, due to a user abort) the control connection handler can
+ never be broken out of this loop.
+
+ Should the user side send the control connection handler command
+ first, or send the marks and identifiers first?
+
+ Sending the marks first is problematic, because the data channel at
+ the other end might not be reading them (for it has not yet been so
+ instructed by the control connection handler). The user might then
+ become blocked for output, thus prohibiting sending of the
+ RESYNCHRONIZE-DATA-CHANNEL command.
+
+ On the other hand, sending the control connection handler command
+ first requires that the user side can send the marks and identifiers
+ between sending the control connection handler command and receiving
+ a response for it. The response will never come until the marks and
+ identifiers have been successfully received. The user implementation
+ must allow for this one case of a command where a subroutine that
+ "sends a command and waits for a response" is inapplicable.
+
+ RESYNCHRONIZING AN INPUT DATA CHANNEL
+
+ The server control process should dispatch the data process to send
+ the mark, and not wait, lest the data process become blocked for
+ output due to a user abort. The control process must go back to its
+ command loop, to possibly receive a command that might break the data
+ process out of that block.
+
+8.25 UNDATA-CONNECTION Command
+
+ Command: (UNDATA-CONNECTION tid input-handle output-handle)
+
+ Response: (UNDATA-CONNECTION tid)
+
+ UNDATA-CONNECTION explicitly disestablishes a data connection from
+ the user side. The user side has the option of disestablishing data
+ connections at its discretion. There is no place in the protocol
+ where disestablishment of data connections is required, other than at
+ the end of the session, where it is implicit.
+
+
+
+
+
+
+Greenberg & Keene [Page 52]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The data connection to be disestablished is the one designated by the
+ input-handle and output-handle arguments. These two handles must
+ refer to the same data connection.
+
+ It is not permitted to explicitly disestablish a data connection
+ either of whose channels is active. If the session is terminated by
+ the breaking of the control connection, all file handles become
+ meaningless, and the server must close all data connections known to
+ it and close-abort all files opened on behalf of the user during the
+ dialogue.
+
+ In the Symbolics implementation, the user side disestablishes data
+ connections that have not been used for a long time, such as twenty
+ minutes or so.
+
+ For more information about data connections: See the section "NFILE
+ Control and Data Connections", section 4.
+
+9. NFILE RESYNCHRONIZATION PROCEDURE
+
+ Ordinarily, the user side sends NFILE commands to the server side
+ over the control connection; the server side responds to every user
+ command, and file data is transmitted over the data channels. This
+ section describes a resynchronization procedure that takes place when
+ something disturbs the usual course of events.
+
+ First, if the server side aborts while sending or receiving data,
+ nothing can be done to salvage the connection between the two hosts.
+ The control connection and any data channels associated with this
+ connection are broken. This happens rarely, if at all.
+
+ It is not unusual for the user side to abort file operations, either
+ commands or data transfer. On a Symbolics computer, the user can do
+ this by pressing CONTROL-ABORT. An important aspect of any file
+ protocol is the way it handles the situation when the user side
+ aborts file operations.
+
+ An NFILE user side reacts to user side aborts by immediately marking
+ the connection unsafe. When a control connection is unsafe, it must
+ be resynchronized before it can be used again. Data channels can
+ also be marked unsafe, and must also be resynchronized before further
+ use. The resynchronization process rids the connection (whether
+ control or data connection) of bytes of data that are now unwanted,
+ and thus cleans up the channel so it can be used again.
+
+ The resynchronization procedure is somewhat complex, but it fulfills
+ a genuine need. For those interested, a brief design discussion is
+ included as note <3>.
+
+
+
+Greenberg & Keene [Page 53]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+9.1 NFILE Control Connection Resynchronization
+
+ NFILE requires any unsafe control connection to undergo a
+ resynchronization procedure before further use. Therefore, the
+ resynchronization does not necessarily occur immediately after the
+ control connection is marked unsafe. The user side initiates the
+ control connection resynchronization when another operation on the
+ control connection is attempted.
+
+ A "mark" is defined in the context of Byte Stream with Mark: See the
+ section "Discussion of Byte Stream with Mark", section 12.1.
+
+ USER SIDE STEPS: CONTROL CONNECTION RESYNCHRONIZATION
+
+ 1. The user side sends a mark over the control connection to
+ the server.
+
+ 2. The user side sends the ASCII characters USER-RESYNC-DUMMY
+ (as a data token) to the server.
+
+ 3. The user side sends a second mark to the server.
+
+ 4. The user side declares the control connection safe (at the
+ token list level).
+
+ 5. The user side generates and sends a unique data token to
+ the server.
+
+ 6. The user side then waits, expecting to detect a mark
+ followed by the unique data token. The user side reads and
+ discards all tokens and marks until the desired match is
+ found.
+
+ Once the user side detects the mark and unique data token, the
+ control connection has been fully resynchronized, and can be used
+ again.
+
+
+ SERVER SIDE STEPS: CONTROL CONNECTION RESYNCHRONIZATION
+
+ 1. The server side detects a mark. The server is thus alerted
+ that the control connection is unsafe, and that
+ resynchronization is in progress.
+
+ 2. The server continues to read data coming from the user side
+ until it detects the second mark, and the token following
+ it.
+
+
+
+
+Greenberg & Keene [Page 54]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ 3. The server checks to see if the token following the mark is
+ USER-RESYNC-DUMMY. This rare situation occurs if the user
+ aborts during the course of the resynchronization itself.
+ If so, the server side discards the USER-RESYNC-DUMMY
+ token. The control connection is still unsafe, and the
+ user side restarts the resynchronization procedure; the
+ server side therefore begins at Step 2 again.
+
+ 4. If the token following the mark is not USER-RESYNC-DUMMY
+ (this is the expected circumstance), the server should have
+ received a single data token that is the unique data token
+ generated by the user side.
+
+ a. The server sends a mark to the user side.
+
+ b. The server declares the control connection safe (at
+ the token list level).
+
+ c. The server sends the unique data token to the user
+ side.
+
+ 5. If the server detects something following the mark that was
+ neither USER-RESYNC-DUMMY nor a single data token, a
+ protocol error has occurred.
+
+9.2 NFILE Data Connection Resynchronization
+
+ The NFILE data channel resynchronization procedure is similar to the
+ NFILE control connection resynchronization. Both procedures are
+ based on a mark signalling the unsafe condition, then a second mark
+ followed by a unique identifier. One important difference between
+ the two procedures is the circumstances in which they occur. Control
+ connections are put into unsafe states only when the user aborts
+ during control connection I/O operations. Data channels are made
+ unsafe by a larger set of circumstances:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 55]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ - User aborts occur during the file protocol operations that
+ assign and deassign data channels. This is the most common
+ cause of data channels becoming unsafe.
+
+ - A server receives a CLOSE command (with abort-p supplied as
+ Boolean truth) specifying an open file that has not finished
+ transmitting data. That is, file reading is aborted.
+
+ - The ABORT command is issued, causing data channels to be
+ made unsafe.
+
+ - The FILEPOS command is issued, causing the input data
+ channel to become unsafe.
+
+ The resynchronization clears the data channel of unwanted data from
+ aborted operations and puts the data channel in a known state. The
+ data channel resynchronization procedure is invoked when the user
+ side gives the RESYNCHRONIZE-DATA-CHANNEL command over the control
+ connection.
+
+ The following policies can be used to improve response time, but are
+ not required by the NFILE protocol: The user side can initiate
+ resynchronization only if it needs the data channel, having first
+ tried to use a free data channel that does not require
+ resynchronization. Also, the user side can periodically
+ resynchronize all unsafe data channels.
+
+ In giving the RESYNCHRONIZE-DATA-CHANNEL command, the user side
+ indicates which data channel should be resynchronized. Data channels
+ are unidirectional, which means that depending on the direction
+ (either input or output) of the data channel, either the user side or
+ the server side sends the resynchronization data. This is another
+ difference from the resynchronization of the control connection, in
+ which the resynchronization data is always sent by the user side.
+ The resynchronization steps for input data channels are different
+ than the steps for output data channels.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 56]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ INPUT DATA CHANNEL RESYNCHRONIZATION
+
+ 1. The user side gives the RESYNCHRONIZE-DATA-CHANNEL command
+ on the control connection, with only one argument, the
+ handle of the data channel to be resynchronized.
+
+ 2. The server side of the data channel generates a unique
+ identifier, and sends that data token in its regular
+ command response to the user side.
+
+ 3. The server side sends a mark over the data channel.
+
+ 4. The server side sends the unique identifier token over the
+ data channel.
+
+ 5. The user side reads until it detects a mark followed by the
+ unique identifier token. The resynchronization is then
+ complete. The data channel is no longer in an unsafe
+ state.
+
+ OUTPUT DATA CHANNEL RESYNCHRONIZATION
+
+ 1. The user side gives the RESYNCHRONIZE-DATA-CHANNEL command
+ on the control connection, with two arguments: the handle
+ of the data channel to be resynchronized, and a unique
+ identifier that it has just generated.
+
+ 2. The user side of the data channel sends a mark.
+
+ 3. The user side of the data channel sends a dummy identifier
+ token. The dummy identifier can be any token that the
+ server could not interpret as being the unique identifier.
+ One suggestion is the data token DUMMY-IDENTIFIER.
+
+ 4. The server side of the data channel was alerted by the
+ RESYNCHRONIZE-DATA-CHANNEL command that resynchronization
+ is in progress. The server side now reads the data,
+ seeking the first mark.
+
+ 5. The server side reads and discards the first mark and the
+ dummy identifier.
+
+ 6. The user side sends a second mark.
+
+ 7. The user side sends the unique identifier.
+
+ 8. The server side recognizes the mark and the unique
+ identifier that follows, and the resynchronization is
+
+
+
+Greenberg & Keene [Page 57]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ complete. The data channel is no longer in the unsafe
+ state.
+
+10. NFILE ERRORS AND NOTIFICATIONS
+
+ NFILE recognizes two types of errors: command response errors and
+ asynchronous errors. In addition to errors, NFILE supports
+ notifications.
+
+ Command response errors:
+
+ - Signify an error that prevented the successful completion of
+ the command; when such an error occurs, a command response
+ error is sent instead of a normal command response.
+ - Occur frequently in normal operations
+
+ Asynchronous errors:
+
+ - Are not related to any specific command
+ - Are associated with an erring data channel
+ - Typically indicate a problem in the transfer, such as
+ running out of disk space or allocation, or an unreadable
+ disk record
+ - Occur rarely in normal operations
+
+ Notifications:
+
+ - Are not associated with an error
+ - Are sent at the server's discretion
+ - Provide general information, such as a warning that the
+ system is going down
+
+10.1 Notifications From the NFILE Server
+
+ The NFILE server can send asynchronous notifications to the user side
+ over the control connection. The text of the notification contains
+ information of interest to the person using NFILE, such as a warning
+ that the server's operating system will be going down soon.
+ Notifications can come from the server side at any time that the
+ server is not sending something else.
+
+ The format of NFILE notifications is:
+
+ (NOTIFICATION "" text)
+
+ The empty string "" takes the place of a transaction identifier.
+ Notifications are initiated by the server, and are not associated
+ with any transaction originated by the user side.n
+
+
+
+Greenberg & Keene [Page 58]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+10.2 NFILE Command Response Errors
+
+ When an error prevents the successful completion of an NFILE command,
+ a command response error is sent instead of the normal command
+ response. A normal command response indicates success; a command
+ response error indicates failure of the command.
+
+ NFILE command response errors are sent from the server to the user
+ across the control connection as top-level token lists, in this
+ format:
+
+ (ERROR tid three-letter-code error-vars message)
+
+ ERROR is a keyword. The tid is the transaction identifier of the
+ command that encountered this error. The arguments three-letter-
+ code, error-vars, and message are all required.
+
+ The three-letter-code provides the information on what kind of an
+ error was encountered. For a table of the three-letter codes and
+ their meanings: See the section "NFILE Three-letter Error Codes",
+ section 10.4.
+
+ message is a string that is displayed to the human user of the
+ protocol.
+
+ error-vars is a keyword/value list. The three possible keywords are:
+ PATHNAME, OPERATION, and NEW-PATHNAME. Before transmitting an error,
+ the server looks at the type of error to see if it can easily
+ determine the value of any of the keywords. If so, the server
+ includes the keyword/value pair in its error. If not, the
+ keyword/value pair is omitted. The value associated with OPERATION
+ is the keyword naming the NFILE command that failed. The values
+ associated with PATHNAME and NEW-PATHNAME are strings in the full
+ pathname syntax of the server host.
+
+ For example, suppose the server on a file system with hierarchical
+ directories could not access a file because its containing directory
+ did not exist. The command error response would use the PATHNAME
+ keyword to indicate the first directory level that did not exist,
+ instead of the full pathname which was supplied as the command
+ argument. This gives the user side valuable information that it
+ otherwise would not have known.
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 59]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+10.3 NFILE Asynchronous Errors
+
+ When a data channel process, in either direction, encounters an error
+ condition, the server sends an asynchronous error description. An
+ asynchronous error description consists of a top-level token list.
+ Typically, asynchronous errors indicate error conditions in the
+ transfer, such as running out of disk space or allocation, or a
+ unreadable disk record.
+
+ The format of asynchronous error descriptions is:
+
+ (ASYNC-ERROR handle three-letter-code error-vars message)
+
+ ASYNC-ERROR is a keyword. The handle argument identifies the erring
+ data channel. The arguments three-letter-code, error-vars, and
+ message are all required. Their meanings are the same as in NFILE
+ command error responses: See the section "NFILE Command Response
+ Errors", section 10.2.
+
+ When the server detects an asynchronous error on an input data
+ channel, the server sends an asynchronous error description on that
+ data channel itself. When an asynchronous error occurs on an output
+ data channel, the asynchronous error description is sent on the
+ control connection.
+
+ Some asynchronous errors are restartable. In this context,
+ restartable means it makes sense to try to resume the operation. One
+ example of a restartable error is an attempt to write a file to a
+ file system that is out of room. The server side indicates whether
+ an asynchronous error is restartable by prepending the keyword
+ RESTARTABLE and the associated value Boolean truth to the error-vars
+ list. To proceed from a restartable error, the user side sends a
+ CONTINUE command over the control connection.
+
+ On any asynchronous error, either input or output, the data channel
+ on the server side enters an "asynchronous error outstanding" state.
+ The server can exit that state in one of two ways: by receiving a
+ CONTINUE command or a CLOSE command with the abort-p argument
+ supplied as Boolean truth.
+
+ On a normal CLOSE (not a close-abort), the server side checks the
+ channel it was requested to close. If an asynchronous error
+ description has been sent on the data channel, but not yet processed
+ by CONTINUE, the server side does not close the channel, but sends a
+ command error response. The same thing happens on a FINISH command
+ received on a channel that has an asynchronous error pending. In
+ both cases, the three-letter code included in the command error
+ response is EPC, for Error Pending on Channel.
+
+
+
+Greenberg & Keene [Page 60]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+10.4 NFILE Three-letter Error Codes
+
+ Usually the server's operating system provides some description of an
+ error that occurs. NFILE has a mechanism for conveying that
+ information to the user side. Upon detecting an error, the NFILE
+ server should characterize the error by choosing the three-letter
+ code that best describes the error. The three-letter code is an
+ argument in both the command response error and asynchronous error
+ messages from the server to the user.
+
+ Each of the NFILE three-letter codes represents some system error.
+ The set of codes enables all operating systems to use one error-
+ reporting mechanism. Some operating systems will never encounter
+ certain of the error conditions.
+
+ Some errors fit logically into two error codes. For example, suppose
+ the server could not delete a file because the file was not found.
+ This error could be considered either CDF (Cannot Delete File) or FNF
+ (File Not Found). In this case, File Not Found gives more specific
+ and valuable information than Cannot Delete File. Since the protocol
+ does not allow more than one error code to be reported when an error
+ occurs, the server must choose the most appropriate error code, given
+ the information available to it from the operating system.
+
+ This is the set of three-letter codes:
+
+ ACC Access error. This indicates a protection-violation error.
+
+ ATD Incorrect access to directory. A directory could not be
+ accessed because the user's access rights to it did not
+ permit this type of access.
+
+ ATF Incorrect access to file. A file could not be accessed
+ because the user's access rights to it did not permit this
+ type of access.
+
+ BUG File system bug. This includes all protocol violations
+ detected by the server, as well as by the host file system.
+
+ CCD Cannot create directory. An error occurred in attempting to
+ create a directory.
+
+ CDF Cannot delete file. The file system reported that it cannot
+ delete a file.
+
+ CCL Cannot create link. An error occurred in attempting to
+ create a link.
+
+
+
+
+Greenberg & Keene [Page 61]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ CIR Circular link. An operation was attempted on a pathname that
+ designates a link that eventually links back to itself.
+
+ CRF Cannot rename file. An error occurred in attempting to
+ rename a file.
+
+ CSP Cannot set property. An error occurred in attempting to
+ change the properties of a file. This could mean that you
+ tried to set a property that only the file system is allowed
+ to set, or a property that is not defined on this type of
+ file system.
+
+ DAE Directory already exists. A directory could not be created
+ because a directory or file of this name already exists.
+
+ DAT Data error. The file system contains unreadable data. This
+ could mean data errors detected by hardware or inconsistent
+ data inside the file system.
+
+ DEV Device not found. The device of the file was not found or
+ does not exist.
+
+ DND "Do Not Delete" flag set. An attempt was made to delete a
+ file that is marked by a "Do Not Delete" flag.
+
+ DNE Directory not empty. An invalid deletion of a nonempty
+ directory was attempted.
+
+ DNF Directory not found. The directory was not found or does not
+ exist. This refers specifically to the containing directory;
+ if you are trying to access a directory, and the actual
+ directory you are trying to access is not found, FNF (for
+ File Not Found) should be indicated instead.
+
+ EPC Error pending on channel. The server cannot close the
+ channel in attempting to close or finish the channel.
+
+ FAE File already exists. The file could not be created because a
+ file or directory of this name already exists.
+
+ FNF File not found. The file was not found in the containing
+ directory. The TOPS-20 and TENEX "no such file type" and "no
+ such file version" errors should also report this condition.
+
+ FOO File open for output. Opening a file that was already opened
+ for output was attempted.
+
+ FOR Filepos out of range. Setting the file pointer past the
+
+
+
+Greenberg & Keene [Page 62]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ end-of-file position or to a negative position was attempted.
+
+ FTB File too big. File is larger than the maximum file size
+ supported by the file system.
+
+ HNA Host not available The file server or file system is
+ intentionally denying service to user. This does not mean
+ that the network connection failed; it means that the file
+ system is explicitly not available.
+
+ IBS Invalid byte size. The value of the "byte size" option was
+ not valid.
+
+ ICO Inconsistent options. Some of the options given in this
+ operation are inconsistent with others.
+
+ IOD Invalid operation for directory. The specified operation is
+ invalid for directories, and the given pathname specifies a
+ directory, in directory pathname as file format.
+
+ IOL Invalid operation for link. The specified operation is
+ invalid for links, and this pathname is the name of a link.
+
+ IP? Invalid password. The specified password was invalid.
+
+ IPS Invalid pathname syntax. This includes all invalid pathname
+ syntax errors.
+
+ IPV Invalid property value. The new value provided for the
+ property is invalid.
+
+ IWC Invalid wildcard. The pathname is not a valid wildcard
+ pathname.
+
+ LCK File locked. The file is locked. It cannot be accessed,
+ possibly because it is in use by some other process.
+
+ LIP Login problems. A problem was encountered while trying to
+ log in to the file system.
+
+ MSC Miscellaneous problems.
+
+ NAV Not available. The file or device exists but is not
+ available. Typically, the disk pack is not mounted on a
+ drive, the drive is broken, or the like. Operator
+ intervention is probably required to fix the problem, but
+ retrying the operation is likely to succeed after the problem
+ is solved.
+
+
+
+Greenberg & Keene [Page 63]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ NER Not enough resources. For example, a system limit on the
+ number of open files or network connections has been reached.
+
+ NET Network problem. The file server had some sort of trouble
+ trying to create a new data connection, or perform some other
+ network operation, and was unable to do so.
+
+ NFS No file system. The file system was not available. For
+ example, this host does not have any file systems, or this
+ host's file system cannot be initialized or accessed for some
+ reason, or the file system simply does not exist.
+
+ NLI Not logged in. A file operation was attempted before logging
+ in. Normally the file system interface always logs in before
+ doing any operation, but this problem can occur in certain
+ unusual cases in which logging in has been aborted.
+
+
+ NMR No more room. The file system is out of room. This can mean
+ any of several things:
+
+ - The entire file system is full.
+ - The particular volume involved is full.
+ - The particular directory involved is full.
+ - The user's allocated quota has been exceeded.
+
+ RAD Rename across directories. The devices or directories of the
+ initial and target pathnames are not the same, but on this
+ file system they are required to be.
+
+ REF Rename to existing file. The target name of a rename
+ operation is the name of a file that already exists.
+
+ UKC Unknown operation. An unsupported file system operation was
+ attempted, or an unsupported command was attempted.
+
+ UKP Unknown property. The property is unknown.
+
+ UNK Unknown user. The specified user name is unknown to this
+ host.
+
+ UUO Unimplemented option. An option to a command is not
+ implemented.
+
+ WKF Wrong kind of file. This includes errors in which an invalid
+ operation for a file, directory, or link was attempted.
+
+ WNA Wildcard not allowed.
+
+
+
+Greenberg & Keene [Page 64]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+11. TOKEN LIST TRANSPORT LAYER
+
+ PURPOSE: The Token List Transport Layer is a protocol that
+ facilitates the transmission of simple structured data, such as
+ lists.
+
+11.1 Introduction to the Token List Transport Layer
+
+ The Token List Transport Layer is a general-purpose protocol. The
+ Token List Transport Layer sends "tokens" through its underlying
+ stream. Each token usually represents a simple quantity, such as a
+ string or integer.
+
+ Tokens can be organized into "token lists". Special tokens are
+ provided to denote the starting and ending point of lists. The token
+ list transport layer differentiates between "top-level token lists",
+ which are not contained in other lists, and "embedded token lists",
+ which are contained in other lists. Using lists makes it convenient
+ to send structured records, such as commands and command responses of
+ the client protocol. The top-level token lists provide robustness.
+
+ The Token List Transport Layer is a general term that includes two
+ separate but related subjects: the "token list stream" and the
+ "token list data stream". The token list stream is commonly used for
+ applications that can easily organize the information to be
+ transmitted into tokens and lists. The token list data stream is
+ more appropriate for transmitting a large volume of data that cannot
+ easily be structured into tokens and lists, such as file data, which
+ is simply a sequence of characters or bytes.
+
+ The following table illustrates the main differences between token
+ list streams and token list data streams:
+
+ Token List Data Stream Token List Stream
+ ---------------------- -----------------
+
+ Built on: token list stream Byte Stream with Mark
+
+ Transmits: stream data tokens, token lists
+
+ Example
+ of use: NFILE data channels NFILE control
+ connection
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 65]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ NFILE uses the the Token List Transport Layer, and provides an
+ excellent example of its usefulness. The NFILE commands and command
+ responses are sent over the control connection in a token list
+ stream. File data is sent across each data channel in a token list
+ data stream.
+
+11.2 Token List Stream
+
+11.2.1 Types of Tokens and Token Lists
+
+ All numbers in the token list documentation are represented in
+ decimal notation. Bytes are 8 bits long.
+
+ TYPES OF TOKENS
+
+ Tokens are of the following types:
+
+ 1. Atomic tokens.
+
+ Atomic tokens are of the following subtypes:
+
+ - Data tokens. A data token consists of a sequence of
+ bytes with an effectively infinite maximum length. In
+ some contexts a data token represents a string; in
+ other contexts, a data token is other arbitrary data.
+
+ Each data token is preceded in the token list stream
+ by a representation of its length in bytes.
+
+ Data tokens that are under 200 bytes long are preceded
+ by one byte containing their length in bytes. That
+ is, a data token of 34 bytes is preceded by one byte
+ of value 34.
+
+ Data tokens 200 bytes or over are preceded by the byte
+ known as PUNCTUATION-LONG, of value 201. After the
+ 201 comes a four-byte-long number (least significant
+ byte first) containing the length of the data token
+ that follows.
+
+ - Numeric tokens. A sequence of bytes that represent
+ and encode a nonnegative binary integer. The largest
+ valid integer is 2^63 - 1.
+
+ Numeric tokens are either short integers (less than
+ 256) or long integers (greater than or equal to 256).
+ Short integers are preceded by the byte known as
+ PUNCTUATION-SHORT-INTEGER, of value 206.
+
+
+
+Greenberg & Keene [Page 66]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ Long integers are begun by PUNCTUATION-LONG-INTEGER,
+ of value 207. One byte follows, containing the length
+ (in bytes) of the long integer. The integer itself is
+ next, least significant byte first.
+
+ - Keyword tokens. A sequence of bytes that represent
+ and encode a named identifier of the implemented
+ protocol. Keyword tokens are used by the client
+ protocol to convey a name; the only significance of a
+ keyword token is in its name.
+
+ Each keyword is preceded by the byte known as
+ PUNCTUATION-KEYWORD, of value 208. The data token
+ following PUNCTUATION-KEYWORD represents the name of
+ the keyword as a string. The characters are in
+ upper-case standard ASCII.
+
+ - Boolean truth. A special token that represents the
+ Boolean truth value. This token is known as
+ BOOLEAN-TRUTH, of value 209 <4>.
+
+ 2. Control tokens.
+
+ The token list stream supports four control tokens to delimit token
+ lists, and one padding token.
+
+ TOP-LEVEL-LIST-BEGIN 202 This control token
+ appears at the start of
+ each top-level token list.
+
+ TOP-LEVEL-LIST-END 203 This control token
+ appears at the end of
+ each top-level token list.
+ LIST-BEGIN 204 This control token
+ appears at the start of
+ each embedded token list.
+
+ LIST-END 205 This control token
+ appears at the end of
+ each embedded token list.
+
+ PUNCTUATION-PAD 200 This padding token should
+ be ignored by the token
+ list stream. It can be
+ sent to fill buffers.
+
+
+
+
+
+
+Greenberg & Keene [Page 67]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ TOKEN LISTS
+
+ A token list consists of a sequence of atomic tokens or token lists.
+ Token lists are begun and ended by control tokens that delimit the
+ token lists. There are three types of token lists:
+
+ 1. Top-level token lists.
+
+ Top-level token lists begin with TOP-LEVEL-LIST-BEGIN and
+ end with TOP-LEVEL-LIST-END. Top-level token lists are not
+ contained in other lists.
+
+ 2. Embedded token lists.
+
+ These token lists occur inside other token lists. They
+ begin with LIST-BEGIN and end with LIST-END.
+
+ 3. The empty token list.
+
+ This is a special example of the embedded token list. In
+ some contexts, the empty token list represents Boolean
+ falsity. An embedded empty token list is composed of a
+ LIST-BEGIN followed immediately by a LIST-END. A top-level
+ empty token list is composed of TOP-LEVEL-LIST-BEGIN
+ followed immediately by TOP-LEVEL-LIST-END.
+
+11.2.2 Token List Stream Example
+
+ This section contains an example of some data that can appear on a
+ token list stream. The example is a top-level token list encoding an
+ NFILE DELETE command.
+
+ The DELETE command is composed of the following pieces: a TOP-
+ LEVEL-LIST-BEGIN, the keyword DELETE, a data token containing the
+ transaction identifier, a LIST-BEGIN, a LIST-END, a data token
+ containing a pathname of a file to be deleted, and a TOP-LEVEL-LIST-
+ END. This example uses t105 as the transaction identifier, and
+ /usr/max/temp as the pathname.
+
+ All numbers in this section are expressed in decimal notation.
+
+ The pieces of the command are displayed here in order:
+
+ 1. TOP-LEVEL-LIST-BEGIN
+ 2. The keyword token whose name is DELETE
+ 3. The data token containing the characters: t105
+ 4. LIST-BEGIN
+ 5. LIST-END
+
+
+
+Greenberg & Keene [Page 68]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ 6. The data token containing the characters: /usr/max/temp
+ 7. TOP-LEVEL-LIST-END
+
+ Now, let's translate each piece of the command into the bytes that
+ are transmitted through the token list stream.
+
+ 1. TOP-LEVEL-LIST-BEGIN
+
+ 202 represents TOP-LEVEL-LIST-BEGIN
+
+ 2. The keyword token whose name is DELETE.
+
+ A keyword token is introduced by PUNCTUATION-KEYWORD, which
+ is represented in the token list stream as the byte 208.
+
+ A data token follows, containing the string "DELETE". A
+ data token under 200 bytes long is introduced by one byte
+ containing its length in bytes. The length of this data
+ token is 6 bytes.
+
+ The data token continues with the standard ASCII character
+ set representation of each character in the string DELETE:
+
+ 208 represents PUNCTUATION-KEYWORD
+ 006 represents the length of this data token
+ 068 represents "D"
+ 069 represents "E"
+ 076 represents "L"
+ 069 represents "E"
+ 084 represents "T"
+ 069 represents "E"
+
+ 3. The data token containing the characters: t105
+
+ This data token is begun by its length in bytes (4), and
+ continues with the NFILE character set representation of
+ each character in the string:
+
+ 004 represents the length of this data token
+ 116 represents "t"
+ 049 represents "1"
+ 048 represents "0"
+ 053 represents "5"
+
+ 4. LIST-BEGIN
+
+ 204 represents LIST-BEGIN
+
+
+
+
+Greenberg & Keene [Page 69]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ 5. LIST-END
+
+ 205 represents LIST-END
+
+ 6. The data token containing the characters: /usr/max/temp
+
+ 013 represents length of this data token
+ 047 represents "/"
+ 117 represents "u"
+ 115 represents "s"
+ 114 represents "r"
+ 047 represents "/"
+ 109 represents "m"
+ 097 represents "a"
+ 120 represents "x"
+ 047 represents "/"
+ 116 represents "t"
+ 101 represents "e"
+ 109 represents "m"
+ 112 represents "p"
+
+ 7. TOP-LEVEL-LIST-END
+
+ 203 represents TOP-LEVEL-LIST-END
+
+11.2.3 Mapping of Lisp Objects to Token List Stream Representation
+
+ The Symbolics interface to the token list stream sends Lisp objects
+ through the underlying Byte Stream with Mark and produces Lisp
+ objects on the other end. Not all Lisp objects can be sent in this
+ way. For example, compound objects other than lists are not handled.
+ An appropriate analogy is the sending and reconstruction of list
+ structure via printed representation. These are the types of objects
+ that can be sent, and their representations:
+
+ - Lisp strings are represented as data tokens in the NFILE
+ character set. Only 8-bit strings can be sent <5>.
+
+ - Keyword symbols are represented as keyword tokens. Although
+ identifiable and reconstructable as keyword symbols, only
+ their names are sent. Any properties, bindings, and the
+ like are not sent.
+
+ - T is represented as BOOLEAN-TRUTH.
+
+ - NIL is represented as the empty token list.
+
+ - Lists are represented as token lists. Circular lists cannot
+
+
+
+Greenberg & Keene [Page 70]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ be sent. See the footnote related to the ambiguity between
+
+ NIL and the empty list: See the section "Types of Tokens
+ and Token Lists", section 11.2.1.
+
+ - Integers are represented as numeric tokens. Only
+ nonnegative integers less than 2^63 can be sent.
+
+11.2.4 Aborting and the Token List Stream
+
+ A token list stream accrues the benefits of the abort management
+ policy of the Byte Stream with Mark on which it is built. In order
+ to fully realize this benefit, some simple rules must be obeyed by
+ any implementation of the token list stream.
+
+ The term "transmission" means either an atomic token or a complete
+ top-level token list. A transmission starts with the control token
+ TOP-LEVEL-BEGIN and ends with TOP-LEVEL-END. The top-level token
+ list can contain embedded token lists.
+
+ The interface that writes to the token list stream must be capable of
+ writing the representation of entire transmissions. When this
+ interface is called, it must effectively lock the token list stream,
+ and exclude access by other processes until the entire transmission
+ has been encoded and sent.
+
+ If the sending is aborted while the stream is locked, the stream
+ enters an "unsafe" state. Trying to send data while the stream is
+ unsafe signals an error. The application and the token list stream
+ must send a mark to cause resynchronization, and allow the token list
+ stream to be used again. When the reading side encounters this mark,
+ it resynchronizes itself according to whatever client protocol is in
+ use.
+
+ Similarly, the interface that reads from the token list stream must
+ be capable of reading entire transmissions. When this interface is
+ called, it must lock the stream, excluding access by other processes
+ until the entire transmission has been read.
+
+ If the reading is aborted while the stream is locked, the stream
+ enters an unsafe state. The only exit from this unsafe state is by
+ means of receiving a mark. When the stream is unsafe, the only valid
+ operation that can be performed upon it is "read and discard all
+ tokens until a mark is encountered; read and discard that mark;
+ declare the stream safe again".
+
+
+
+
+
+
+Greenberg & Keene [Page 71]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ Depending on the client protocol, the receipt of a mark might cause
+ the reading side to read for further marks. NFILE implements the
+ resynchronization of token list streams, and serves as a useful
+ example: See the section "NFILE Control Connection
+ Resynchronization", section 9.1.
+
+ The Symbolics implementation provides the two mark-handling
+ primitives in this way:
+
+
+ 1. Send token (or list) preceded by a mark. When the stream
+ is in the unsafe state (on the output side), this is the
+ only permitted output operation (other than closing).
+
+ 2. Read through to a mark and read the token (or list)
+ following the mark. When the stream is in the unsafe state
+ (on the input side), this is the only permitted input
+ operation (other than closing).
+
+11.3 Token List Data Stream
+
+ The token list data stream is a facility to transmit stream data
+ through a token list stream. The token list data stream imposes the
+ following protocol on the data transmitted:
+
+ - Data is sent in the format of loose data tokens, not
+ contained in token lists.
+
+ - The keyword token EOF indicates that the end of data has
+ been reached.
+
+ - Token lists can be transmitted through the token list
+ data stream.
+
+ - No loose tokens other than data tokens or the keyword
+ token EOF can be sent.
+
+ - Boundaries between data tokens are not signification.
+ The data is considered to be a continuous stream, with
+ the possible exception of marks.
+
+ The token list data stream is most appropriate for sending file data.
+ It is expected (but not required) that its typical mode of use is to
+ send a large number of data tokens, with an occasional token list.
+ The design intent was that token lists would be used by the
+ application program to indicate exceptional situations.
+
+ Data tokens, the keyword token EOF, and token lists are defined in
+
+
+
+Greenberg & Keene [Page 72]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ the token list stream documentation: See the section "Types of
+ Tokens and Token Lists", section 11.2.1.
+
+ The NFILE file protocol provides a good example of the use of token
+ list data streams. NFILE sends file data through token list data
+ streams; each NFILE data channel is a token list data stream. Errors
+ such as disk errors during the reading of a file are conveyed as
+ token lists through the token list data stream.
+
+12. BYTE STREAM WITH MARK
+
+ PURPOSE: Byte Stream with Mark is a simple layer of protocol that
+ guarantees that an out-of-band signal can be transmitted in the case
+ of program interruption. Byte Stream with Mark is designed to
+ provide end-to-end stream consistency in the face of user program
+ aborts.
+
+12.1 Discussion of Byte Stream with Mark
+
+ INTRODUCTION
+
+ Byte Stream with Mark is a reliable, bidirectional byte stream with
+ one out-of-band (but not out-of-sequence) signal called a "mark".
+ The design of Byte Stream with Mark ensures that the mark is always
+ recognizable on the receiving end. The Byte Stream with Mark is
+ built on an underlying stream, which must support the transmission of
+ 8-bit bytes. Byte Stream with Mark has been implemented to run on
+ TCP and Chaos. Marks are implemented differently on the two
+ protocols.
+
+ Marks are used to resynchronize the stream when something has
+ occurred to interrupt normal operations. For example, an application
+ layer sending data over the Byte Stream with Mark can abort in the
+ middle of sending that data. Recovery is handled by sending a mark.
+
+ In the context of this document, "aborting" is defined as follows:
+ Aborting the current execution of a program means to halt that
+ execution and to abandon it, never to complete it. The data
+ representing the state of the execution are irrevocably discarded.
+
+ EXAMPLE OF USE
+
+ Byte Stream with Mark is the layer of protocol underlying NFILE.
+ NFILE uses the marks implemented in Byte Stream with Mark to
+ resynchronize control connections or data channels whose
+ synchronization has been lost. For a description of NFILE's use of
+ marks to resynchronize streams: See the section "NFILE
+ Resynchronization Procedure", section 9.
+
+
+
+Greenberg & Keene [Page 73]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ BYTE STREAM WITH MARK ON CHAOSNET
+
+ A mark is recognized on Chaosnet by a packet bearing the opcode 201
+ (octal). There is no data in a mark packet, so the data portion of
+ the packet is ignored. Byte Stream with Mark transmits all data in
+ packets bearing opcode 200 (octal).
+
+ If Byte Stream with Mark is implemented on another (non-Chaos) stream
+ that supports opcode-bearing packets, the recommended implementation
+ is the reservation of an opcode for the mark.
+
+ BYTE STREAM WITH MARK ON TCP: RECORD MODE
+
+ The purpose of Byte Stream with Mark is to guarantee that marks can
+ always be unambiguously identified. Therefore, for TCP (and for any
+ transport layer that does not implement packets natively) a simple
+ record stream is imposed on the stream. The record boundaries serve
+ only to distinguish where a mark can occur. A record consists of a
+ two-byte byte count, most significant byte first, followed by that
+ many bytes of data. A byte count of zero is recognized as a mark.
+
+ Both the sending side and the receiving side must rigorously maintain
+ the integrity of the record boundaries. A writer to the stream must
+ never output a byte count without that number of data bytes
+ following. Similarly, a reader of the stream, after reading a byte
+ count, has effectively contracted to read that many bytes from the
+ encapsulated stream, regardless of whether those bytes are requested
+ by the application layer.
+
+ MAINTAINING RECORD INTEGRITY
+
+ This subsection deals with maintaining record integrity on non-Chaos
+ networks. Since Chaos implements packets natively, no special care
+ is required to maintain record integrity on the Chaos network.
+
+ The design discussed here guarantees record integrity; the underlying
+ stream must guarantee data integrity.
+
+ The basic design of Byte Stream with Mark on TCP (and other transport
+ layers that do not implement packets natively) is to preserve record
+ integrity by putting clearly demarcated, byte-counted records in the
+ natural records of the encapsulated stream. Therefore, when the
+ outer stream requests a buffer's worth of file data from the
+ encapsulated stream, it expects to receive a buffer containing one
+ entire, ntegral, record of that stream, complete with byte count.
+
+ Because of diverse network implementations on different operating
+ systems, the software that implements the encapsulated stream might
+
+
+
+Greenberg & Keene [Page 74]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ not be able to provide integral record buffers to the Byte Stream
+ with Mark implementation. For example, the writing stream could have
+ written records that are much longer than available buffers on the
+ receiving system. In this case, a request to read from the
+ encapsulated stream returns some buffer or some amount of data
+ representing less than an entire Byte Stream with Mark record. The
+ input subroutine of the Byte Stream with Mark implementation must
+ therefore return a region of this (smaller) buffer, representing less
+ than the full Byte Stream with Mark record. Nevertheless, the Byte
+ Stream with Mark must extract the count of the full Byte Stream with
+ Mark record from the first such buffer of each Byte Stream with Mark
+ record, and maintain and update this count as succeeding component
+ buffers are read.
+
+ In this case, if the program reading from the Byte Stream with Mark
+ aborts while reading data, the implementation of Byte Stream with
+ Mark must continue to read through the remaining buffers of the Byte
+ Stream with Mark record that has been subdivided in this fashion.
+
+ The user side program will have determined that an abort has
+ occurred, and will request the Byte Stream with Mark to read up to
+ and through the next mark. The Byte Stream with Mark will have
+ processed a fractional record, and must discard the remaining buffers
+ of the record now being read.
+
+12.2 Byte Stream with Mark Abortable States
+
+ Byte Stream with Mark is designed to provide end-to-end stream
+ consistency in the face of user program aborts. This section
+ describes user program aborts, and how Byte Stream with Mark handles
+ them. In the context of this document, "aborting" is defined as
+ follows: Aborting the current execution of a program means to halt
+ that execution and to abandon it, never to complete it. The data
+ representing the state of the execution are irrevocably discarded.
+
+ USER PROGRAM ABORTS AND I/O STREAMS
+
+ Aborting the execution of the code that manipulates I/O streams, in
+ general, poses significant problems. Given that a stream is a static
+ data object, and is intended to be used over and over again, aborting
+ the execution of any routine manipulating a stream can leave it in an
+ inconsistent, unusable state.
+
+ Many operating systems solve this problem by manipulating a large
+ subset of streams within the confines of the supervisor or executive
+ program, which is not vulnerable to aborts, short of system or
+ network failure. Nevertheless, the need still exists to implement
+ streams outside of the boundaries of the supervisor. Furthermore,
+
+
+
+Greenberg & Keene [Page 75]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ the Symbolics computer environment has no supervisor or executive
+ program, and is thus vulnerable to aborts everywhere.
+
+ BYTE STREAM WITH MARK HANDLING OF USER PROGRAM ABORTS
+
+ Byte Stream with Mark is designed to be nearly impervious to the
+ aborting of programs using it. Its design is based on careful
+ analysis of all possible states of the stream, and of the effect of
+ aborts of the programs using the stream in each of these states.
+ This section provides that analysis.
+
+ A "transmission" is a collection of user data sent by the application
+ level through the Byte Stream with Mark whose end is well-defined,
+ once its start has been recognized. For instance, the token list
+ stream, when using Byte Stream with Mark, sends token lists. When a
+ TOP-LEVEL-LIST-BEGIN has been sent, the containing transmission is
+ not considered complete until the corresponding TOP-LEVEL-LIST-END is
+ read. See the section "Token List Transport Layer", section 11.
+
+ The following cases are possible states of the stream when an abort
+ occurs:
+
+ 1. Abort occurs when the user program is not manipulating the
+ stream.
+
+ This case presents no problem.
+
+ 2. Abort occurs after a transmission has been partially sent,
+ at a packet or record boundary.
+
+ This implies that the datum that would indicate the
+ successful complete sending of that transmission has been
+ not yet been sent.
+
+ The Byte Stream with Mark state is consistent, but the
+ application level state is not. The application level must
+ determine that the execution of the code composing and
+ sending its transmission was, in fact, aborted, and
+ initiate resynchronization via marks.
+
+ The receiving side must be careful not to act upon a
+ transmission (that is, to perform any action or side
+ effect) until the transmission has been successfully
+ received in entirety. This protects the user program from
+ the possibility that an abort can occur after a
+ transmission has been partially sent.
+
+
+
+
+
+Greenberg & Keene [Page 76]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ 3. Abort occurs during the sending or receiving of a record.
+
+ This is the most vulnerable state of the mechanism. This
+ case does not occur on packet-oriented media; it is
+ subsumed by the next case.
+
+ This case is handled by minimizing the extent of this
+ window, and killing the connection when and if the
+ situation is detected. Depending on the operating system
+ involved, this window could be minimized by using
+ interrupt-disabling mechanisms, auxiliary processes or
+ tasks, or some other technique.
+
+ For buffered streams, input and output waiting can be done
+ in consistent states, thus minimizing the amount of time
+ manipulating the actual encapsulated stream. For
+ unbuffered streams, a lot of time can be spent in this
+ window. It is expected that unbuffered streams will be
+ exceedingly uncommon. Nevertheless, the implementation of
+ Byte Stream with Mark must detect this case.
+
+ 4. Abort occurs during the sending or receiving of fundamental
+ units of the lowest-level underlying stream (packets,
+ buffers, or bytes).
+
+ This case is usually handled by inhibiting interrupts, or
+ other forms of masking, in the code implementing the
+ encapsulated stream, since no waiting is possible at
+ unexpected times.
+
+13. POSSIBLE FUTURE EXTENSIONS
+
+ NFILE was designed to be extended as the needs of its clients grow,
+ or as new clients with different needs appear. Currently it meets
+ the needs of the Symbolics Genera 7.0 operating system, although its
+ design is intentionally general. If users of other operating systems
+ identify new features that would be useful, they could be added to
+ NFILE. This section illustrates some areas areas where the design of
+ NFILE intentionally accommodates extensions.
+
+ - The NFILE protocol encodes commands and responses as text,
+ rather than using prearranged numbers. This means that new
+ commands and responses can be added without having to obtain
+ a new number from a central registry.
+
+ - The Token List Transport Layer provides a general substrate
+ for the value-transmission portion of network protocols. In
+ fact, it has been used at Symbolics for other protocols
+
+
+
+Greenberg & Keene [Page 77]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ besides NFILE. The Token List Transport Layer could
+ conveniently be extended to support transmission of other
+ types of values besides those it currently supports.
+
+ - The character set to be used for file transfer could be made
+ negotiable.
+
+ - The command character set could be made negotiable.
+ Currently there is no negotiation sequence, but one could be
+ added.
+
+ - Greater support for more complex file organizations could be
+ added, such as record files, databases, and so on. This
+ could be an extension to the direct access mode facility.
+
+ - Currently, the LOGIN command allows the user side to inform
+ the server which version of NFILE it is running. This
+ feature is included in NFILE so that a server can continue
+ to support older versions of the protocol even after new,
+ extended versions have been implemented. However, the
+ specification is currently somewhat vague as to how the
+ server can make use of the version.
+
+ - NFILE is not restricted to using TCP or Chaos as its
+ underlying protocol. NFILE can be built on any byte stream
+ protocol that supports reliable transmission of 8-bit bytes
+ and multiple connections.
+
+ In addition to the possible future extensions, we would like to
+ mention a known limitation of NFILE.
+
+ Currently NFILE requires multiple connections for a single session.
+ That is, the control connection must be separate from the data
+ connections. If NFILE is to be used over a telephone, this
+ requirement poses an inconvenient restriction. It is possible to
+ implement a multiplexing scheme as a level between NFILE and the
+ communication medium.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 78]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ APPENDIX A
+ NORMAL TRANSLATION MODE
+
+
+ NORMAL translation mode guarantees the following:
+
+ - A file containing characters in the NFILE character set can
+ be written to any NFILE server and read back intact
+ (containing the same characters).
+
+ - A file written by NFILE should not appear as "foreign" to a
+ server operating system unless the file contains NFILE's
+ extended characters. That is, a server file that uses only
+ the subset of the NFILE character set limited to standard
+ ASCII characters (the 95 printing characters, and the native
+ representation of return, linefeed, page, backspace, rubout,
+ and tab) can be read and written, with the result being the
+ same data in NFILE characters as exists in server
+ characters.
+
+ In this section, all numbers designating values of character codes
+ are to be interpreted in octal. The notation "x in c1..c2" means
+ "for all character codes x such that c1 <= x <= c2."
+
+ The NFILE character set is an extension of standard ASCII. The 95
+ ASCII printing characters have the same numerical codes in the NFILE
+ character set. Five ASCII non-printing characters have counterparts
+ in the NFILE character set, as shown in the following table. The
+ NFILE character set includes a single Return character, rather than
+ the carriage-return line-feed sequence typically used in ASCII. The
+ NFILE character set does not include the ASCII control characters,
+ other than the five shown in the following table, but does include
+ some additional printing and formatting characters that have no
+ counterparts in ASCII.
+
+ NFILE Standard ASCII
+
+ Rubout: 207 177
+ Backspace: 210 10
+ Tab: 211 11
+ Linefeed: 212 12
+ Page: 214 14
+
+ Note that the NFILE Return character is of code 215. This character
+ includes "going to the next line". This is a notable difference from
+ the convention used in PDP-10 ASCII in which lines are ended by a
+ pair of characters, "carriage return" and "line feed".
+
+
+
+
+Greenberg & Keene [Page 79]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ NORMAL TRANSLATION TO UNIX SERVERS
+
+ The translation given in this table is appropriate for use by UNIX
+ servers, or other servers that use 8-bit bytes to store ASCII
+ characters. Machines with 8-bit bytes usually place the extra NFILE
+ characters in the top half of their character set.
+
+ TABLE 1. TRANSLATIONS FROM NFILE CHARACTERS TO UNIX CHARACTERS
+
+
+ NFILE character UNIX character
+
+ x in 000..007 x
+ x in 010..015 x + 200
+ x in 016..176 x
+ 177 377
+ x in 200..207 x
+ x in 210..211 x - 200
+ 212 015
+ x in 213..214 x - 200
+ 215 012
+ x in 216..376 x
+ 377 177
+
+ TABLE 2. TRANSLATIONS FROM UNIX CHARACTERS TO NFILE CHARACTERS
+
+
+ UNIX character NFILE character
+
+ x in 000..007 x
+ x in 010..011 x + 200
+ 012 215
+ x in 013..014 x + 200
+ 015 212
+ x in 016..176 x
+ 177 377
+ x in 200..207 x
+ x in 210..215 x - 200
+ x in 216..376 x
+ 377 177
+
+ NORMAL TRANSLATION TO PDP-10 FAMILY SERVERS
+
+ The translation given in this table is appropriate for use by PDP-10
+ family servers, or other servers that use 7-bit bytes to store ASCII
+ characters. On the PDP-10 the sequence CRLF, 015 012, represents a
+ new line.
+
+
+
+
+Greenberg & Keene [Page 80]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ The mechanism for this translation on machines with 7-bit bytes is to
+ use the RUBOUT character (octal code 177) as an escape character.
+
+ TABLE 3. TRANSLATIONS FROM NFILE TO PDP-10 CHARACTERS
+
+
+ NFILE character PDP-10 character(s)
+
+ x in 000..007 x
+ x in 010..012 177 x
+ 013 013
+ x in 014..015 177 x
+ x in 016..176 x
+ 177 177 177
+ x in 200..207 177 x - 200
+ x in 210..212 x - 200
+ 213 177 013
+ 214 014
+ 215 015 012
+ x in 216..376 177 x - 200
+ 377 no corresponding code
+
+ These tables might seem confusing at first, but there are some
+ general rules about it that should make it clearer. First, NFILE
+ characters in the range 000..177 are generally represented as
+ themselves, and x in 200..377 is generally represented as 177
+ followed by x - 200. That is, 177 is used to quote the second 200
+ NFILE characters. It was deemed that 177 is a more useful and common
+ character than 377, so 177 177 means 177, and there is no way to
+ describe 377 with PDP-10 ASCII characters. In the NFILE character
+ set, the formatting control characters appear offset up by 200 with
+ respect to standard ASCII. This explains why the preferred mode of
+ expressing 210 (backspace) is 010, and 010 turns into 177 010. The
+ same reasoning applies to 211 (Tab), 212 (Linefeed), 214 (Formfeed),
+ and 215 (Return).
+
+ More special care is needed for the Return character, which is the
+ mapping of the system-dependent representation of "the start of a new
+ line". The NFILE Return (215) is equivalent to 015 012 (CRLF) in
+ some ASCII systems. In the NFILE character set there is no
+ representation
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 81]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ TABLE 4. TRANSLATIONS FROM PDP-10 CHARACTERS TO NFILE CHARACTERS
+
+
+ PDP-10 character NFILE character
+
+ x in 000..007 x
+ x in 010..012 x + 200
+ 013 013
+ 014 214
+ 015 012 215
+ 015 not-012 115
+ x in 016..176 x
+ 177 x in 000..007 x + 200
+ 177 x in 010..012 x
+ 177 013 213
+ 177 x in 014..015 x
+ 177 x in 016..176 x + 200
+ 177 177 177
+
+ of a carriage that doesn't go to a new line, so if there is one in a
+ server file, it must be translated to something else. When
+ converting ASCII characters to NFILE characters, an 015 followed by
+ an 012 therefore turns into a 215. A stray CR is arbitrarily
+ translated into a single M (115).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 82]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ APPENDIX B
+ RAW TRANSLATION MODE
+
+
+ RAW mode means no translation should be performed. In RAW mode the
+ server operating system should treat the file as a character file and
+ use the same data formatting that would be appropriate for a
+ character file, but transfer the actual binary values of the
+ character codes.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 83]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ APPENDIX C
+ SUPER-IMAGE TRANSLATION MODE
+
+
+ SUPER-IMAGE mode is intended for use by PDP-10 family machines only.
+ It is included largely as an illustration of a system-dependent
+ extension. A server machine that has 8-bit bytes should treat
+ SUPER-IMAGE mode the same as NORMAL mode.
+
+ In this section, all numbers designating values of character codes
+ are to be interpreted in octal. The notation "x in c1..c2" means
+ "for all character codes x such that c1 <= x <= c2."
+
+ SUPER-IMAGE mode suppresses the use of the 177 character as an escape
+ character. Character translation should be done as in NORMAL mode,
+ with one exception. When a two-character sequence beginning with 177
+ is detected, the 177 should not be output at all.
+
+ In this section, all numbers designating values of character codes
+ are to be interpreted in octal. SUPER-IMAGE mode is intended for use
+ by PDP-10 machines only.
+
+ SUPER-IMAGE suppresses the use of Rubout for quoting. That is, for
+ each entry beginning with a 177 in the PDP-10 character column in the
+ NORMAL translation table, the NFILE character has the 177 removed.
+
+ TABLE 5. SUPER-IMAGE TRANSLATION FROM NFILE TO ASCII
+
+
+ NFILE character PDP-10 character(s)
+
+
+ x in 000..177 x
+ x in 200..214 <x - 200>
+ 215 015 012
+ x in 216..376 <x - 200>
+ 377 no corresponding code
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 84]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ TABLE 6. SUPER-IMAGE TRANSLATION FROM ASCII TO NFILE
+
+
+ PDP-10 character NFILE character
+
+
+ x in 000..007 x
+ x in 010..012 x + 200
+ 013 013
+ 014 214
+ 015 012 215
+ 015 not-012 115
+ x in <016..176> x
+ 177 177
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 85]
+
+RFC 1037 NFILE - A File Access Protocol December 1987
+
+
+ NOTES
+
+ 1. NFILE's requirement for using the NFILE character set is
+ recognized as a drawback for non-Symbolics machines. A useful
+ extension to NFILE would be a provision to make the character set
+ negotiable.
+
+ 2. Implementation note: Care must be taken that the freeing is done
+ before the control connection is allowed to process another
+ command, or else the control connection may find the data channel
+ to be falsely indicated as being in use.
+
+ 3. The Symbolics operating system has the policy that whenever the
+ user side is waiting for the server side, a user abort can occur.
+ This user side waiting can occur in any context, such awaiting a
+ response, waiting in the middle of reading network input, or
+ waiting in the middle of transmitting network output. Thus there
+ are no "hung" states.
+
+ 4. Note that the Token List Transport Layer supplies a special token
+ to indicate Boolean truth, but no corresponding token to indicate
+ Boolean falsity. NFILE uses an empty token list to indicate
+ Boolean falsity. The historical reason for this asymmetry is the
+ inability of the Lisp language to differentiate between the empty
+ list and NIL, which is traditionally used to mean Boolean falsity.
+ If the flexibility of both a Boolean falsity and an empty token
+ list were allowed, it would create problems for an operating
+ system that cannot distinguish between the two. This aspect of
+ the protocol is recognized as a concession to the Lisp language.
+ The unfortunate effect is to disallow operating systems to
+ distinguish between Boolean falsity and an empty list.
+
+ 5. No so-called "fat strings" can be sent.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Greenberg & Keene [Page 86]
+ \ No newline at end of file