Next: Loading Files Up: File System Interface Previous: Opening and Closing
Common Lisp the Language, 2nd Edition
Next: Loading Files
Up: File System Interface
Previous: Opening and
Closing
These functions provide a standard interface to operations provided in some form by most file systems. It may be that some implementations of Common Lisp cannot support them all completely.
[Function]
rename-filefilenew-name
The specified file is renamed to new-name (which must be a file name). The file may be a string, a pathname, or a stream. If it is an open stream associated with a file, then the stream itself and the file associated with it are affected (if the file system permits).
X3J13 voted in March 1988 (PATHNAME-STREAM) to specify exactly which
streams may be used as pathnames. See section 23.1.6.
rename-file returns three values if successful. The
first value is the new-name with any missing components filled
in by performing a merge-pathnames operation using
file as the defaults. The second value is the
truename of the file before it was renamed. The third value
is the truename of the file after it was renamed.
If the renaming operation is not successful, an error is signaled.
It is an error to specify a file name containing a :wild
component, for file to contain a nil component
where the file system does not permit a nil component, or
for the result of defaulting missing components of new-name
from file to contain a nil component where the
file system does not permit a nil component.
X3J13 voted in June 1989 (PATHNAME-WILD) to specify that supplying a
wild pathname as the file argument to rename-file
has implementation-dependent consequences; rename-file
might signal an error, for example, or might rename all files that match
the wild pathname.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require
rename-file to accept logical pathnames (see section 23.1.5).
Compatibility note: This corresponds to the function
called renamef in MacLisp and Lisp Machine Lisp. The name
renamef is not used in Common Lisp because the convention
that a trailing f means ``file’’ conflicts with the use of
a trailing f for forms related to setf.
[Function]
delete-filefile
The specified file is deleted. The file may be a string, a pathname, or a stream. If it is an open stream associated with a file, then the stream itself and the file associated with it are affected (if the file system permits), in which case the stream may or may not be closed immediately, and the deletion may be immediate or delayed until the stream is explicitly closed, depending on the requirements of the file system.
X3J13 voted in March 1988 (PATHNAME-STREAM) to specify exactly which
streams may be used as pathnames. See section 23.1.6.
delete-file returns a non-nil value if
successful. It is left to the discretion of the implementation whether
an attempt to delete a non-existent file is considered to be successful.
If the deleting operation is not successful, an error is signaled.
It is an error to specify a file name that contains a
:wild component or one that contains a nil
component where the file system does not permit a nil
component.
X3J13 voted in June 1989 (PATHNAME-WILD) to clarify that supplying a
wild pathname as the file argument to delete-file
has implementation-dependent consequences; delete-file
might signal an error, for example, or might delete all files that match
the wild pathname.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require
delete-file to accept logical pathnames (see section 23.1.5).
Compatibility note: This corresponds to the function
called deletef in MacLisp and Lisp Machine Lisp.
[Function]
probe-filefile
This predicate is false if there is no file named file, and
otherwise returns a pathname that is the true name of the file (which
may be different from file because of file links, version
numbers, or other artifacts of the file system). Note that if the
file is an open stream associated with a file, then
probe-file cannot return nil but will produce
the true name of the associated file. See truename and the
:probe value for the :direction argument to
open.
This corresponds to the function called probef in
MacLisp and Lisp Machine Lisp.
X3J13 voted in March 1988 (PATHNAME-STREAM) to specify exactly which
streams may be used as pathnames. See section 23.1.6.
X3J13 voted in June 1989 (PATHNAME-WILD) to clarify that
probe-file accepts only non-wild pathnames; an error is
signaled if wild-pathname-p would be true of the
file argument.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require
probe-file to accept logical pathnames (see section 23.1.5). However,
probe-file never returns a logical pathname.
X3J13 voted in January 1989 (CLOSED-STREAM-OPERATIONS) to specify
that probe-file is unaffected by whether the first
argument, if a stream, is open or closed. If the first argument is a
stream, probe-file behaves as if the function
pathname were applied to the stream and the resulting
pathname used instead. However, X3J13 further commented that the
treatment of open streams may differ considerably from one
implementation to another; for example, in some operating systems open
files are written under a temporary or invisible name and later renamed
when closed. In general, programmers writing code intended to be
portable should be very careful when using
probe-file.
[Function]
file-write-datefile
file can be a file name or a stream that is open to a file.
This returns the time at which the file was created or last written as
an integer in universal time format (see section 25.4.1), or nil if this
cannot be determined.
X3J13 voted in March 1988 (PATHNAME-STREAM) to specify exactly which
streams may be used as pathnames. See section 23.1.6.
X3J13 voted in June 1989 (PATHNAME-WILD) to clarify that
file-write-date accepts only non-wild pathnames; an error
is signaled if wild-pathname-p would be true of the
file argument.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require
file-write-date to accept logical pathnames (see section 23.1.5).
[Function]
file-authorfile
file can be a file name or a stream that is open to a file.
This returns the name of the author of the file as a string, or
nil if this cannot be determined.
X3J13 voted in March 1988 (PATHNAME-STREAM) to specify exactly which
streams may be used as pathnames. See section 23.1.6.
X3J13 voted in June 1989 (PATHNAME-WILD) to clarify that
file-author accepts only non-wild pathnames; an error is
signaled if wild-pathname-p would be true of the
file argument.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require
file-author to accept logical pathnames (see section 23.1.5).
[Function]
file-positionfile-stream&optionalposition
file-position returns or sets the current position
within a random-access file.
(file-positionfile-stream)
returns a non-negative integer indicating the current position within
the file-stream, or nil if this cannot be
determined. The file position at the start of a file will be zero. The
value returned by file-position increases monotonically as
input or output operations are performed. For a character file,
performing a single read-char or write-char
operation may cause the file position to be increased by more than 1
because of character-set translations (such as translating between the
Common Lisp #\Newline character and an external ASCII
carriage-return/line-feed sequence) and other aspects of the
implementation. For a binary file, every read-byte or
write-byte operation increases the file position by 1.
(file-positionfile-streamposition)
sets the position within file-stream to be position.
The position may be an integer, or :start for the
beginning of the stream, or :end for the end of the stream.
If the integer is too large or otherwise inappropriate, an error is
signaled (the file-length function returns the length
beyond which file-position may not access). An integer
returned by file-position of one argument should, in
general, be acceptable as a second argument for use with the same file.
With two arguments, file-position returns t if
the repositioning was performed successfully, or nil if it
was not (for example, because the file was not random-access).
Implementation note: Implementations that have
character files represented as a sequence of records of bounded size
might choose to encode the file position as, for example,
record-number*256+character-within-record. This is a
valid encoding because it increases monotonically as each character is
read or written, though not necessarily by 1 at each step. An integer
might then be considered ``inappropriate’’ as a second argument to
file-position if, when decoded into record number and
character number, it turned out that the specified record was too short
for the specified character number.
Compatibility note: This corresponds to the function
called filepos in MacLisp and Lisp Machine Lisp.
[Function]
file-lengthfile-stream
file-stream must be a stream that is open to a file. The
length of the file is returned as a non-negative integer, or
nil if the length cannot be determined. For a binary file,
the length is specifically measured in units of the
:element-type specified when the file was opened (see
open).
Compatibility note: This corresponds to the function
called lengthf in MacLisp and Lisp Machine Lisp.
[Function]
file-string-lengthfile-streamobject
X3J13 voted in June 1989 (MORE-CHARACTER-PROPOSAL) to add the
function file-string-length. The object must be a
string or a character. The function file-string-length
returns a non-negative integer that is the difference between what the
file-position of the file-stream would be after
and before writing the object to the file-stream, or
nil if this difference cannot be determined. The value
returned may depend on the current state of the file-stream;
that is, calling file-string-length on the same arguments
twice may in certain circumstances produce two different integers.
Next: Loading Files
Up: File System Interface
Previous: Opening and
Closing
AI.Repository@cs.cmu.edu