|
|
|
|
|||||
|
|
|
|||
|
|
|
|
|
|||||||||||||||||||||||||||||||||||||||||
|
|
|
|||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||
[Text version]
Network Working Group
Request for Comments: 1037B. Greenberg
S. Keene
December 1987
- 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 37.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 148.1 ABORT Command 16 8.2 CHANGE-PROPERTIES Command 16 8.3 CLOSE Command 17 8.4 COMPLETE Command 19 8.5 CONTINUE Command 208.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 529.1 NFILE Control Connection Resynchronization 54 9.2 NFILE Data Connection Resynchronization 5510.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 6111.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 7112.1 Discussion of Byte Stream with Mark 73 12.2 Byte Stream with Mark Abortable States 75TABLE 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- Creating links - Listing, creating, and expunging directories - Listing and changing the properties of files - Enabling and disabling access capabilities on a remote hostNFILE 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. 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.
- 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.
An NFILE session is begun when the NFILE user program connects to a remote host and establishes a network connection. This initial connection is the control conection of the dialogue. If TCP is used as the underlying protocol, contact NFILE's well-known port, 59. If Chaos is used, use the contact name "NFILE".
The control connection is the vehicle used by the user to send its commands, and the server to send its command responses. These types of communication occur over the NFILE control connection:
- The user side sends NFILE commands. - The server sends command responses. - The server sends "notifications" and "asynchronous errors". See the section "NFILE Errors and Notifications", section 10. - During resynchronization (a special circumstance) either the user or server sends a mark.All commands, command responses, and other data flowing over the NFILE control connection are transmitted in the format of "top-level token lists". The control connection expects never to receive "loose tokens"; that is, tokens not contained in token lists.
Data connections 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. 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.
- 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".
- 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:
String A data token containing the characters of the string in the NFILE character set.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:
Command: (DATA-CONNECTION tid new-input-handle new-output-handle)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.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.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.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:
The empty token list in the token list stream appears as a LIST-BEGIN followed immediately by a LIST-END.
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:
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:
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).
- 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:
The handle must identify a data channel that is bound to an opening.
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".
Here are some examples of file pathnames, for different server hosts: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:
- 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.
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:
Integers BLOCK-SIZE, BYTE-SIZE, GENERATION-RETENTION-COUNT, LENGTH-IN-BLOCKS, LENGTH-IN-BYTES, DEFAULT-GENERATION-RETENTION-COUNTDate-or-never's REFERENCE-DATE, INCREMENTAL-DUMP-DATE, COMPLETE-DUMP-DATE, DATE-LAST-EXPUNGED, EXPIRATION-DATEKeyword Lists SETTABLE-PROPERTIES, LINK-TRANSPARENCIES, DEFAULT-LINK-TRANSPARENCIESBoolean values DELETED, DONT-DELETE, DONT-DUMP, DONT-REAP, SUPERSEDE-PROTECT, NOT-BACKED-UP, OFFLINE, TEMPORARY, CHARACTERS, DIRECTORYStrings ACCOUNT, AUTHOR, LINK-TO, PHYSICAL-VOLUME, PROTECTION, VOLUME-NAME, PACK-NUMBER, READER, DISK-SPACE-DESCRIPTION, and any keywords not on this listNote 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
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)
- 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.
Response: (CHANGE-PROPERTIES tid)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
Response: (CLOSE tid truename binary-p other-properties)
CLOSE terminates a data transfer, and frees a data channel. The handle must be a data channel handle for a data stream opening, or a direct file identifier for a direct access opening. If a data channel is given, a transfer must be active on that handle. If abort-p is supplied as Boolean truth, the file is close-aborted, as described below.
"Closing the file" has different implications specific to each operating system. It generally implies invalidation of the pointer or logical identifier obtained from the operating system when the file was "opened", and freeing of operating system and/or job resources associated with active file access. For output files, it involves ensuring that every last bit sent by the user has been successfully written to disk. The server should not send a successful response until all these things have completed successfully. In either data stream or direct access mode, the user can request the server to close-abort the file, instead of simply closing it. To close-abort a file means to close it in such a way, if possible, that it is as if the file had never been opened. In the specific case of a file being created, it must appear as if the file had never been created. This might be more difficult to implement on certain operating systems than others, but tricks with temporary names and close-time renamings by the server can usually be used to implement close-abort in these cases. In the case of a file being appended to, close-abort means to forget the appended data.
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.
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.
- 8.4 COMPLETE Command
- Command: (COMPLETE tid string pathname DIRECTION NEW-OK DELETED)
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:
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.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
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.
- 8.6 CREATE-DIRECTORY Command
- Command: (CREATE-DIRECTORY tid pathname property-pairs)
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)
CREATE-LINK creates a link on the remote file system.
pathname is the pathname of the link to be created; target-pathname is the place in the file system to which the link points. Both are required arguments. The return value link-truename names the resulting link.
If a server on a file system that does not support links receives the CREATE-LINK command, it sends a command error response.
The arguments pathname and target-pathname, and the return value link-truename, are all strings in the full pathname syntax of the server host. See the section "Syntax of File and Directory Pathname Arguments", section 7.4.
The required properties argument is a token list of keyword/value pairs. These properties and their values specify certain attributes to be given to the link. The allowable keywords and associated values are operating system dependent; typically they indicate arguments to be given to the native primitive for creating links.
If no property pairs are given in the command, the server should apply a reasonable default set of attributes to the link. See the section "Format of NFILE File Property/Value Pairs", section 7.5.
- 8.8 DATA-CONNECTION Command
- Command: (DATA-CONNECTION tid new-input-handle new-output-handle)
DATA-CONNECTION enablesthe user side to initiate the establishment of a new data connection. The user side supplies two required string arguments, new-input-handle and new-output-handle. These arguments are used by subsequent commands to reference the two data channels that constitute the data connection now being created. new-input- handle describes the server-to-user data channel, and new-output- handle describes the user-to-server channel. new-input-handle and new-output-handle cannot refer to any data channels already in use.
Upon receiving the DATA-CONNECTION command, the server arranges for a logical port (called socket or contact name on some networks) to be made available on the foreign host machine. When the server has made that port available, it must inform the user of its identity. The server relays that information in the command response, in the required connection-identifier, a string. The server then listens on the port named by connection-identifier, and waits for the user side to connect to it.
Upon receiving the success command response, the user side supplies the connection-identifier to the local network implementation, in order to connect to the specified port. The data connection is not fully established until the user side connects successfully to that port. This command is unusual in that the successful command response does not signify the completion of the command; it indicates only that the server has fulfilled its responsibility in the process of establishing a data connection. The connection-identifier informs the user of the correct identity of the logical port that the server has provided. NFILE expects the connection-identifier to be a string. For TCP this string is the port number represented in decimal. For Chaosnet, this string is the contact name. The connection-identifier is used only once; in all subsequent NFILE commands that need to reference either of the data channels that constitute this data connection, the new-input-handle and new-output-handle are used.
For background information: See the section "NFILE Control and Data Connections", section 4.
- 8.9 DELETE Command
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)
DIRECT-OUTPUT starts and stops output data flow for a direct access file opening. DIRECT-OUTPUT explicitly controls binding and unbinding of an output data channel to a direct access opening. direct-handle is a required argument, and output-handle is optional.
If supplied, output-handle is a request to bind an output data channel (indicated by output-handle) to the direct access opening designated by the direct-handle. The specified output data channel must be free. The server binds the data channel and begins accepting data from that connection and writing it to the opening.
If the output-handle is omitted, this is a request to unbind the channel and terminate the active output transfer.
- 8.11 DIRECTORY Command
Command: (DIRECTORY tid input-handle pathname control-keywords properties)DIRECTORY returns a directory listing including the identities and attributes for logically related groups of files, directories, and links. If the command is successful, a single token list containing the requested information is sent over the data channel specified by input-handle, and the data channel is then implicitly freed by both sides <2>. For details on the format of the token list: See the section "NFILE DIRECTORY Data Format", section 8.11.1.
pathname specifies the files that are to be described; it is a string in the full pathname syntax of the server host. See the section "Syntax of File and Directory Pathname Arguments", section 7.4.
The pathname generally contains wildcard characters, in operating- system-specific format, describing potential file name matches. Most operating systems provide a facility that accepts such a pathname and returns information about all files matching this pathname. Some operating systems allow wildcard (potential multiple) matches in the directory or device portions of the pathname; other operating systems do not. There is no clear contract at this time about what is expected of servers on systems that do not allow wildcard matches (or some kinds of wild card matches), when presented with a wildcard.
properties is a token list of keywords that are the names of properties. If properties is omitted or supplied as the empty token list, the server sends along all properties. If any properties are supplied, the user is requesting the server to send only those properties.
control-keywords 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:
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.
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.
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.
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-ENDLIST-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-ENDThe 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
Response: (DISABLE-CAPABILITIES tid cap-1 success-1 cap-2 success-2 cap-3 success-3 ...)DISABLE-CAPABILITIES causes an access capability to be disabled on the server machine. capability is a string naming the capability to be disabled. The meaning of the capability is dependent on the operating system.
The return values cap-1, cap-2, and so on, are strings specifying names of capabilities. If the capability named by cap-1 was successfully disabled, the corresponding success-1 is supplied as Boolean truth; otherwise it is the empty token list. Although the user can specify only one capability to disable, it is conceivable that the result of disabling that particular capability is the disabling of other, related capabilities. That is why the command response can contain information on more than one capability.
- 8.13 ENABLE-CAPABILITIES Command
- Command: (ENABLE-CAPABILITIES tid capability password)}
Response: (ENABLE-CAPABILITIES tid cap-1 success-1 cap-2 success-2 cap-3 success-3 ...)ENABLE-CAPABILITIES causes an access capability to be enabled on the server machine. The password argument is optional, and should be included only if it is needed to enable this particular capability. Both password and capability are strings. The meaning of the capability is dependent on the operating system.
The return values cap-1, cap-2 and so on, are strings specifying names of capabilities. If the capability named by cap-1 was successfully enabled, the corresponding success-1 is supplied as Boolean truth; otherwise it is the empty token list.
Although the user can specify only one capability to enable, it is conceivable that the result of enabling that particular capability is the enabling of other, related capabilities. That is why the command response can contain information on more than one capability.
- 8.14 EXPUNGE Command
EXPUNGE causes the directory specified by pathname to be expunged. Expunging means that any files that have been soft deleted are to be permanently removed.
For file systems that do not support soft deletion, the command is to be ignored; a success command response is sent, but no action is performed on the file system. In this case, the number-of-server- storage-units-freed return value should be omitted.
directory-pathname is a required string argument in the directory pathname format; it must refer to a directory on the server file system, and not to a file. See the section "Syntax of File and Directory Pathname Arguments", section 7.4. The return value server-storage-units-freed is an integer specifying how many records, blocks, or whatever unit is used to measure file storage on the server host system, were recovered. This return value should be omitted if the server does not know how many storage units were freed.
The protocol does not define whether directory-pathname is really a pathname as directory or a wildcard pathname of files to be expunged. The protocol does not define whether or not wildcards are permitted, or required to be supported, in the directory portion of the pathname (representing an implicit request to expunge many directories).
- 8.15 FILEPOS Command
FILEPOS sets the file access pointer to a given position, relative to the beginning of the file. FILEPOS is used to indicate the position of the next byte of data to be transferred.
The handle indicates the file to be affected. handle must be a data channel handle for a data stream opening, or a direct file identifier for a direct access opening. Both handle and position are required arguments.
position is an integer indicating to which point in the file the file access pointer is to be reset. position is either a byte number according to the current byte size being used, or characters for character openings. Position zero is the beginning of the file. If this is a character opening, position is measured in server units, not in NFILE character set units.
If the FILEPOS command is given on an input data channel (that is, a data channel currently sending data from server to user), the affected data channel must be resynchronized after the FILEPOS is accomplished, in order to identify the start of the new data. The resync-uid is a unique identifier associated with the resynchronization of the data channel; it is unique with respect to this dialogue. resync-uid must be supplied if handle is an input handle, but it is not supplied otherwise. For more information on the resynchronization procedure: See the section "NFILE Data Connection Resynchronization", section 9.2.
In the output case, the user must somehow indicate to the server, on the output data channel, when there is no more data. The user side sends the keyword token EOF to do so. Upon receiving that control token, the server is required to position the file pointer according to the position given. When the new file position is established, the server resumes accepting data at the new file position.
In most cases, using the direct access mode of transfer is more convenient and efficient than repeated use of FILEPOS with a data stream opening.
There are problems inherent in trying to set a file position of a character-oriented file on a foreign host, if one machine is a Symbolics computer and the other is not. For example, character set translation must take place. See the section "NFILE Character Set", section 6. Because of these difficulties, FILEPOS might not be supported in the future on character files. FILEPOS is not problematic for binary files.
- 8.15.1 Implementation Hint for FILEPOS Command
- The server processing of this command (by the control connection handler) must not attempt to wait for the resynchronization procedure to complete. It is possible that the user could abort between sending the FILEPOS command and reading for the mark and resynchronization identifier. That scenario could leave the sender of the resynchronization identifier, on the server side, blocked for output indefinitely.
Only two commands received on the control connection can break the data channel out of the blocked state described above: CLOSE with abort-p supplied as Boolean truth, and RESYNCHRONIZE-DATA-CHANNEL. Therefore, the control connection must not wait for the data channel to finish performing the resynchronization procedure. This wait should instead be performed by the process managing the data channel.
- 8.16 FINISH Command
Response: (FINISH tid truename binary-p other-properties)
FINISH closes a file and reopens it immediately with the file position pointer saved, thus leaving it open for further I/O. If possible, the implementation should do the closing and opening in an indivisible operation, such that no other process can get access to the file. The arguments, results, and their meaning are identical to those of the CLOSE command. See the section "CLOSE Command", section 8.3. FINISH requires a handle, which has the same meaning as the handle of the CLOSE command.
In the output case, for both direct mode and data stream mode of openings, the server writes out all buffers and sets the byte count of the file. The user sends the keyword token EOF on the data channel, to indicate that the end of data has been reached. The server leaves the file in such a state that if the system or server crashes anytime after the FINISH command has completed, it would later appear as though the file had been closed by this command. However, the file is not left in a closed state now; it is left open for further I/O operations. FINISH is a reliability feature.
FINISH is somewhat pointless in the input case, but valid. The native Symbolics file system (LMFS) implements FINISH on an output file by an internal operation that effectively goes through the work of closing but leaves the file open for appending.
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
HOME-DIRECTORY returns the full pathname of the home directory on the server machine for the given user.
user is a string that should be recognizable as a user's login name on the server operating system. directory-pathname is a string in the directory pathname format. See the section "Syntax of File and Directory Pathname Arguments", section 7.4.
- 8.18 LOGIN Command
- Command: (LOGIN tid user password FILE-SYSTEM USER-VERSION)
LOGIN logs the given user in to the server machine, using the password if necessary. Both user and password are string arguments; user is required, password is optional. An omitted password is valid if the host allows the specified user to log in without a password. Depending on the operating system and server, it might be necessary to log in to run a program (in this case the NFILE server program) on the host. LOGIN establishes a user identity that is used by the operating system to establish the file author and determine file access rights during the current session.
The server has the option to reject with an error any command except LOGIN if a successful LOGIN command has not been performed. This is recommended. Many operating systems perform the login function in a different process and/or environment than user programs. The portion of the NFILE server running in the special login environment could conceivably be capable only of processing the LOGIN command; this is the reason for having the LOGIN command in NFILE.
FILE-SYSTEM and USER-VERSION are optional keyword/value pairs. The FILE-SYSTEM keyword/value pair selects the identity of the file system to which all following commands in this session are to be directed. This argument has meaning only if the server host machine has multiple file systems, and the targeted file system is other than the default file system that a user would get by initiating a dialogue with that host. The FILE-SYSTEM argument is an arbitrary token list. If the server does not recognize it, the server gives an appropriate command error response.
Currently, the only use of FILE-SYSTEM is for Symbolics servers to select one of the front-end processor hosts instead of the LMFS, which is the default. In this case, the first element in the token list is the keyword FEP, and the second element in the token list is an integer, indicating the desired FEP disk unit number. If the server discovers there is no such file system, the server gives a command error response including the three-letter code NFS, meaning "no file system". See the section "NFILE Errors and Notifications", section 10. The user tells the server what version of NFILE it is running by including the optional USER-VERSION keyword/value pair. The value associated with USER-VERSION can be a string, an integer, or a token list. This document describes NFILE user version 2 and server version 2.
Upon receiving the representation of the user version, the server can either adjust certain parameters to handle this particular version, or simply ignore the user version altogether. Currently, the only released versions of NFILE are user version 2 and server version 2.
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:
The value associated with NAME is a string specifying the user identity, in the server host's terms.
The value associated with PERSONAL-NAME is a string representing the user's personal name, last name first. For example: "McGillicuddy, Aloysius X.".
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.
The value associated with GROUP-AFFILIATION is a string specifying the group to which the user belongs, when this concept is appropriate.
The value associated with SERVER-VERSION can be a string, an integer, or a token list. The value is a representation of the version of the server is running. Upon receiving the server version, the user can: adjust certain parameters to handle this particular version; accept the version; or close the connection. Currently, the only released versions of NFILE are user version 2 and server version 2.
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)MULTIPLE-FILE-PLISTS returns file property information of one or more files. The server sends the information in a data structure (the format is described later in this section) on the given input-handle. paths is an embedded token list composed of the pathnames in which the user is interested. Each pathname in this list is a string in the full pathname syntax of the server host. Unlike for the DIRECTORY command, wildcards are not allowed in these pathnames. See the section "Syntax of File and Directory Pathname Arguments", section 7.4.
characters is either Boolean truth (indicating that each file is a character file), the empty token list (each file is a binary file), or the keyword DEFAULT. DEFAULT indicates that the server itself is to figure out whether a file is a character or binary file. For more information on the meaning of the DEFAULT keyword: See the section "OPEN Command", section 8.20. The value of characters can influence some servers' idea of a file's length.
properties is a token list of keywords indicating which properties the user wants returned. The server is always free to return more properties than those requested in the properties argument. If properties is supplied as the empty token list, the server should transmit all known properties on the files. The server transmits as much of the requested information as possible on the given input-handle. The information is contained in a top- level token list of elements. Each element corresponds with a supplied pathname; the order of the original pathlist must be retained in the returned token list. An element is an empty token list if the corresponding file or any of its containing directories does not exist. The elements that correspond to successfully located files are lists composed of truename followed by any properties. properties are keyword/value pairs. truename is a string in the full pathname syntax of the server host.
The following example shows TOP-LEVEL-LIST-BEGIN and TOP-LEVEL-LIST- END as parentheses, and LIST-BEGIN and LIST-END with square brackets.
For example, the user supplied a pathlist argument resembling:
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:
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)OPEN opens a file for reading, writing, or direct access at the server host. That means, in general, asking the host file system to access the file and obtaining a file number, pointer, or other quantity for subsequent rapid access to the file; this is called an "opening". See the section "NFILE File Opening Modes", section 5.
The OPEN command has the most complicated syntax of any NFILE command. The OPEN command has required arguments, an optional argument, and many optional keyword/value pairs. For details on the syntax of each of these parts of the OPEN command: See the section "Conventions Used in This Document", section 7. The following arguments are required: pathname, direction, and binary-p. handle is an optional argument, which must either be supplied or explicitly omitted by means of substituting in its place the empty token list.
The OPEN command has many optional keyword/value pairs, which encode conceptual arguments to the server file system for the OPEN operation. A detailed description of all the supported OPEN optional keywords is given below.
The OPEN return values reflect information about the file opened, when the opening is successful. In the case of a probe-type opening, this information is returned when the given file (or link, or directory) exists and is accessible, even though the file (or link, or directory) is not actually opened. For detail on the OPEN return values: See the section "NFILE OPEN Response Return Values", section 8.20.2.
The pathname 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 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 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:
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.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.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.
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.Like PROBE, with one difference. PROBE-LINK specifies that if the pathname is found to refer to a link, that link is not to be followed, and information about the link itself is to be returned.PROBE-DIRECTORY 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 value of binary-p affects the mode in which the server opens the file, as well as informing it whether or not character set translation must be performed.
If binary-p is supplied as the empty token list, the opening is said to be a character opening. The server performs character set translation between its native character set and the NFILE character set. The data is transferred over the data connection one character per eight-bit byte. See the section "NFILE Character Set", section 6.
If binary-p is supplied as Boolean truth, the opening is said to be a binary opening. The user side supplies the byte size via the BYTE- SIZE option; if not supplied, the default byte size is 16 bits. If byte size is less than 9, the file data is transferred byte by byte. If the byte size is 9 or greater, the server transfers each byte of the file as two eight-bit bytes, low-order first.
binary-p can also be supplied as the keyword DEFAULT. DEFAULT specifies that the server itself is to determine whether to transfer binary or character data. DEFAULT is meaningful only for input openings; it is an error for OUTPUT, IO, or probe-type openings. For file systems that maintain the innate binary or character nature of a file, the server simply asks the file system which case is in force for the file specified by pathname.
When binary-p is supplied as DEFAULT, on file systems that do not maintain thisinformation, the server is required to perform a heuristic check for Symbolicsobject fileson the first two 16-bit bytes of the file. If the file isdetermined to be aSymbolics object file, the server performs a BINARY openingwith BYTE-SIZE of16; otherwise, it performs a CHARACTER opening. The details of the check are as follows: if the first 16-bit byte is the octal number170023 and the second 16-bit byte is any number between 0 and 77 octal(inclusive), the file is recognized as a Symbolics object file. In any othercase, it is not.
- 8.20.1 NFILE OPEN Optional Keyword/Value Pairs
- The OPEN command has many optional keyword/value pairs that encode conceptual arguments to the file system for the OPEN operation.
The following options are used often:
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: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 wordIn 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.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.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.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.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.Meaningful only for output openings, ignored otherwise, but not diagnosed as an error. The value of IF-EXISTS is a keyword that specifies the action to Be taken if a file of the given name already exists. The semantics of the values are derived from the Common Lisp specification and repeated here for completeness. If the file does not already exist, the IF-EXISTS option and its value are ignored.If the user side does not give the IF-EXISTS option, The action to be taken if a file of the given name already exists depends on whether or not the file system supports file versions. If it does, the default is ERROR (if an explicit version is given in the file pathname) or NEW-VERSION (if the version in the file pathname is the newest version). For file systems not supporting versions, the default is SUPERSEDE. These actions are described below.IF-EXISTS provides the mechanism for overwriting or appending to files. With the default setting of IF-EXISTS, new files are created by every output opening.Operating systems supporting soft deletion can take different actions if a "deleted" file already exists with the same name (and type and version, where appropriate) as a file to be created. The Symbolics file system (LMFS) effectively uses SUPERSEDE, even if not asked to do so. Other servers and file systems are urged to do similarly. Recommended action is to not allow deleted files to prevent successful file creation (with specific version number) even if an IF-EXISTS option weaker than SUPERSEDE, RENAME, or RENAME-AND-DELETE is specified or implied.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.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.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.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.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.Output operations on the opening destructively modify the existing file. New data is placed at the current end of the file.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.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.- The following optional keyword/value pairs are rarely used, if ever:
Creates an empty file with the specified name and then proceeds as if it already existed.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.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.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 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 SUBMITkeyword/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:
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.
The value of AUTHOR is a string representing the name of the author of the file. This is some kind of user identifier, whose format is system-specific. As with CREATION-DATE (see below), AUTHOR is supposed to represent the logical determinor of the current data content of the file, not necessarily the agency that actually created the file.
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.
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.
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.
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.
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 pai