The Lisp Machine can access files on a variety of remote file servers,
which are typically (but not necessarily) accessed through the Chaosnet,
as well as accessing files on the Lisp Machine itself, if the machine
has its own file system. You are not allowed to refer to files
without first logging in, and you may also need to specify a username
and password for the host on which the file is stored; see .
The way to read or write a file's contents is to open the file to
get an input or output stream, use the standard stream I/O functions or
operations described in chapters and
, and then close the stream. The first section
of this chapter tells how to open and close the stream. The rest of the
chapter describes things specific to files such as deleting and
renaming, finding out the true name of the file that has been opened,
and listing a directory.
Files are named with pathnames. There is much to know about
pathnames aside from accessing files with them; all this is described
in the previous chapter.
Many functions in this chapter take an argument called file which
is intended to specify a file to be operated on. This argument may be
given as a pathname (which is defaulted), a namestring (which is
parsed into a pathname and then defaulted), or a stream open to a file
(the same file is used).
(stream file options...) body...
Evaluates the body forms with the variable stream bound to a stream that
reads or writes the file named by the value of file. The options
forms evaluate to the file-opening options to be used; see .
When control leaves the body, either normally or abnormally (via throw),
the file is closed. If a new output file is being written and control leaves
abnormally, the file is aborted and it is as if it were never written. Because
it always closes the file, even when an error exit is taken, with-open-file
is preferred over open. Opening a large number of files and forgetting to
close them tends to break some remote file servers, ITS's for example.
If an error occurs in opening the file, the result depends on the
values of the error option, the if-exists option, and the
if-does-not-exist option. An error may be signaled (and possibly
corrected with a new pathname), or stream may be bound to a condition
object or even nil.
(stream file options...) clauses...
This opens and closes the file like with-open-file, but what happens
afterward is determined by clauses that are like the clauses of a
condition-case (). Each clause begins with a
condition name or a list of condition names and is executed if open
signals a condition that possesses any of those names. A clause
beginning with the symbol :no-error is executed if the file is
opened successfully. This would be where the reading or writing of the
file would be done.
Example: (with-open-file-case (stream (send generic-pathname
:source-pathname))
(sys:remote-network-error (format t "~&Host down."))
(fs:file-not-found (format t "~&(New file)"))
(:no-error (setq list (read stream))))
(pathname-var condition-names...) body...
cond-form (pathname-var condition-names...) body...
file-retry-new-pathname executes body. If body does not
signal any of the conditions in condition-names, body's values
are simply returned. If any of condition-names is signaled,
file-retry-new-pathname reads a new pathname, setq's
pathname-var to it, and executes body again.
The user can type End instead of a pathname if he wishes
to let the condition be handled by the debugger.
file-retry-new-pathname-if is similar, but the conditions are
handled only if cond-form's value is non-nil.
For an example, see the example of the following macro.
(stream (pathname-var condition-names...) options...) body...
Like with-open-file inside of a file-retry-new-pathname. If an
error occurs while opening the file and it has one of the specified
condition-names, a new pathname is read, the variable
pathname-var is setq'd to it, and another attempt is made to
open a file with the newly specified name. Example:
(with-open-file-retry (instream (infile fs:file-not-found))
...)
infile should be a variable whose value is a pathname or namestring.
The example is equivalent to
(file-retry-new-pathname (infile fs:file-not-found)
(with-open-file (instream infile)
...))
Opens a file, trying various pathnames until one of them succeeds. The
pathnames tried differ only in their type components. For example,
load uses this macro to search for either a compiled file or a
source file. The calling sequence looks like
(with-open-file-search
(streamvar (operation defaults auto-retry)
types-and-pathname options...)
body...)
with-open-file-search
tries opening various files until one succeeds; then binds streamvar to the stream
and executes body, closing the stream on exit. The values of body are returned.
types-and-pathname specifies which files to open. It should be a form
which evaluates to two values, the first being a list of types to try
and the second being a pathname called the base pathname. Each pathname to try
is made by merging the base pathname with the defaults defaults and one of the types.
The types may be strings or canonical type keywords (see ).
options are forms whose values should be alternating to keywords and
values, which are passed to open each time.
If all the names to be tried fail, a fs:multiple-file-not-found error is signaled.
operation is provided just so that the :operation operation on the condition
object can return it. Usually the value given for operation should be the
user-level function for which the with-open-file-search is being done.
If auto-retry is non-nil, an error causes the user to be
prompted for a new base pathname. The entire set of types specified is
tried anew with the new pathname.
file &rest options
Returns a stream that is connected to the specified file. Unlike
Maclisp, the open function creates streams only for files;
streams of other kinds are created by other functions. The file
and options arguments are the same as in with-open-file; see above.
When the caller is finished with the stream, it should close the file by using
the :close operation or the close function. The with-open-file
special form does this automatically and so is usually preferred. open
should only be used when the control structure of the program necessitates opening
and closing of a file in some way more complex than the simple way provided
by with-open-file. Any program that uses open should set up
unwind-protect handlers (see ) to close its files
in the event of an abnormal exit.
stream &optional option
The close function simply sends the :close message to stream.
If option is :abort for a file output stream, the file is discarded.
stream &key abort
The Common Lisp version of close is the same as close except for
its calling convention. If abort is non-nil for a file output
stream, the file is discarded.
Closes all open files. This is useful when a program has run wild opening
files and not closing them. It closes all the files in :abort mode
(see ), which means that files open for output are
deleted. Using this function is dangerous, because you may close files
out from under various programs like Zmacs and ZMail; only use it if you
have to and if you feel that you know what you're doing.
The options used when opening a file are normally alternating keywords and
values, like any other function that takes keyword arguments. In addition,
for compatibility with the Maclisp open function, if only a single option
is specified it is either a keyword or a list of keywords (not alternating with
values).
The file-opening options control things like whether the stream is for input
from a existing file or output to a new file, whether the file is text or binary, etc.
The following keyword arguments are standardly recognized; additional keywords
can be implemented by particular file system hosts.
direction |
Controls which direction of I/O can be done on the resulting stream.
The possible values are :input (the default), :output, nil,
:probe, :probe-directory and :probe-link. The first two
should be self-explanatory. nil or :probe means that this is a
``probe'' opening; no data are to be transferred, the file is being opened
only to verify its existence or access its properties. The stream
created in this case does not permit any I/O. nil and :probe
differ in causing different defaults for the argument if-does-not-exist.
If that argument is specified explicitly, nil and :probe are equivalent.
:probe-directory is used to see whether a directory exists. If the
directory specified for the file to be opened is found, then the
open completes (returning a non-I/O stream) as if the specified file
existed whether it really exists or not.
:probe-link is used to find out the truename of a link. If the file
specified exists as a link, then the open completes returning a
non-I/O stream which describes the link itself rather than the file
linked to. If the file exists and is not a link, the open also
completes for it as with any probe.
Common Lisp defines the value :io for this argument, requesting a stream
that can do input and output, but no file system
supported by the Lisp Machine has this capability.
|
characters |
The possible values are t (the default), nil, which means that the
file is a binary file, and :default, which means that the file system should
decide whether the file contains characters or binary data and open it in the
appropriate mode.
|
byte-size |
The possible values are nil (the default), a number, which is the number
of bits per byte, and :default, which means that the file system should
choose the byte size based on attributes of the file. If the file is being
opened as characters, nil selects the appropriate system-dependent byte
size for text files; it is usually not useful to use a different byte size.
If the file is being opened as binary, nil selects the default byte size
of 16 bits.
|
element-type | This is the Common Lisp way to specify what kind of objects the stream wants to
read or write. This combines the effect of the characters and byte-size
arguments. The value is a type specifier; it must be one of the following:
string-char | Read or write characters as usual. The default.
| character | Read or write characters, dealing with characters
that are more than 8 bits. You can succeed in writing out any
sequence of character objects and reading it back, but the file
does not look anything like a text file.
| (unsigned-byte n) | Read or write n-bit bytes.
Like characters = nil, byte-size = n.
| unsigned-byte | Similar, but uses the byte size that the file was originally written with.
This is the same as characters = nil, byte-size = :default.
| (signed-byte n) | Read or write n-bit bytes, sign-extending on input.
Each byte read from the file is sign-extended so that its most
significant bit serves as a sign bit.
| signed-byte | Similar, but uses the byte size that the file was originally written with.
| (mod n) | Like unsigned-byte for a big enough byte size to hold all numbers
less than n. bit is also accepted, and means (mod 2).
| :default | Is allowed, even though it is not a type specifier.
It is the same as using :default as the value of characters.
|
|
if-exists |
For output opens, if-exists specifies what to do if a file with the specified
name already exists. There are several values you can use:
:new-version | Create a new version. This makes sense only when the pathname has
:newest as its version, and it is the default in that case.
| :supersede | Make a new file which, when closed, replaces the old one.
| :overwrite | Write over the data of the existing file, starting
at the beginning, and set the file's length to the length of the
newly written data.
| :truncate | Like :overwrite except that it discards the old contents
of the file immediately, making it empty except for what is written into
it this time.
| :append | Add new data onto the existing file at the end.
| :rename | Rename the existing file and then create a new one.
| :rename-and-delete | Rename the existing file, create a new one,
and delete the old file when the new one is closed.
| :error | Signal an error (fs:file-already-exists).
This is the default when the pathname's version is not :newest.
The further handling of the error is controlled by the error argument.
| nil | Return nil from open in this case.
The error argument is irrelevant in this case.
|
|
if-does-not-exist | Specifies what to do when the file requested does not
exist. There are three allowed values:
:create | Create a file. This is the default for output opens, except when if-exists
is :append, :overwrite or :truncate. This silly exception
is part of the Common Lisp specifications.
| :error | Signal an error. This is the default for input opens,
and also for output opens when if-exists is :append, :overwrite
or :truncate.
The further handling of the error is controlled by the error argument.
| nil | Return nil from open. This is the default for :probe opens.
The error argument is irrelevant in this case.
|
|
error |
Specifies what to do if an error is signaled for any reason.
(Note that the values of the if-exists and if-does-not-exist arguments
control whether an error is signaled in certain circumstances.)
The possible values are t (the default), :reprompt and nil.
t means that nothing special is done, so the error invokes the
debugger if the caller does not handle it. nil means that the
condition object should be returned as the value of open. :reprompt
means that a new file name should be read and opened.
Any caller which need not know reliably which file was ultimately opened
might as well specify :reprompt for this argument. Callers which
need to know if a different file is substituted should never specify
:reprompt; they may use with-open-file-retry or
file-retry-new-pathname (see ) if they
wish to permit an alternative file name to be substituted.
|
:submit |
If specified as t when opening a file for output, the file is
submitted as a batch job if it is closed normally. The default is
nil. You must specify :direction :output as well.
|
deleted |
The default is nil. If t is specified, and the file system has the
concept of deleted but not expunged files, it is possible to open a deleted
file. Otherwise deleted files are invisible.
|
temporary |
If t is specified, the file is marked as
temporary, if the file system has that concept. The default is nil.
|
preserve-dates |
If t is specified, the file's reference and
modification dates are not updated. The default is nil.
|
flavor |
This controls the kind of file to be opened. The default is nil, a
normal file. Other possible values are :directory and :link.
Only certain file systems recognize this keyword.
|
link-to |
When creating a file with flavor :link, this argument must be
specified; its value is a pathname or namestring that becomes the target of the link.
|
submit |
The value can be either nil (the default) or t.
If the value is t, and the :direction is :output, the
resulting file will be submitted as a batch job.
Currently, this option is implemented only for Twenex and VMS.
|
estimated-size |
The value may be nil (the default), which means there is no estimated
size, or a number of bytes. Some file systems use this to optimize disk
allocation.
|
physical-volume |
The value may be nil (the default), or a string that is the name
of a physical volume on which the file is to be stored. This is not meaningful
for all file systems.
|
logical-volume |
The value may be nil (the default), or a string that is the name
of a logical volume on which the file is to be stored. This is not meaningful
for all file systems.
|
super-image |
The value may be nil (the default), or t, which
disables the special treatment of rubout in ASCII files. Normally, rubout is
an escape which causes the following character to be interpreted specially,
allowing all characters from 0 through 376 (octal) to be stored. This applies to
ASCII file servers only.
|
raw |
The value may be nil (the default), or t, which
disables all character set translation in ASCII files. This applies to ASCII
file servers only.
|
In the Maclisp compatibility mode, there is only one option, and it
is either a symbol or a list of symbols. These symbols are recognized no
matter what package they are in, since Maclisp does not have packages.
The following symbols are recognized:
in, read | Select opening for input (the default).
|
out, write, print | Select opening for output; a new file is to be created.
|
binary, fixnum | Select binary mode; otherwise character mode is used. Note that fixnum mode
uses 16-bit binary words and is not compatible with Maclisp fixnum mode, which
uses 36-bit words. On the PDP-10, fixnum files are stored with two 16-bit words
per PDP-10 word, left-justified and in PDP-10 byte order.
|
character, ascii | The opposite of fixnum. This is the default.
|
single, block | Ignored for compatibility with the Maclisp open function.
|
byte-size | Must be followed by a number in the options list, and must be used in combination
with fixnum. The number is the number of bits per byte, which can be from
1 to 16. On a PDP-10 file server these bytes will be packed into words in the
standard way defined by the ILDB instruction. The :tyi stream operation
will (of course) return the bytes one at a time.
|
probe, error, noerror, raw, super-image, deleted, temporary | These are not available in Maclisp. The corresponding keywords in the
normal form of file-opening options are preferred over these.
|
The following functions and operations may be used on file streams, in addition to the normal I/O
operations which work on all streams. Note that several of these operations are
useful with file streams that have been closed. Some operations
use pathnames; refer to for an explanation of pathnames.
file-stream
Returns the length of the file open on file-stream, in terms of the units
in which I/O is being done on that stream. (A stream is needed, rather than
just a pathname, in order to specify the units.)
file-stream &optional new-position
With one argument, returns the current position in the file of file-stream,
using the :read-pointer stream operation. It may return nil meaning that
the position cannot be determined. In fact, it always returns nil
for a stream open in character mode and not at the beginning of the file.
With two arguments, sets the position using the :set-pointer stream
operation, if possible, and returns t if the setting was possible
and nil if not. You can specify :start as the new-position
to position to the beginning of the file, or :end to position to the
end.
streams" :pathname
Returns the pathname that was opened to get this stream. This may not be
identical to the argument to open, since missing components will have been
filled in from defaults. The pathname may have been replaced wholesale if
an error occurred in the attempt to open the original pathname.
streams" :truename
Returns the pathname of the file actually open on this stream. This can be
different from what :pathname returns because of file links, logical
devices, mapping of version :newest to a particular version number, etc. For
an output stream the truename is not meaningful until after the stream has been
closed, at least when the file server is an ITS.
streams" :generic-pathname
Returns the generic pathname of the pathname that was opened to get this
stream. Normally this is the same as the result of sending the
:generic-pathname message to the value of the :pathname
operation on the stream; however, it does special things when the Lisp
system is bootstrapping itself.
streams" :qfaslp
Returns t if the file has a magic flag at the front that says it is a QFASL file,
nil if it is an ordinary file.
streams" :length
Returns the length of the file, in bytes or characters. For text files on
ASCII file servers, this is the number of ASCII characters, not Lisp Machine
characters. The numbers are different because of character-set translation;
see for a full explanation.
For an output stream the length is not meaningful until after the stream has
been closed, at least when the file server is an ITS.
streams" :creation-date
Returns the creation date of the file, as a number that is a universal time.
See the chapter on the time package ().
streams" :info
Returns a cons of the file's truename and its creation date. This can
be used to tell if the file has been modified between two open's.
For an output stream the information is not guaranteed to be correct
until after the stream has been closed.
streams" :properties &optional (error-p t)
This returns two values: a property list (like an element of the list
returned by fs:directory-list), and a list of the settable
properties. See the section on standard file properties () for a
description of the ones that may possible found in the list.
streams" :set-byte-size new-byte-size
This is only allowed on binary file streams. The byte size
can be changed to any number of bits from 1 to 16.
streams" :delete &optional (error-p t)
Deletes the file open on this stream. For the meaning of error-p, see the deletef
function. The file doesn't really go away until the stream is closed.
streams" :undelete &optional (error-p t)
If you have used the :deleted option in open to open a deleted
file, this operation undeletes the file.
streams" :rename new-name &optional (error-p t)
Renames the file open on this stream. For the meaning of error-p, see the renamef
function.
File output streams implement the :finish and :force-output operations.
This section describes functions for doing things to files aside from
reading or writing their contents.
object
Returns the truename of the file specified somehow by object. If
object is a plausible stream, it is asked for the truename with the
:truename operation. Otherwise, object is converted to a
pathname and that pathname is opened to get its file's truename.
file &key (error-p t) query?
file &optional (error-p t) query?
Both delete the specified file. The two functions differ in accepting
keyword arguments versus positional arguments. file may contain
wildcard characters, in which case multiple files are deleted.
If query? is non-nil, the user is queried about each file
(whether there are wildcards or not). Only the files that the user
confirms are actually deleted.
If error-p is t, then if an error occurs it is signaled as
a Lisp error. If error-p is nil and an error occurs, the error
message is returned as a condition object. Otherwise, the value is a list of
elements, one for each file considered. The car of each element is
the truename of the file, and the cadr is non-nil if the file
was actually deleted (it is always t unless querying was done).
file &key (error-p t) query?
file &optional (error-p t) query?
Both undelete the specified file. Wildcards are allowed, just as in
deletef. The rest of the calling conventions are the same as well.
The two functions differ in taking keyword arguments versus positional
arguments.
Not all file systems support undeletion, and if it is not supported on
the one you are using, it gets an error or returns a string according to
error-p. To find out whether a particular file system supports
this, send the :undeletable-p operation to a pathname. If it
returns t, the file system of that pathname supports undeletion.
file new-name &key (error-p t) query?
file new-name &optional (error-p t) query?
Both rename the specified file to new-name (a pathname or string).
The two functions differ in taking keyword arguments versus positional
arguments. file may contain wildcards, in which case multiple files
are renamed. Each file's new name is produced by passing new-name
to merge-pathname-defaults with the file's truename as the defaults.
Therefore, new-name should be a string in this case.
If query? is non-nil, the user is queried about each file
(whether there are wildcards or not). Only the files that the user
confirms are actually renamed.
If error-p is t, then if an error occurs it is signaled as
a Lisp error. If error-p is nil and an error occurs, the error
message is returned as a condition object. Otherwise, the value is a list of
elements, one for each file considered. The car of each element is
the original truename of the file, the cadr is the name it was to be
renamed to, and the caddr is non-nil if the file was renamed.
The caddr is nil if the user was queried and said no.
file new-name &key (error t) (copy-creation-date t) (copy-author t) report-stream (create-directories :query) (characters :default) (byte-size :default)
Copies the file specified by file to the name new-name.
characters and byte-size specify what mode of I/O to use to transfer the data.
characters can be
t | to specify character input and output.
|
nil | for binary input and output,
|
:ask | meaning ask the user which one
|
:maybe-ask | meaning ask if it is not possible to tell with certainty which method is best,
|
:default | meaning to guess as well as possible automatically.
|
If binary transfer is done, byte-size specifies the byte size to
use; :default means to ask the file system for the byte size that
the old file is stored in, just as it does in open.
copy-author and copy-creation-date say whether to set those
properties of the new file to be the same as those of the old file. If
a property is not copied, it is set to your login name or the current
date and time.
report-stream, if non-nil, is a stream on which a message should
be printed describing the file copied, where it is copied to, and which
mode was used.
create-directories says what to do if the output filename specifies a directory that
does not exist. It can be t meaning create the directory, nil meaning treat it as
an error, or :query meaning ask the user which one to do. The default is :query.
error, if nil, means that if an error happens then this function
should just return an error indication.
If the pathname to copy from contains wildcards, multiple files are
copied. The new name for each file is obtained by merging new-name
(parsed into a pathname) with that file's truename as a default. The
mode of copy is determined for each file individually, and each copy is
reported on the report-stream if there is one. If error is nil,
an error in copying one file does not prevent the others from being
copied.
There are four values. If wildcards were used, each value is a list with
one element describing each file that matched; otherwise, each value describes the
single file specified (though the value may be a list anyway). The values,
for each file, are:
output-file | The defaulted pathname to be opened for output in copying this file.
|
truename | The truename of the file copied
|
outcome | The truename of the new file, If the file was successfully copied.
A condition object, if there was an error and error was nil.
nil if the user was asked whether to copy this file and said no.
|
mode | A Common Lisp type descriptor such as string-char or (unsigned-byte 8)
saying how the file was copied.
|
file
file
Returns nil if there is no file named file; otherwise returns a
pathname that is the true name of the file, which can be different from
file because of file links, version numbers, etc. If file is
a stream, this function cannot return nil.
Any problem in opening the file except for fs:file-not-found signals
an error.
probef is the Maclisp name; probe-file is the Common Lisp name.
file
Returns the creation date/time of file, as a universal time.
file
Returns the name of the author of file (the user who wrote it), as a
string.
file &optional (output-stream *standard-output*) leader
Copies the contents of the specified file, opened in character
mode, onto output-stream. Normally this has the effect of printing
the file on the terminal. leader is passed along to
stream-copy-until-eof (see ).
link-name link-to &key (error t)
Creates a link named link-name which points to a file named link-to.
An error happens if the host specified in link-name does not support links,
or for any of the usual problems that can happen in creating a file.
To load a file is to read through the file, evaluating each form
in it. Programs are typically stored in files; the expressions in the file are mostly
special forms such as defun and defvar which define the functions and
variables of the program.
Loading a compiled (or QFASL) file is similar, except that the file does not
contain text but rather pre-digested expressions created by the
compiler which can be loaded more quickly.
These functions are for loading single files. There is a system for keeping track
of programs which consist of more than one file; for further information refer
to .
file &key verbose print (if-does-not-exist t) set-default-pathname package
Loads the specified file into the Lisp environment. If
file is a stream, load reads from it; otherwise file
is defaulted from the default pathname defaults and the result
specifies a file to be opened. If the file is a QFASL file, fasload
is used; otherwise readfile is used. If file specifies a name
but no type, load looks first for the canonical type :qfasl and
then for the canonical type :lisp.
Normally the file is read into the package specified in its attribute
list, but if package is supplied then the file is read in that
package. If package is nil and verbose is nil, load
prints a message saying what file is being loaded and what package is
being used. verbose defaults to the value of *load-verbose*.
If if-does-not-exist is nil, load just returns nil if no
file with the specified name exists. Error conditions other than
fs:file-not-found are not handled by this option.
If a file is loaded, load returns the file's truename.
If print is non-nil, the value of each expression evaluated from
the file is printed on *standard-output*.
pathname is defaulted from the default pathname defaults. If
set-default-pathname is non-nil, the pathname defaults are set
to the name of the file loaded. The default for
set-default-pathname is t.
load used to be called with a different calling sequence:
(load pathname pkg nonexistent-ok
dont-set-default)
This calling sequence is detected and still works, but it is obsolete.
Is the default value for the verbose argument to load.
file &optional pkg no-msg-p
readfile is the version of load for text files. It reads and evaluates
each expression in the file. As with load, pkg can specify what package
to read the file into. Unless no-msg-p is t, a message is printed
indicating what file is being read into what package.
file &optional pkg no-msg-p
fasload is the version of load for QFASL files. It defines
functions and performs other actions as directed by the specifications
inserted in the file by the compiler. As with load, pkg can
specify what package to read the file into. Unless no-msg-p is
t, a message is printed indicating what file is being read into what
package.
Here are the operations that access files. Many accept an argument
error or error-p which specifies whether to signal an error or
to return a condition instance, if the file cannot be accessed. For
these arguments, nil and non-nil are the only significant values.
:reprompt has no special meaning as a value. That value when passed
to one of the file accessing functions (open, deletef, etc.)
has its special significance at a higher level.
Returns a pathname object describing the exact name of the file specified
by the pathname the object is sent to.
This may be different from the original pathname. For example, the
original pathname may have :newest as the version, but the truename
always has a number as the version if the file system supports versions.
pathname &rest options
Opens a stream for the file named by the pathname.
The argument pathname is what the :pathname operation on the
resulting stream should return. When a logical pathname is opened,
pathname is that logical pathname, but self is
its translated pathname.
options is a list of alternating keywords and values, as would be
passed to open. The old style of open keywords are not allowed;
when they are used with open, open converts them to the new
style before sending the :open message.
&optional (error-p t)
&optional (error-p t)
Respectively delete or undelete the file specified by the pathname.
All file systems support :delete but not all support :undelete.
If error-p is nil, problems such as nonexistent files cause a
string describing the problem to be returned. Otherwise, they signal an
error.
Returns t if this pathname is for a file system which allows
deletion to be undone. Such pathnames support the :undelete
and :expunge operations.
new-name &optional (error-p t)
Renames the file specified by the pathname. new-name, a string or
pathname, specifies the name to rename to. If it is a string, it is
parsed using self as the defaults.
If error-p is nil, problems such as nonexistent files cause a
string describing the problem to be returned. Otherwise, they signal an
error.
string options
Attempts to complete the filename string, returning the results.
This operation is used by the function fs:complete-pathname (see
). The pathname the message is sent to is
used for defaults. options is a list whose elements may include
:deleted, :read (file is for input), :write (it's for
output), :old (only existing files allowed), or :new-ok (new files
are allowed too).
There are two values: a string, which is the completion as far as possible,
and a flag, which can be :old, :new or nil.
:old says that the returned string names an existing file,
:new says that the returned string is no file but some completion was done,
nil says that no completion was possible.
error-p &rest properties
Changes the properties of the file specified by the
pathname. properties should be an
alternating list of property names and values.
options
Performs the work of (fs:directory-list this-pathname options...).
Returns a property list (in the form
of a directory-list element) and a list of settable properties.
See for more information on file properties.
function plistp dir-list-options &rest args
Maps function over all the
files specified by this pathname (which may contain wildcards).
Each time function is called, its first argument is a pathname
with no wildcards, or else a directory-list element (whose car is a
pathname and whose cdr contains property names and values).
The elements of args are given to function as additional
arguments.
plistp says whether function's first argument should be a
directory-list element or just a pathname. t specifies a
directory-list element. That provides more information, but it makes it
necessary to do extra work if the specified pathname does not
contain wildcards.
dir-list-options is passed to fs:directory-list. You can use this
to get deleted files mentioned in the list, for example.
The remaining file-access operations are defined only on certain file
systems.
&key (error t)
Expunges the directory specified by the host, device and directory
components of the pathname.
The argument error says whether to signal an error if the directory
does not exist. nil means just return a string instead.
&key (error t)
Creates the directory specified in this pathname.
&key (error t) access
Performs the work of fs:remote-connect with the same arguments
on this pathname's host.
Any text file can contain an attribute list that specifies several attributes
of the file. The above loading functions, the compiler, and the editor look
at this property list. Attribute lists are especially useful in program
source files, i.e. a file that is intended to be loaded (or compiled and
then loaded). QFASL files also contain attribute lists, copied from
their source files.
If the first non-blank line in a text file contains the three characters
`-*-',
some text, and `-*-' again, the text is recognized as the file's attribute list.
Each attribute consists of the attribute name, a colon, and the attribute value.
If there is more than one attribute they are separated by semicolons. An example
of such an attribute list is:
; -*- Mode:Lisp; Package:Cellophane; Base:10 -*-
This defines three attributes: mode, package, and base.
The initial semicolon makes the line look like a comment rather than a Lisp expression.
Another example is:
.c Part of the Lisp Machine manual. -*- Mode:Bolio -*-
An attribute name is made up of letters, numbers, and otherwise-undefined
punctuation characters such as hyphens. An attribute value can be such a
name, or a decimal number, or several such items separated by commas.
Spaces may be used freely to separate tokens. Upper and lower-case
letters are not distinguished. There is no quoting convention for
special characters such as colons and semicolons.
If the attribute list text contains no colons, it is an old Emacs
format, containing only the value of the Mode attribute.
The file attribute list format actually has nothing to do with Lisp; it
is just a convention for placing some information into a file that is
easy for a program to interpret. The Emacs editor on the PDP-10 knows
how to interpret these attribute lists (primarily in order to look at the
Mode attribute).
The Lisp Machine handles the attribute list stored in the file by
parsing it into a Lisp data structure, a property list. Attribute names
are interpreted as Lisp symbols and are interned on the keyword package.
Numbers are interpreted as Lisp fixnums and are read in decimal. If a
attribute value contains any commas, then the commas separate several
expressions that are formed into a list.
When a file is compiled, its attribute list data structure is stored in
the QFASL file. It can be loaded back from the QFASL file as well.
The representation in the QFASL file resembles nothing described here,
but when the attribute list is extracted from there, the same Lisp data
structure described above is obtained.
When a file is edited, loaded, or compiled, its file attribute list is
read in and the properties are stored on the property list of the
generic pathname (see ) for that file, where they can
be retrieved with the :get and :plist messages. This is done
using the function fs:read-attribute-list, below. So the way you
examine the properties of a file is usually to use messages to a
pathname object that represents the generic pathname of a file. Note
that there are other properties there, too.
Here the attribute names with standard meanings:
Mode | The editor major mode to be used when editing this file. This is typically
the name of the language in which the file is written. The most common values
are Lisp and Text.
|
Package | This attribute specifies the package in which symbols in the file should
be interned. The attribute may be either the name of a package, or a
list that specifies both the package name and how to create the package
if it does not exist. If it is a list, it should look like
(name superpackage initial-size ...options...). See
for more information about packages.
|
Base | The number base in which the file is written (remember, it is
always parsed in decimal). This affects both *read-base* and *print-base*,
since it is confusing to have the input and output bases be different.
The most common values are 8 and 10.
|
Readtable | The value specifies the syntax (that is, the choice of readtable)
to use for reading Lisp objects from this file.
The defined values are t or traditional for traditional
Lisp Machine syntax, and cl or common-lisp for Common Lisp syntax.
If you do not specify this option, the objects in the file are read
using whatever readtable is current in the program that reads them.
|
Lowercase | If the attribute value is not nil, the file is written in lower-case letters
and the editor does not translate to upper case. (The editor does not translate
to upper case by default unless the user enables Electric Shift Lock mode.)
|
Fonts | The attribute value is a list of font names, separated by commas. The editor
uses this for files that are to be displayed in a specific font, or
contain multiple fonts. If this attribute is present,
the file is actually stored in the file system with font-change indicators.
A font-change indicator is an epsilon (ε) followed by a digit or *.
εn means to enter font n. The previous font is saved on a stack
and ε* means to pop the stack, returning to the previous font.
If the file includes an epsilon as part of its contents, it is stored as
εε.
When expressions are read from such files, font-change indicators
are ignored, and εε is treated as a single ε.
|
Backspace | If the attribute value is not nil, Overstrike characters in the
file should cause characters to overprint on each other. The default is
to disallow overprinting and display Overstrike the way other
special function keys are displayed. This default is to prevent the
confusion that can be engendered by overstruck text.
|
Patch-File | If the attribute value is not nil, the file is a patch file. When it is loaded
the system will not complain about function redefinitions. In a patch
file, the defvar special-form turns into defconst; thus patch files
always reinitialize variables. Patch files are usually created by special
editor commands described in .
|
Cold-Load | A non-nil value for this attribute identifies files that are part of
the cold load, the core from which a new system version is built.
Certain features that do not work in the cold load check this flag to
give an error or a compiler warning if used in such files, so that the
problem can be detected sooner.
|
You are free to define additional file attributes of your own. However,
to avoid accidental name conflicts, you should choose names that are
different from all the names above, and from any names likely to be
defined by anybody else's programs.
The following functions are used to examine file attribute lists:
pathname
Returns the attribute list of the file specified by the pathname.
This works on both text files and QFASL files.
stream
Returns the attribute list read from the specified stream, which should
be pointing to the beginning of a file. This
works on both text streams and QFASL file binary streams.
After the attribute list is read, the stream's pointer is set back to
the beginning of the file using the :set-pointer file
stream operation (see ).
pathname stream
pathname should be a pathname object (not a string or namelist,
but an actual pathname); usually it is a generic pathname (see
). stream should be a stream that has been
opened and is pointing to the beginning of the file whose file attribute
list is to be parsed. The attribute list is read from the stream and
then corresponding properties are placed on the specified pathname.
The attribute list is also returned.
The fundamental way that programs in the Lisp Machine notice the
presence of properties on a file's attribute list is by examining the
property list in the generic pathname. However, there is another way
that is more convenient for some applications. File attributes can
cause special variables to be bound whenever Lisp expressions are being
read from the file--when the file is being loaded, when it is being
compiled, when it is being read from by the editor, and when its QFASL
file is being loaded. This is how the Package and Base attributes work.
You can also deal with attributes this way, by using the following function:
pathname
Returns values describing the special variables that should be bound
before reading expressions from file pathname.
It examines the property list of pathname and finds all
those property names that have fs:file-attribute-bindings properties.
Each such property name specifies a set of variables to bind and
a set of values to which to bind them. This function returns two values,
a list of all the variables and a list of all the corresponding values.
Usually you use this function by calling it on a generic pathname
that has had fs:read-attribute-list done on it, and then
you use the two returned values as the first two arguments of a
progv
special form (see ). Inside the body of the progv the
specified bindings will be in effect.
pathname may be anything acceptable as the first argument of get.
Usually it is a generic pathname.
Of the standard attribute names, the following ones have
fs:file-attribute-bindings, with the following effects. Package
binds the variable package (see ) to the package.
Base binds the variables *print-base* (see ) and *read-base*
(see ) to the value. Readtable binds the variable readtable
to a value computed from the specified attribute. Patch-file binds
fs:this-is-a-patch-file to the value. Cold-load binds
si:file-in-cold-load to the value. Fonts binds
si:read-discard-font-changes to t.
Any properties whose names do not have fs:file-attribute-bindings
properties are ignored completely.
You can also add your own attribute names that affect bindings. If
an indicator symbol has an fs:file-attribute-bindings property, the
value of that property is a function that is called when a file with a
file attribute of that name is going to be read from. The function is
given three arguments: the file pathname, the attribute name, and the
attribute value. It must return two values: a list of variables to be
bound and a list of values to bind them to. The function for the
Base keyword could have been defined by:
(defun (:base file-attribute-bindings) (file ignore bse)
(if (not (and (typep bse 'fixnum)
(> bse 1)
(< bse 37.)))
(ferror 'fs:invalid-file-attrbute
"File ~A has an illegal -*- Base:~D -*-"
file bse))
(values (list 'base 'ibase) (list bse bse)))
stream
Returns two values: a list of variables, and a corresponding list of values to bind them to,
giving the attribute bindings of the attribute list found on stream
(error)
An attribute in the file attribute list had a bad value. This is detected within
fs:file-attribute-bindings.
To understand the functions in this section, it is vital to have read
the chapter on pathnames. The filespec argument in many of
these functions may be a pathname or a namestring; its name, type and
version default to :wild.
filespec
Prints on *standard-output* the names of the files that match
filespec, and their sizes, creation dates, and other information
that comes in the directory listing.
filespec &rest options
Finds all the files that match filespec and returns a list with one
element for each file. Each element is a list whose car is the pathname
of the file and whose cdr is a list of the properties of the file; thus the element
is a disembodied property list and get may be used to access the file's
properties. The car of one element is nil; the properties in this element
are properties of the file system as a whole rather than of a specific file.
filespec normally contains wildcards, and the data returned
describe all existing files that match it. If it contains no wildcards,
it specifies a single file and only that file is described
in the data that are returned.
The options are keywords which modify the operation. The following options
are currently defined:
:noerror |
If a file-system error (such as no such directory) occurs during the operation,
normally an error is signaled and the user is asked to supply a new pathname.
However, if :noerror is specified then, in the event of an error,
a condition object describing the error is returned as the result of fs:directory-list.
This is identical to the :noerror option to open.
|
:deleted |
This is for file servers on which deletion is not permanent. It specifies
that deleted (but not yet expunged) files are to be included in the
directory listing.
|
:sorted |
This requests that the directory list be sorted by filenames before it
is returned.
|
The properties that may appear in the list of property lists returned by
fs:directory-list are host-dependent to some extent. The following
properties are those that are defined for both ITS and TOPS-20 file servers. This set of
properties is likely to be extended or changed in the future.
:length-in-bytes | The length of the file expressed in terms of the basic units in which it is written
(characters in the case of a text file).
|
:byte-size | The number of bits in one of those units.
|
:length-in-blocks | The length of the file in terms of the file system's unit of storage allocation.
|
:block-size | The number of bits in one of those units.
|
:creation-date | The date the file was created, as a universal time. See .
|
:reference-date | The most recent date on which the file was used, as a universal time or
nil, meaning the file was never referenced.
|
:modification-date | The most recent date on which the file's contents were changed, as a
universal time.
|
:author | The name of the person who created the file, as a string.
|
:reader | The name of the person who last read the file, as a string.
|
:not-backed-up | t if the file exists only on disk, nil if it has been backed up on magnetic tape.
|
:directory | t if this file is actually a directory.
|
:temporary | t if this file is temporary.
|
:deleted | t if this file is deleted. Deleted files are included in the
directory list only if you specify the :deleted option.
|
:dont-delete | t indicates that the file is not allowed to be deleted.
|
:dont-supersede | t indicates that the file may not be superseded; that is, a file
with the same name and higher version may not be created.
|
:dont-reap | t indicates that this file is not supposed to be deleted
automatically for lack of use.
|
:dont-dump | t indicates that this file is not supposed to be dumped onto
magnetic tape for backup purposes.
|
:characters | t indicates that this file contains characters (that is, text).
nil indicates that the file contains binary data.
This property, rather than the file's byte size, should be used to
decide whether it is a text file.
|
:link-to | If the file is a link, this property is a string containing the name that
the link points to.
|
:offline | T if the file's contents are not online.
|
:incremental-dump-date | The last time this file was dumped during an incremental dump (a
universal time).
|
:incremental-dump-tape | The tape on which the last was saved in that incremental dump (a
string).
|
:complete-dump-date | The last time this file was dumped during an full dump (a
universal time).
|
:complete-dump-tape | The tape on which the last was saved in that full dump (a
string).
|
:generation-retention-count | The number of files differing in version that are kept around.
|
:default-generation-retention-count | The generation-retention-count that a file ordinarily gets when it is
created in this directory.
|
:auto-expunge-interval | The interval at which files are expunged from this directory, in
seconds.
|
:date-last-expunged | The last (universal) time this directory was expunged, or nil.
|
:account | The account to which the file belongs, a string.
|
:protection | A system-dependent description of the protection of this file as a
string.
|
:physical-volume | A string naming the physical volume on which the file is found.
|
:volume-name | A string naming the logical volume on which the file is found.
|
:pack-number | A string describing the pack on which this file is found.
|
:disk-space-description | A system-dependent description of the space usage on the file system.
This usually appears in the plist that applies to the entire directory
list.
|
The element in the directory list that has nil instead of a file's
pathname describes the directory as a whole.
:physical-volume-free-blocks | This property is an alist in which each element maps a physical volume
name (a string) into a number, that is the number of free blocks on that volume.
|
:settable-properties | This property is a list of file property names that may be set.
This information is provided in the directory list because it is
different for different file systems.
|
:pathname | This property is the pathname from which this directory list was made.
|
:block-size | This is the number of words in a block in this directory. It can be
used to interpret the numbers of free blocks.
|
filespec &rest options
This is like fs:directory-list but returns the information in a
different form. Instead of returning the directory list all at once, it
returns a special kind of stream which gives out one element of the
directory list at a time.
The directory list stream supports two operations: :entry and
:close. :entry asks for the next element of the directory
stream. :close closes any connection to a remote file server.
The purpose of using fs:directory-list-stream instead of
fs:directory-list is that, when communicating with a remote file
server, the directory list stream can give you some of the
information without waiting for it to all be transmitted and parsed.
This is desirable if the directory is being printed on the console.
filespec
Returns a list of pathnames (truenames) of the files in the directory specified
by filespec. Wildcards are allowed. This is the Common Lisp way
to find the contents of a directory.
filespec &key (error t)
Expunges the directory specified in filespec; that is, permanently
eliminates any deleted files in that directory. If error is nil,
there is no error if the directory does not exist.
Note that not all file systems support this function. To find out
whether a particular one does, send the :undeletable-p operation to
a pathname. If it returns t, the file system of that pathname
supports undeletion (and therefore expunging).
filespec &key (error t)
Creates the directory specified in filespec.
If error is nil, there is no error if the directory cannot be
created; instead an error string is returned.
Not all file servers support creation of directories.
filespec &key (error t) access
Performs the TOPS-20 ``connect'' or ``access'' function, or their
equivalents, in a remote file server. Access is done if
access is non-nil; otherwise, connect is done.
The connect operation grants you full access to the
specified directory. The access operation grants you whatever access
to all files and directories you would have if logged in on the
specified directory. Both operations affect access only, since the connected
directory of the remote server is never used by the Lisp Machine in
choosing which file to operate on.
This function may ask you for a password if one is required for the
directory you specify. If the operation cannot be performed, then if
error is nil, an error object is returned.
File Properties:
file error-p &rest properties
Changes one or more properties of the
file file. The properties arguments are alternating keywords
and values. If an error occurs accessing the file or changing the
properties, the error-p argument controls what is done; if it is
nil, a condition object describing the error is returned; if it is
t a Lisp error is signaled. If no error occurs,
fs:change-file-properties returns t.
Only some of the properties of a file may be changed; for instance,
its creation date or its author. Exactly which properties may be
changed depends on the host file system; a list of the changeable
property names is the :settable-properties property of the file
system as a whole, returned by fs:directory-list as explained
above.
file &optional (error-p t)
Returns a disembodied property list for a single file (compare this to
fs:directory-list). The car of the returned list is the truename of
the file and the cdr is an alternating list of indicators and values.
The error-p argument is the same as in fs:change-file-properties.
Filename Completion:
defaults string type version &rest options
string is a partially-specified file name. (Presumably it was typed in by a user
and terminated with the Altmode key or the End key to request completion.)
fs:complete-pathname looks in the file system on the appropriate host and
returns a new, possibly more specific string. Any unambiguous abbreviations
are expanded out in a host-dependent fashion.
defaults, type, and version are the arguments to be given to
fs:merge-pathname-defaults (see ) when the
user's input is eventually parsed and defaulted.
options are keywords (without following values) that control how the
completion is performed. The following option keywords are allowed:
:deleted | Looks for files which have been deleted but not yet expunged.
|
:read or :in |
The file is going to be read. This is the default.
|
:print or :write or :out |
The file is going to be written (i.e. a new version is going to be created).
|
:old | Looks only for files that already exist. This is the default.
|
:new-ok | Allows either a file that already exists or a file that does not yet exist.
An example of the use of this is the C-X C-F (Find File) command in the editor.
|
The first value returned is always a string containing a file name, either the
original string or a new, more specific string. The second value returned
indicates the success or failure of the completion. It is nil if an
error occurred. One possible error is that the file is on a file system that
does not support completion, in which case the original string is returned
unchanged. Other possible second values are :old, which means that the
string completed to the name of a file that exists, :new, which means that
the string completed to the name of a file that could be created, and nil
again, which means that there is no possible completion.
Balance Directories:
filespec1 filespec2 &rest options
fs:balance-directories is a function for maintaining multiple copies
of a directory. Often it is useful to maintain copies of your files on
more than one machine; this function provides a simple way of keeping
those copies up to date.
The function first parses filespec1, filling in missing components
with wildcards (except for the version, which is :newest). Then
filespec2 is parsed with filespec1 as the default. The
resulting pathnames are used to generate directory lists using
fs:directory-list. Note that the resulting directory lists need not
be entire directories; any subset of a directory that
fs:directory-list can produce will do.
First the directory lists are matched up on the basis of file name and
type. All of the files in either directory list which have both the
same name and the same type are grouped together.
The directory lists are next analyzed to determine if the directories
are consistent, meaning that two files with the same name and type have
equal creation-dates when their versions match, and greater versions
have later creation-dates. If any inconsistencies are found, a warning
message is printed on the console.
If the version specified for both filespec1 and filespec2 was
:newest (the default), then the newest version of each file in each
directory is copied to the other directory if it is not already
there. The result is that each directory has the newest copy
of every file in either of the two directories.
If one or both of the specified versions is not :newest, then every
version that appears in one directory list and not in the other is
copied. This has the result that the two directories are completely the
same. (Note that this is probably not the right thing to use to
copy an entire directory. Use copy-file with a wildcard
argument instead.)
The options are keywords arguments which modify the operation. The
following options are currently defined:
:ignore |
This option takes one argument, which is a list of file names to ignore
when making the directory lists. The default value is nil.
|
:error |
This option is identical to the :error option to open.
|
:query-mode |
This option takes one argument, which indicates whether or not the user
should be asked before files are transferred. If the argument is
nil, no querying is done. If it is :1->2, then only files
being transferred from filespec2 to filespec1 are queried,
while if it is :2->1, then files transferred from filespec1 to
filespec2 are queried. If the argument is :always, then
the user is asked about all files.
|
:copy-mode |
This option is identical to the :copy-mode option of copy-file,
and is used to control whether files are treated as binary or textual
data.
|
:direction | This option specifies transfer of files in one direction only.
If the value is :1->2 then files are transfered only from filespec1
to filespec2, never in the other direction. If the value is
:2->1 then files are transferred only from filespec2 to
filespec1. nil, the default, means transfer in either direction
as appropriate.
|
(error)
This flavor is the basis for all errors signaled by the file system.
It defines two special operations, :pathname and :operation.
Usually, these return the pathname of the file being operated on, and
the operation used. This operation was performed either on the pathname
object itself, or on a stream.
It defines prompting for the proceed types :retry-file-operation and
:new-pathname, both of which are provided for many file errors.
:retry-file-operation tries the operation again exactly as it was
requested by the program; :new-pathname expects on argument, a
pathname, and tries the same operation on this pathname instead of the
original one.
(fs:file-error)
This condition name signifies a problem with the file operation
requested. It is an alternative to fs:file-request-failure
(), which means that the file system
was unable to consider the operation properly.
All the following conditions in this section are always accompanied by
fs:file-operation-failure, fs:file-error, and error, so they
will not be mentioned.
The request cannot be performed because the file is open for output.
The file cannot be accessed because it is already being accessed. Just
which kinds of simultaneous access are allowed depends on the file
system.
A link could not be opened because it pointed, directly or indirectly
through other links, to itself. In fact, some systems report this condition
whenever a chain of links exceeds a fixed length.
In open, the specified byte size was not valid for the particular
file server or file.
Processing a request requires resources not available, such as
space in a directory, or free disk blocks.
The :set-pointer operation was used with a pointer value outside the bounds of the file.
A requested pack, file, etc. exists but is currently off line or not available to users.
This condition name categorizes all sorts of failure to find a specified file,
for any operation.
(fs:file-lookup-error)
The specified device does not exist.
(fs:file-lookup-error)
The specified directory does not exist.
(fs:file-lookup-error)
There is no file with the specified name, type and version.
This implies that the device and directory do exist,
or one of the errors described above would have been signaled.
(fs:file-lookup-error)
There is no file with the specified name and any of the
specified types, in with-open-file-search.
Three special operations are defined:
:operation | Returns the function which used with-open-file-search, such as load.
|
:pathname | The base pathname used.
|
:pathnames | A list of all the pathnames that were looked for.
|
(fs:file-lookup-error)
The file specified was a link, but the link's target filename
fails to be found.
The operation is possible, but the file server is insubordinate and refuses to
obey you.
(access-error).
(access-error).
The file server refuses to obey you because of protection attached to
the file (or, the directory).
A pathname had a wildcard in a place where the particular file server
does not support them. Such pathnames are not created by pathname
parsing, but they can be created with the :new-pathname operation.
A pathname with a wildcard was used in an operation that does not support it.
For example, opening a file with a wildcard in its name.
An operation was done on the wrong kind of file.
If files and directories share one name space and it is an error to open
a directory, the error possesses this condition name.
An attempt to create a file or directory failed for a reason
specifically connected with creation.
(fs:creation-failure)
The file or directory to be created already exists.
(fs:creation-failure fs:wrong-kind-of-file)
In file systems where directories and files share one name space, this
error results from an attempt to create a file using a filename
specifying a directory whose name exists in the file system but is not
a directory.
A file to be deleted exists, but for some reason cannot be deleted.
(fs:delete-failure)
A file could not be deleted because it is a directory and has files in it.
(fs:delete-failure)
A file could not be deleted because its ``don't delete'' flag is set.
A file to be renamed exists, but the renaming could not be done. The
:new-pathname operation on the condition instance returns the
specified new pathname, which may be a pathname or a string.
(fs:rename-failure)
Renaming cannot be done because there is already a file with the
specified new name.
(fs:rename-failure)
Renaming cannot be done because the new pathname contains a different
device or directory from the one the file is on. This may not always be
an error--some file systems support it in certain cases--but when
it is an error, it has this condition name.
(fs:change-property-failure)
A property name specified in a :change-properties operation is not
supported by the file server. (Some file servers support only a fixed
set of property names.) The :property operation on the condition
instance returns the problematical property name.
(fs:change-property-failure)
In a :change-properties operation, some property was given a value
that is not valid for it. The :property operation on the
condition instance returns the property name, and the :value
operation returns the specified value.
(fs:change-property-failure)
In a :change-properties operation, a syntactically invalid property
name was specified. This may be because it is too long to be stored.
The :property operation on the condition instance returns the
property name.
Files on remote file servers are accessed using file servers over
the Chaosnet. Normally connections to servers are established
automatically when you try to use them, but there are a few ways you can
interact with them explicitly.
When characters are written to a file server computer that
normally uses the ASCII character set to store text, Lisp Machine
characters are mapped into an encoding that is reasonably close to an
ASCII transliteration of the text. When a file is written, the
characters are converted into this encoding; the inverse
transformation is done when a file is read back. No information is
lost. Note that the length of a file, in characters, is not the
same measured in original Lisp Machine characters as it is measured in
the encoded ASCII characters. In the currently implemented ASCII file
servers, the following encoding is used. All printing characters and
any characters not mentioned explicitly here are represented as
themselves. Codes 010 (lambda), 011 (gamma), 012 (delta), 014
(plus-minus), 015 (circle-plus), 177 (integral), 200 through 207
inclusive, 213 (Delete), and 216 and anything higher, are preceded
by a 177; that is, 177 is used as a quoting character for these codes.
Codes 210 (Overstrike), 211 (Tab), 212 (Line), and 214 (Page), are
converted to their ASCII cognates, namely 010 (backspace), 011
(horizontal tab), 012 (line feed), and 014 (form feed) respectively.
Code 215 (Return) is converted into 015 (carriage return) followed by
012 (line feed). Code 377 is ignored completely, and so cannot be
stored in files.
When a file server is first created for you on a particular host, you
must tell the server how to log in on that host. This involves
specifying a username, and, if the obstructionists are in control
of your site, a password.
The Lisp Machine prompts you for these on the terminal when they are
needed.
Logging in a file server is not the same thing as logging in on the Lisp
Machine (see login, ). The latter identifies you as a
user in general and involves specifying one host, your login host. The
former identifies you to a particular file server host and must be done
for each host on which you access files. However, logging in on the
Lisp Machine does specify the username for your login host and logs in
a file server there.
The Lisp Machine uses your username (or the part that follows
the last period) as a first guess for your password (this happens to
take no extra time). If that does not work, you are asked to type a
password, or else a username and a password, on the keyboard. You do
not have to give the same user name that you are logged in as, since you
may have or use different user names on different machines.
Once a password is recorded for one host, the system uses that password
as the guess if you connect to a file server on another host.
This is an alist matching host names with the usernames you have
specified on those hosts. Each element is the cons of a host object and
the username, as a string.
For hosts running ITS, the symbol fs:its is used instead of a
host object. This is because every user has the same username on all
ITS hosts.
Once you have specified a password for a given username and host, it
is remembered for the duration of the session in this variable.
The value is a list of elements, each of the form
((username hostname) password)
All three data are strings.
The remembered passwords are used if more than one file server is needed
on the same host, or if the connection is broken and a new file server
needs to be created.
If you are very scared of your password being known, you can turn off
the recording by setting this variable:
Passwords are recorded when typed in if this variable is non-nil.
You should set the variable at the front of your init file, and also set
fs:user-host-password-alist to nil, since it will already have
recorded your password when you logged in.
If you do not use a file server for a period of time, it is killed to
save resources on the server host.
This is the length of time after which an idle file server connection
should be closed, in 60ths of a second. The default is 20 minutes.
Some hosts have a caste system in which all users are not equal. It is
sometimes necessary to enable one's privileges in order to exercise
them. This is done with these functions:
host &rest capabilities
Enables the named capabilities on file servers for the specified host.
capabilities is a list of strings, whose meanings depend on the
particular file system that is available on host.
If capabilities is nil, a default list of capabilities is
enabled; the default is also dependent on the operating system type.
host &rest capabilities
Disables the named capabilities on file servers for the specified host.
capabilities is a list of strings, whose meanings depend on the
particular file system that is available on host.
If capabilities is nil, a default list of capabilities is
disabled; the default is also dependent on the operating system type.
The PEEK utility has a mode that displays the status of all your file
connections, and of the host unit data structures that record them.
Clicking on a connection with the mouse gets a menu of operations, of
which the most interesting is reset. Resetting a host unit may
be useful if the connection becomes hung.
(fs:file-error error)
This condition name categorizes errors that prevent the file system from
processing the request made by the program.
The following condition names are always accompanied by the more general
classifications fs:file-request-failure, fs:file-error, and error.
This condition signifies inconsistent data found in the file system,
indicating a failure in the file system software or hardware.
This condition signifies that the file server host is up, but refusing
connections for file servers.
This condition signifies certain problems in the use of the Chaosnet by a file server,
such as failure to open a data connection when it is expected.
This condition signifies a shortage of resources needed to consider
processing a request, as opposed to resources used up by the request
itself. This may include running out of network connections or job
slots on the server host. It does not include running out of space in a
directory or running out of disk space, because these are resources
whose requirements come from processing the request.
This condition signifies that the particular file system fails to
implement a standardly defined operation; such as, expunging or
undeletion on ITS.