When DIRECTORIES-ONLY is supplied, the server is to list only
directories, not whose pathnames match the supplied pathname, but
whose pathnames expressed as directory pathnames match the
(potentially wildcarded) directory portion of the supplied pathname.
The description of the PROBE-DIRECTORY keyword that can be supplied
as the direction argument of the OPEN command discusses this: See
the section "OPEN Command", section 8.20.
It is not yet established what servers on hosts that do not support
this type of action natively are to do when presented with
DIRECTORIES-ONLY and a pathname with a wildcard directory component.
FAST Speeds up the operation and data transmission by not listing any
properties at all for the files concerned; that is, only the
truenames are returned.
NO-EXTRA-INFO
Specifies that the server is to suppress listing those properties
that are generally more difficult or expensive to obtain. This
typically eliminates listing of directory-specific properties such as
information about default generation counts and expunge dates.
SORTED
This causes the directory listing to be sorted. The sorting is done
alphabetically by directory, then by file name, then file type, then
file version (by increasing version number).
8.11.1 NFILE DIRECTORY Data Format
If the NFILE DIRECTORY command completes successfully, a single token
list containing the requested directory information is sent on the
data channel specified by the input-handle argument in the DIRECTORY
command. This section describes the format of that single token
list, and gives further detail on the properties argument to
DIRECTORY.
The token list is a top-level token list, so it is delimited by TOP-
LEVEL-LIST-BEGIN and TOP-LEVEL-LIST-END. The top-level token list
contains embedded token lists. The first embedded token list
contains the empty token list followed by property/value pairs
describing property information of the file system as a whole rather
than of a specific file. NFILE requires one property of the file
system to be present: DISK-SPACE-DESCRIPTION is a string describing
the amount of free file space available on the system. The following
embedded token lists contain the pathname of a file, followed by
property/value pairs describing the properties of that file.
The following example shows the format of the top-level token list
returned by DIRECTORY, for two files. It is expected that the server
return several property/value pairs for each file; the number of
pairs returned is not constrained. In this example, two
property/value pairs are returned for the file system, two pairs are
returned for the first file, and only one pair is returned for the
second file.
TOP-LEVEL-LIST-BEGIN
LIST-BEGIN - first embedded token list starts
LIST-BEGIN - an empty embedded token list starts
LIST-END - the empty embedded token list ends
prop1 value1 - property/value pairs of file system
prop2 value2
LIST-END
LIST-BEGIN
pathname1 - pathname of the first file
prop1 value1 - property/value pairs of first file
prop2 value2
LIST-END
LIST-BEGIN
pathname2 - pathname of the second file
prop1 value1 - property/value pairs of second file
LIST-END
TOP-LEVEL-LIST-END
The following example is designed to illustrate the structure of the
top-level token list by depicting TOP-LEVEL-LIST-BEGIN and TOP-
LEVEL-LIST-END by parentheses and LIST-BEGIN and LIST-END by squarbe
rackets. respectively. The indentation, blank spaces, and newlines
in the example are not part of the token list, but are used here to
make the structure of the token list clear.
([ [ ] prop1 value1 prop2 value2]
[pathname1 prop1 value1 prop2 value2]
[pathname2 prop1 value1])
The pathname is a string in the full pathname syntax of the server
host. See the section "Syntax of File and Directory Pathname
Arguments", section 7.4.
For further information on file property/value pairs: See the
section "Format of NFILE File Property/Value Pairs", section 7.5.
8.12 DISABLE-CAPABILITIES Command
Command: (DISABLE-CAPABILITIES tid capability)
Response: (DISABLE-CAPABILITIES tid cap-1 success-1
cap-2 success-2 cap-3 success-3 ...)
DISABLE-CAPABILITIES causes an access capability to be disabled on
the server machine. capability is a string naming the capability to
be disabled. The meaning of the capability is dependent on the
operating system.
The return values cap-1, cap-2, and so on, are strings specifying
names of capabilities. If the capability named by cap-1 was
successfully disabled, the corresponding success-1 is supplied as
Boolean truth; otherwise it is the empty token list.
Although the user can specify only one capability to disable, it is
conceivable that the result of disabling that particular capability
is the disabling of other, related capabilities. That is why the
command response can contain information on more than one capability.
8.13 ENABLE-CAPABILITIES Command
Command: (ENABLE-CAPABILITIES tid capability password)}
Response: (ENABLE-CAPABILITIES tid cap-1 success-1
cap-2 success-2 cap-3 success-3 ...)
ENABLE-CAPABILITIES causes an access capability to be enabled on the
server machine. The password argument is optional, and should be
included only if it is needed to enable this particular capability.
Both password and capability are strings. The meaning of the
capability is dependent on the operating system.
The return values cap-1, cap-2 and so on, are strings specifying
names of capabilities. If the capability named by cap-1 was
successfully enabled, the corresponding success-1 is supplied as
Boolean truth; otherwise it is the empty token list.
Although the user can specify only one capability to enable, it is
conceivable that the result of enabling that particular capability is
the enabling of other, related capabilities. That is why the command
response can contain information on more than one capability.
8.14 EXPUNGE Command
Command: (EXPUNGE tid directory-pathname)
Response: (EXPUNGE tid server-storage-units-freed)
EXPUNGE causes the directory specified by pathname to be expunged.
Expunging means that any files that have been soft deleted are to be
permanently removed.
For file systems that do not support soft deletion, the command is to
be ignored; a success command response is sent, but no action is
performed on the file system. In this case, the number-of-server-
storage-units-freed return value should be omitted.
directory-pathname is a required string argument in the directory
pathname format; it must refer to a directory on the server file
system, and not to a file. See the section "Syntax of File and
Directory Pathname Arguments", section 7.4.
The return value server-storage-units-freed is an integer specifying
how many records, blocks, or whatever unit is used to measure file
storage on the server host system, were recovered. This return value
should be omitted if the server does not know how many storage units
were freed.
The protocol does not define whether directory-pathname is really a
pathname as directory or a wildcard pathname of files to be expunged.
The protocol does not define whether or not wildcards are permitted,
or required to be supported, in the directory portion of the pathname
(representing an implicit request to expunge many directories).
8.15 FILEPOS Command
Command: (FILEPOS tid handle position resync-uid)
Response: (FILEPOS tid)
FILEPOS sets the file access pointer to a given position, relative to
the beginning of the file. FILEPOS is used to indicate the position
of the next byte of data to be transferred.
The handle indicates the file to be affected. handle must be a data
channel handle for a data stream opening, or a direct file identifier
for a direct access opening. Both handle and position are required
arguments.
position is an integer indicating to which point in the file the file
access pointer is to be reset. position is either a byte number
according to the current byte size being used, or characters for
character openings. Position zero is the beginning of the file. If
this is a character opening, position is measured in server units,
not in NFILE character set units.
If the FILEPOS command is given on an input data channel (that is, a
data channel currently sending data from server to user), the
affected data channel must be resynchronized after the FILEPOS is
accomplished, in order to identify the start of the new data. The
resync-uid is a unique identifier associated with the
resynchronization of the data channel; it is unique with respect to
this dialogue. resync-uid must be supplied if handle is an input
handle, but it is not supplied otherwise. For more information on
the resynchronization procedure: See the section "NFILE Data
Connection Resynchronization", section 9.2.
In the output case, the user must somehow indicate to the server, on
the output data channel, when there is no more data. The user side
sends the keyword token EOF to do so. Upon receiving that control
token, the server is required to position the file pointer according
to the position given. When the new file position is established,
the server resumes accepting data at the new file position.
In most cases, using the direct access mode of transfer is more
convenient and efficient than repeated use of FILEPOS with a data
stream opening.
There are problems inherent in trying to set a file position of a
character-oriented file on a foreign host, if one machine is a
Symbolics computer and the other is not. For example, character set
translation must take place. See the section "NFILE Character Set",
section 6. Because of these difficulties, FILEPOS might not be
supported in the future on character files. FILEPOS is not
problematic for binary files.
8.15.1 Implementation Hint for FILEPOS Command
The server processing of this command (by the control connection
handler) must not attempt to wait for the resynchronization procedure
to complete. It is possible that the user could abort between
sending the FILEPOS command and reading for the mark and
resynchronization identifier. That scenario could leave the sender
of the resynchronization identifier, on the server side, blocked for
output indefinitely.
Only two commands received on the control connection can break the
data channel out of the blocked state described above: CLOSE with
abort-p supplied as Boolean truth, and RESYNCHRONIZE-DATA-CHANNEL.
Therefore, the control connection must not wait for the data channel
to finish performing the resynchronization procedure. This wait
should instead be performed by the process managing the data channel.
8.16 FINISH Command
Command: (FINISH tid handle)
Response: (FINISH tid truename binary-p other-properties)
FINISH closes a file and reopens it immediately with the file
position pointer saved, thus leaving it open for further I/O. If
possible, the implementation should do the closing and opening in an
indivisible operation, such that no other process can get access to
the file.
The arguments, results, and their meaning are identical to those of
the CLOSE command. See the section "CLOSE Command", section 8.3.
FINISH requires a handle, which has the same meaning as the handle of
the CLOSE command.
In the output case, for both direct mode and data stream mode of
openings, the server writes out all buffers and sets the byte count
of the file. The user sends the keyword token EOF on the data
channel, to indicate that the end of data has been reached. The
server leaves the file in such a state that if the system or server
crashes anytime after the FINISH command has completed, it would
later appear as though the file had been closed by this command.
However, the file is not left in a closed state now; it is left open
for further I/O operations. FINISH is a reliability feature.
FINISH is somewhat pointless in the input case, but valid. The
native Symbolics file system (LMFS) implements FINISH on an output
file by an internal operation that effectively goes through the work
of closing but leaves the file open for appending.
ERRORS ON FINISH
After writing every last bit sent by the user to disk, and before
closing the file, the server checks the data channel specified by
handle to see if an asynchronous error is outstanding on that
channel. That is, the server must determine whether it has sent an
asynchronous error to the user, to which the user has not yet
responded with a CONTINUE command. If so, the server is unable to
finish the file, and it must send a command error response response,
indicating that an error is pending on the channel. The appropriate
three-letter error code is EPC. See the section "NFILE Errors and
Notifications", section 10.
8.17 HOME-DIRECTORY Command
Command: (HOME-DIRECTORY tid user)
Response: (HOME-DIRECTORY tid directory-pathname)
HOME-DIRECTORY returns the full pathname of the home directory on the
server machine for the given user.
user is a string that should be recognizable as a user's login name
on the server operating system. directory-pathname is a string in
the directory pathname format. See the section "Syntax of File and
Directory Pathname Arguments", section 7.4.
8.18 LOGIN Command
Command: (LOGIN tid user password FILE-SYSTEM USER-VERSION)
Response: (LOGIN tid keyword/value-pairs)
LOGIN logs the given user in to the server machine, using the
password if necessary. Both user and password are string arguments;
user is required, password is optional. An omitted password is valid
if the host allows the specified user to log in without a password.
Depending on the operating system and server, it might be necessary
to log in to run a program (in this case the NFILE server program) on
the host. LOGIN establishes a user identity that is used by the
operating system to establish the file author and determine file
access rights during the current session.
The server has the option to reject with an error any command except
LOGIN if a successful LOGIN command has not been performed. This is
recommended. Many operating systems perform the login function in a
different process and/or environment than user programs. The portion
of the NFILE server running in the special login environment could
conceivably be capable only of processing the LOGIN command; this is
the reason for having the LOGIN command in NFILE.
FILE-SYSTEM and USER-VERSION are optional keyword/value pairs. The
FILE-SYSTEM keyword/value pair selects the identity of the file
system to which all following commands in this session are to be
directed. This argument has meaning only if the server host machine
has multiple file systems, and the targeted file system is other than
the default file system that a user would get by initiating a
dialogue with that host. The FILE-SYSTEM argument is an arbitrary
token list. If the server does not recognize it, the server gives an
appropriate command error response.
Currently, the only use of FILE-SYSTEM is for Symbolics servers to
select one of the front-end processor hosts instead of the LMFS,
which is the default. In this case, the first element in the token
list is the keyword FEP, and the second element in the token list is
an integer, indicating the desired FEP disk unit number. If the
server discovers there is no such file system, the server gives a
command error response including the three-letter code NFS, meaning
"no file system". See the section "NFILE Errors and Notifications",
section 10.
The user tells the server what version of NFILE it is running by
including the optional USER-VERSION keyword/value pair. The value
associated with USER-VERSION can be a string, an integer, or a token
list. This document describes NFILE user version 2 and server
version 2.
Upon receiving the representation of the user version, the server can
either adjust certain parameters to handle this particular version,
or simply ignore the user version altogether. Currently, the only
released versions of NFILE are user version 2 and server version 2.
LOGIN RETURN VALUES: keyword/value-pairs
The keyword/value-pairs is a token list composed of keywords followed
by their values. The server includes any or all of the following
keywords and their values; they are all optional. The following
keywords are recognized:
NAME
The value associated with NAME is a string specifying the user
identity, in the server host's terms.
PERSONAL-NAME
The value associated with PERSONAL-NAME is a string representing the
user's personal name, last name first. For example: "McGillicuddy,
Aloysius X.".
HOMEDIR-PATHNAME
The value associated with HOMEDIR-PATHNAME is a string in the
pathname as directory format, indicating the home directory of the
user. See the section "Syntax of File and Directory Pathname
Arguments", section 7.4.
GROUP-AFFILIATION
The value associated with GROUP-AFFILIATION is a string specifying
the group to which the user belongs, when this concept is
appropriate.
SERVER-VERSION
The value associated with SERVER-VERSION can be a string, an integer,
or a token list. The value is a representation of the version of the
server is running. Upon receiving the server version, the user can:
adjust certain parameters to handle this particular version; accept
the version; or close the connection. Currently, the only released
versions of NFILE are user version 2 and server version 2.
PROPERTY-INDEX-TABLE
The value associated with PROPERTY-INDEX-TABLE is a token list of
keywords. This return value enables the server to inform the user
which file properties are meaningful on its file system. The
keywords in PROPERTY-INDEX-TABLE can be used by the DIRECTORY command
(a user request for information on file properties of a specified
directory or directories). The server can specify a certain property
by giving an integer that is the index of that file property into the
PROPERTY-INDEX-TABLE. This reduces the volume of data sent during
directory listings. The first element in PROPERTY-INDEX-TABLE is
indexed by the number 0. See the section "DIRECTORY Command",
section 8.11.
8.19 MULTIPLE-FILE-PLISTS Command
Command: (MULTIPLE-FILE-PLISTS tid input-handle paths
characters properties)
Response: (MULTIPLE-FILE-PLISTS tid)
MULTIPLE-FILE-PLISTS returns file property information of one or more
files. The server sends the information in a data structure (the
format is described later in this section) on the given input-handle.
paths is an embedded token list composed of the pathnames in which
the user is interested. Each pathname in this list is a string in
the full pathname syntax of the server host. Unlike for the
DIRECTORY command, wildcards are not allowed in these pathnames. See
the section "Syntax of File and Directory Pathname Arguments",
section 7.4.
characters is either Boolean truth (indicating that each file is a
character file), the empty token list (each file is a binary file),
or the keyword DEFAULT. DEFAULT indicates that the server itself is
to figure out whether a file is a character or binary file. For more
information on the meaning of the DEFAULT keyword: See the section
"OPEN Command", section 8.20. The value of characters can influence
some servers' idea of a file's length.
properties is a token list of keywords indicating which properties
the user wants returned. The server is always free to return more
properties than those requested in the properties argument. If
properties is supplied as the empty token list, the server should
transmit all known properties on the files.
The server transmits as much of the requested information as possible
on the given input-handle. The information is contained in a top-
level token list of elements. Each element corresponds with a
supplied pathname; the order of the original pathlist must be
retained in the returned token list. An element is an empty token
list if the corresponding file or any of its containing directories
does not exist. The elements that correspond to successfully located
files are lists composed of truename followed by any properties.
properties are keyword/value pairs. truename is a string in the full
pathname syntax of the server host.
The following example shows TOP-LEVEL-LIST-BEGIN and TOP-LEVEL-LIST-
END as parentheses, and LIST-BEGIN and LIST-END with square brackets.
For example, the user supplied a pathlist argument resembling:
[file1 file2 file3]
The server could not locate file1 or file3, but did locate file2, and
found the length and author of file2. The top-level token list
transmitted by the server is:
( [] [ truename-of-file2 LENGTH 381 AUTHOR williams ] [] )
For further detail on how file properties and values are expressed:
See the section "Format of NFILE File Property/Value Pairs", section
7.5.
8.20 OPEN Command
Command: (OPEN tid handle pathname direction binary-p
TEMPORARY RAW SUPER-IMAGE DELETED PRESERVE-DATES
SUBMIT DIRECT-FILE-ID ESTIMATED-LENGTH BYTE-SIZE
IF-EXISTS IF-DOES-NOT-EXIST)
Response: (OPEN tid truename binary-p other-properties)
OPEN opens a file for reading, writing, or direct access at the
server host. That means, in general, asking the host file system to
access the file and obtaining a file number, pointer, or other
quantity for subsequent rapid access to the file; this is called an
"opening". See the section "NFILE File Opening Modes", section 5.
The OPEN command has the most complicated syntax of any NFILE
command. The OPEN command has required arguments, an optional
argument, and many optional keyword/value pairs. For details on the
syntax of each of these parts of the OPEN command: See the section
"Conventions Used in This Document", section 7.
The following arguments are required: pathname, direction, and
binary-p. handle is an optional argument, which must either be
supplied or explicitly omitted by means of substituting in its place
the empty token list.
The OPEN command has many optional keyword/value pairs, which encode
conceptual arguments to the server file system for the OPEN
operation. A detailed description of all the supported OPEN optional
keywords is given below.
The OPEN return values reflect information about the file opened,
when the opening is successful. In the case of a probe-type opening,
this information is returned when the given file (or link, or
directory) exists and is accessible, even though the file (or link,
or directory) is not actually opened. For detail on the OPEN return
values: See the section "NFILE OPEN Response Return Values", section
8.20.2.
THE pathname OPEN ARGUMENT
The pathname is a required argument specifying the file to be opened.
pathname is a string in the full pathname syntax of the server host.
See the section "Syntax of File and Directory Pathname Arguments",
section 7.4.
For some purposes (for example, when the OPEN argument direction is
supplied as PROBE-DIRECTORY), only the directory specified by this
pathname is utilized. See the section "NFILE OPEN Optional
Keyword/Value Pairs", section 8.20.1.
THE handle OPEN ARGUMENT
The handle argument of the OPEN command specifies a data channel to
be used for the transfer. Subsequent commands in this session use
the same handle to specify this opening. It is the user side's
responsibility to ensure that handle refers to an existing and free
data channel that does not require resynchronization before use. A
handle must be supplied, unless a probe-type opening is desired (that
is, the direction is supplied as PROBE, PROBE-DIRECTORY, or PROBE-
LINK) or a direct access opening is being requested (that is, a
DIRECT-FILE-ID is supplied). In those cases, the empty token list is
supplied for handle.
THE direction OPEN ARGUMENT
The direction argument must be supplied as one of these keywords:
INPUT, OUTPUT, IO, PROBE, PROBE-DIRECTORY, and PROBE-LINK. The
meanings of the direction keywords are as follows:
INPUT
Specifies that the file is to be opened for input server-to-user
transfer). To request a direct access opening, supply a value for
DIRECT-FILE-ID. If no DIRECT-FILE-ID is supplied, the opening is a
data stream opening.
OUTPUT
Specifies that the file is to be opened for output user-to-server
transfer). To request a direct access opening, supply a value for
DIRECT-FILE-ID. If no DIRECT-FILE-ID is supplied, the opening is a
data stream opening.
IO
Specifies that interspersed input and output will be performed on
the file. This is only meaningful in direct access mode. A
DIRECT-FILE-ID must also be supplied. See the section "NFILE OPEN
Optional Keyword/Value Pairs", section 8.20.1.
If direction is supplied as PROBE, PROBE-LINK, or PROBE-DIRECTORY,
the opening is said to be a probe-type opening. The DIRECT-FILE-ID
option is meaningless and an error for probe-type openings. The file
handle must be supplied as an empty token list for probe-type
openings.
PROBE
Specifies that the file is not to be opened at all, but simply
checked for existence. If the file does not exist or is not
accessible, the error indications and actions are identical to
those that would be given for an INPUT opening. If the file does
exist, the successful command response contains the same
information as it would have if the file had been opened for
INPUT. If it is a link, the link is followed to its target.
PROBE-LINK
Like PROBE, with one difference. PROBE-LINK specifies that if the
pathname is found to refer to a link, that link is not to be
followed, and information about the link itself is to be returned.
PROBE-DIRECTORY
PROBE-DIRECTORY requests information about the directory
designated by the pathname argument. In the PROBE-DIRECTORY case,
the pathname argument refers to the directory on which information
is requested. In all other cases, the pathname refers to a file
to be opened. If pathname contains a file name and file type,
these parts of the pathname are ignored for PROBE-DIRECTORY
openings as long as they are syntactically valid.
THE binary-p OPEN ARGUMENT
The value of binary-p affects the mode in which the server opens the
file, as well as informing it whether or not character set
translation must be performed.
If binary-p is supplied as the empty token list, the opening is said
to be a character opening. The server performs character set
translation between its native character set and the NFILE character
set. The data is transferred over the data connection one character
per eight-bit byte. See the section "NFILE Character Set", section
6.
If binary-p is supplied as Boolean truth, the opening is said to be a
binary opening. The user side supplies the byte size via the BYTE-
SIZE option; if not supplied, the default byte size is 16 bits. If
byte size is less than 9, the file data is transferred byte by byte.
If the byte size is 9 or greater, the server transfers each byte of
the file as two eight-bit bytes, low-order first.
binary-p can also be supplied as the keyword DEFAULT. DEFAULT
specifies that the server itself is to determine whether to transfer
binary or character data. DEFAULT is meaningful only for input
openings; it is an error for OUTPUT, IO, or probe-type openings. For
file systems that maintain the innate binary or character nature of a
file, the server simply asks the file system which case is in force
for the file specified by pathname.
When binary-p is supplied as DEFAULT, on file systems that do not
maintain thisinformation, the server is required to perform a
heuristic check for Symbolicsobject fileson the first two 16-bit
bytes of the file. If the file isdetermined to be aSymbolics object
file, the server performs a BINARY openingwith BYTE-SIZE of16;
otherwise, it performs a CHARACTER opening.
The details of the check are as follows: if the first 16-bit byte is
the octal number170023 and the second 16-bit byte is any number
between 0 and 77 octal(inclusive), the file is recognized as a
Symbolics object file. In any othercase, it is not.
8.20.1 NFILE OPEN Optional Keyword/Value Pairs
The OPEN command has many optional keyword/value pairs that encode
conceptual arguments to the file system for the OPEN operation.
The following options are used often:
BYTE-SIZE
Must be followed by an integer between 1 and 16, inclusive, or the
empty token list. BYTE-SIZE is meaningful only for binary
openings. BYTE-SIZE can be ignored for probe-type openings. It
can be omitted entirely for character openings, but if supplied,
must be followed by the empty token list. If binary-p is supplied
as DEFAULT, BYTE-SIZE can be omitted entirely, or followed by the
empty token list.
If a binary opening is requested and BYTE-SIZE is not supplied,
the assumed value is 16 for output openings. For input binary
openings, the default is the host file system's stored conception
of the file's byte size (for those hosts that natively support
byte size). For file systems that do not natively support
natively byte size, the default byte-size on binary input is 16.
For file systems that maintain the innate byte-size of each file,
the server should supply this number to the appropriate operating
system interface that performs the semantics of opening the file.
For other operating systems, a file written with a given byte size
must produce the same bytes in the same order when read with that
byte size. In this case, the server or host operating system can
choose any packing scheme that complies with this rule.
Operating systems that do not support byte size must ensure that
binary files written from user ends of the current protocol can be
read back correctly. However, the server can choose packing
schemes that allow all bits of the server host's word to be
accessed and concur with other packing schemes used by native host
software.
For example, Multics supports 36 bit words and 9 bit bytes. A
packing scheme appropriate for a Multics NFILE server is:
Byte Size Packing Scheme
7, 8, or 9 bits four per 36-bit word
10, 11, or 12 bits three per 36-bit word
13, 14, 15, or 16 bits two per 36-bit word
In the first packing scheme in the table, native Multics
character-oriented software can access each logical byte
sequentially. In the last packing scheme, each Symbolics byte is
in a halfword, easily accessible and visible in an octal
representation. To achieve maximum data transfer rate and access
all bits of a Multics word, a byte size of 12 must be specified.
DELETED
If supplied as Boolean truth, DELETED specifies that deleted"
files are to be treated as though they were not "deleted".
DELETED is meaningful only for operating systems that support
"soft deletion" and subsequent "undeletion" of files. Other
operating systems must ignore this option. Normally, deleted
files are not visible to the OPEN operation; this option makes
them visible.
DELETED can also be followed by the empty token list, which has
the same effect as omitting the DELETED keyword/value pair
entirely. For output openings, DELETED is meaningless and an
error if supplied.
DIRECT-FILE-ID
If supplied, the DIRECT-FILE-ID indicates that the opening is to
be a direct access mode opening. If not supplied, the opening is
a data stream opening. The value of DIRECT-FILE-ID is a string
generated by the user, that has not been used as a DIRECT-FILE-ID
in this dialogue, and does not designate any data channel. The
DIRECT-FILE-ID is a unique identifier for the direct access
opening. It is used for all operations that identify an opening
rather than a data channel. The DIRECT-FILE-ID is used to
identify a direct access opening, just as a file handle is used to
identify a data stream opening. The PROPERTIES, CLOSE, and RENAME
commands use the DIRECT-FILE-ID in this way. There are only two
NFILE commands applicable to direct access openings (ABORT and
CONTINUE) that do not use the DIRECT-FILE-ID, but use a data
channel handle instead.
PRESERVE-DATES
If supplied as Boolean truth, PRESERVE-DATES specifies that the
server is to attempt to prevent the operating system from updating
the "reference date" or date-time used" of the file. This is
meaningful only for input openings, and is an error otherwise.
The Symbolics operating system invokes this option for operations
such as View File in the editor, where it wishes to assert that
the user did not "read" the file, but just "looked at it".
Servers on operating systems that do not support reference dates
or users revising or suppressing update of the reference dates
must ignore this option.
ESTIMATED-LENGTH
The value of ESTIMATED-LENGTH is an integer estimating the length
of the file to be transferred. This option is meaningful and
permitted only for output openings. ESTIMATED-LENGTH enables the
user end to suggest to the server's file system how long the file
is going to be. This can be useful for file systems that must
preallocate files or file maps or that accrue performance benefits
from knowing this information at nthe time the file is first
opened. This estimate, if supplied, is not required to be exact.
It is ignored by servers to which it is not useful or interesting.
The units of the estimate are characters for character openings,
and bytes of the agreed-upon byte size for binary openings. The
character units should be server units, if possible, but since
this is only an estimate, NFILE character units are acceptable.
See the section "NFILE Character Set", section 6.
IF-EXISTS
Meaningful only for output openings, ignored otherwise, but not
diagnosed as an error. The value of IF-EXISTS is a keyword that
specifies the action to Be taken if a file of the given name
already exists. The semantics of the values are derived from the
Common Lisp specification and repeated here for completeness. If
the file does not already exist, the IF-EXISTS option and its
value are ignored.
If the user side does not give the IF-EXISTS option, The action to
be taken if a file of the given name already exists depends on
whether or not the file system supports file versions. If it
does, the default is ERROR (if an explicit version is given in the
file pathname) or NEW-VERSION (if the version in the file pathname
is the newest version). For file systems not supporting versions,
the default is SUPERSEDE. These actions are described below.
IF-EXISTS provides the mechanism for overwriting or appending to
files. With the default setting of IF-EXISTS, new files are
created by every output opening.
Operating systems supporting soft deletion can take different
actions if a "deleted" file already exists with the same name (and
type and version, where appropriate) as a file to be created. The
Symbolics file system (LMFS) effectively uses SUPERSEDE, even if
not asked to do so. Other servers and file systems are urged to
do similarly. Recommended action is to not allow deleted files to
prevent successful file creation (with specific version number)
even if an IF-EXISTS option weaker than SUPERSEDE, RENAME, or
RENAME-AND-DELETE is specified or implied.
Here are the possible values and their meanings:
ERROR
Reports an error.
NEW-VERSION
Creates a new file with the same file name but with a larger
version number. This is the default when the version component
of the filename is newest. File systems without version
numbers can implement this by effectively treating it as
SUPERSEDE.
RENAME
Renames the existing file to some other name and then creates a
new file with the specified name. On most file systems, this
renaming happens at the time of a successful close.
RENAME-AND-DELETE
Renames the existing file to some other name and then deletes
it (but does not expunge it, on those systems that distinguish
deletion from expunging). Then it creates a new file with the
specified name. On most file systems, this renaming happens at
the time of a successful close.
OVERWRITE
Output operations on the opening destructively modify the
existing file. New data replaces old data at the beginning of
the file; however, the file is not truncated to length zero
upon opening.
TRUNCATE
Output operations on the opening destructively modify the
existing file. The file pointer is initially positioned at the
beginning of the file; at that time, TRUNCATE truncates the
file to length zero and frees disk storage occupied by it.
APPEND
Output operations on the opening destructively modify the
existing file. New data is placed at the current end of the
file.
SUPERSEDE
Supersedes the existing file. This means that the old file is
removed or deleted and expunged. The new file takes its place.
If possible, the file system does not destroy the old file
until the new file is closed, against the possibility that the
file will be close-aborted. This differs from NEW-VERSION in
that SUPERSEDE creates a new file with the same name as the old
one, rather than a file name with a higher version number.
There are currently no standards on what a server can do if it
cannot implement some of these actions.
IF-DOES-NOT-EXIST
Meaningful for input openings, never meaningful for probe-type
openings, and sometimes meaningful for output openings. IF-DOES-
NOT-EXIST takes a value token, which specifies the action to be
taken if the file does not already exist. Like IF-EXISTS, it is a
derivative of Common Lisp. The default is as follows: If this is
a probe-type opening or read opening, or if the IF-EXISTS option
is specified as OVERWRITE, TRUNCATE, or APPEND, the default is
ERROR. Otherwise, the default is CREATE.
These are the values for IF-DOES-NOT-EXIST:
ERROR
Reports an error.
CREATE
Creates an empty file with the specified name and then proceeds
as if it already existed.
The following optional keyword/value pairs are rarely used, if ever:
RAW
If supplied as Boolean truth, RAW specifies that character set
translation is not to be performed, but that characters are to be
transferred intact, without inspection. This option is meaningful
only for character openings; it is an error otherwise. It is also
an error to supply RAW as Boolean truth for probe-type openings.
RAW can also be followed by the empty token list, which has the
same effect as if the RAW keyword/value pair were omitted
entirely. See the section "RAW Translation Mode", Appendix B.
SUPER-IMAGE
If supplied as Boolean truth, SUPER-IMAGE specifies that Rubout
quoting is not to be performed. This operation is meaningful only
for character openings; it is an error otherwise. It is also an
error for probe-type openings. SUPER-IMAGE can also be followed
by the empty token list, which has the same effect as if the
SUPER-IMAGE keyword/value pair were omitted entirely.
SUPER-IMAGE mode causes the server to read or write character
files where ASCII Rubout characters are a significant part of the
file content, not where they are an escape for this protocol.
However, other translations must still be performed: See the
section SUPER-IMAGE Translation Mode", Appendix C.
TEMPORARY
Used by the TOPS-20 server only. TEMPORARY says to use GJ%TMP in
the GTJFN. This is useful mainly when writing files, and
indicates that the foreign operating system is to treat the file
as temporary. See TOPS-20 documentation for more about the
implications of this option. Other servers can ignore it. This
option is meaningless and an error for input or probe-type
openings. TEMPORARY can also be followed by the empty token list,
which has the same effect as if the TEMPORARY keyword/value pair
were omitted entirely.
SUBMIT
SUBMIT is meaningful for output only. If supplied as Boolean
truth, SUBMIT causes the server to submit the contents of the file
being written to the operating system as a job, after the file is
closed. VMS is an example of an operating system that could
conveniently support SUBMIT. SUBMIT can also be followed by the
empty token list, which has the same effect as if the SUBMIT
keyword/value pair were omitted entirely. Servers that do not
implement this option should give an error response if requested
to submit a file to the operating system.
8.20.2 NFILE OPEN Response Return Values
The results of a successful OPEN operation are reported in the
command response. Here is the specification of the OPEN response
format:
Response Format:
(OPEN tid truename binary-p other-properties)
The return values for OPEN and CLOSE are syntactically identical, but
the values can change in the time interval between open and close.
truename is a string representing the pathname of the file in the
full pathname syntax of the server host. It should be determined by
the server once it has opened the file, via some request to its
operating system. The request can be of the form: "What file
corresponds to this JFN, file number, pointer, etc.?" If the
operating system supports version numbers, this string always
contains an explicit version number. It always contains a directory
name, a file name, and so on.
Some operating systems might not know the truename of an output file
until it is closed. It is permissible not to supply an explicit
version number in the pathname in the OPEN response in this specific
case. On these systems the truename when the file is opened is
different than the truename after it has been closed.
The return value binary-p indicates whether the opening is a binary
or character opening. For binary openings, binary-p is supplied as
Boolean truth; for character openings it is the empty token list.
other-properties is a list of keyword/value pairs. other-properties
must contain CREATION-DATE and LENGTH. AUTHOR should be included if
the server operating system has a convenient mechanism for
determining the author of the sfile. The other properties described
here can be included if desired.
AUTHOR
The value of AUTHOR is a string representing the name of the author
of the file. This is some kind of user identifier, whose format is
system-specific. As with CREATION-DATE (see below), AUTHOR is
supposed to represent the logical determinor of the current data
content of the file, not necessarily the agency that actually created
the file.
BYTE-SIZE
The byte-size agreed upon via the rules described for the BYTE-SIZE
option. The value of BYTE-SIZE is an integer. For details on the
ramifications of BYTE-SIZE: See the section "NFILE OPEN Optional
Keyword/Value Pairs", section 8.20.1. This parameter is only
meaningful for BINARY openings. However, if FILEPOS is returned in
the other-properties list, BYTE-SIZE should also be included, even
for character openings.
CREATION-DATE
The creation date of the file. The date is expressed in Universal
Time format, which measures a time as the number of seconds since
January 1, 1900, at midnight GMT. Creation date does not necessarily
mean the time the file system created the directory entry or records
of the file. For systems that support modification or appending to
files, it is usually the modification date of the file. Creation
date can mean the date that the bit count or byte count of the file
was set by an application program.
Some types of file systems support a user-settable quantity
(CREATION-DATE) which the user can set to an arbitrary time, to
indicate that the contents of this file were written a long time ago
by someone else on another computer. The default value of this
quantity, if the user has not set it, is the time someone last
modified the information in the file. This quantity, in the OPEN
response for an output file, is disregarded by the user side, but
nevertheless must be present.
The Symbolics computer system software uses this quantity as a unique
identifier of file contents, for a given file name, type, and
version, to prove that a file has not changed since it last recorded
this quantity for a file.
FILEPOS
An integer giving the position of the logical file pointer, in
characters or bytes as appropriate for the type of opening. This is
always zero for an input opening and for an output opening creating a
new file. For an output opening appending to an existing file,
FILEPOS is the number of characters or bytes, as appropriate,
currently in the file. This number, for character openings, is
measured in server units: See the section "NFILE Character Set",
section 6.
LENGTH
An integer reporting the length of the file, in characters for
character openings and in bytes of the agreed-upon size for binary
openings. LENGTH should be reported as zero for output openings,
even if appending to an existing file. The server usually only knows
the length for a character opening in server units; thus, it reports
length in server units.
8.21 PROPERTIES Command
Command: (PROPERTIES tid handle pathname control-keywords
properties)
Response: (PROPERTIES tid property-element settable-properties)
PROPERTIES requests the property information about one file. The
file is identified by the pathname argument or the handle argument,
but not both. If pathname is supplied, it is a string in the full
pathname syntax of the server host. See the section "Syntax of File
and Directory Pathname Arguments", section 7.4.
If handle is supplied, its value is a string identifying an opening,
which implicitly identifies a file. For direct access mode openings,
handle must be a direct file identifier.
control-keywords is reserved in the current design. However, it is a
required argument, and must be supplied as the empty token list. Its
presence in the NFILE specification allows for future expansion. In
the future the value of control-keywords might affect the listing
mode.
properties is a token list of keywords indicating the properties the
user wants returned. (In command arguments, properties cannot be
specified with integers, such as indices into the Property Index
Table). For a list of keywords associated with file properties: See
the section "Format of NFILE File Property/Value Pairs", section 7.5.
The server is always free to return more properties than those
requested in the properties argument. If properties is supplied as
the empty token list, the server transmits all known properties of
the file.
PROPERTIES COMMAND RESPONSE
The server returns the property information for the given file in the
command response. The PROPERTIES command does not use any data
channels. If the specified file does not exist or is not accessible,
the server signals an error and includes an appropriate three-letter
error code in the command error response. See the section "NFILE
Errors and Notifications", section 10.
The return value property-element is a token list. The first element
in that token list is the pathname of the file, in the full pathname
syntax of the server host. The following elements of the property-
element token list are property/value pairs. The server is expected
to return several property/value pairs; the number of pairs is not
constrained. For further details on file properties and their
associated values: See the section "Format of NFILE File
Property/Value Pairs", section 7.5.
The return value settable-properties is a token list of keywords.
The number of keywords is not constrained. (Note that integers
cannot be used in settable-properties to indicate the file property;
keywords are to be used instead.) Each keyword supplied in
settable-properties identifies a property considered settable by the
server. The server is implicitly guaranteeing a mechanism for
changing the properties reported as settable. The user can change