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.
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 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.
X3J13 voted in June 1989 to require rename-file to accept logical pathnames (see section 23.1.5).
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 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.
X3J13 voted in June 1989 to require delete-file to accept logical pathnames (see section 23.1.5).
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.
X3J13 voted in March 1988 to specify exactly which streams may be used as pathnames. See section 23.1.6.
X3J13 voted in June 1989 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 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 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.
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 24.3.1), or nil if this cannot be determined.X3J13 voted in March 1988 to specify exactly which streams may be used as pathnames. See section 23.1.6.
X3J13 voted in June 1989 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 to require file-write-date to accept logical pathnames (see section 23.1.5).
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 to specify exactly which streams may be used as pathnames. See section 23.1.6.
X3J13 voted in June 1989 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 to require file-author to accept logical pathnames (see section 23.1.5).
file-position returns or sets the current position within a random-access file.
(file-position le-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-position le-stream position) 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.
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).X3J13 voted in June 1989 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.