Common Lisp the Language, 2nd Edition

Next: Loading Files Up: File System Interface Previous: Opening and Closing

# 23.3. Renaming, Deleting, and Other File Operations

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-file file new-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-file file`

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-file file`

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-date 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 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-author file`

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-position file-stream &optional position`

`file-position` returns or sets the current position within a random-access file.

`(file-position file-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 file-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.

Compatibility note: This corresponds to the function called `filepos` in MacLisp and Lisp Machine Lisp.

[Function]
`file-length file-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-length file-stream object`

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