287 lines
15 KiB
HTML
287 lines
15 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
|
||
|
|
<!Converted with LaTeX2HTML 0.6.5 (Tue Nov 15 1994) by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds >
|
||
|
|
<HEAD>
|
||
|
|
<TITLE>23.3. Renaming, Deleting, and Other File Operations</TITLE>
|
||
|
|
</HEAD>
|
||
|
|
<BODY>
|
||
|
|
<meta name="description" value=" Renaming, Deleting, and Other File Operations">
|
||
|
|
<meta name="keywords" value="clm">
|
||
|
|
<meta name="resource-type" value="document">
|
||
|
|
<meta name="distribution" value="global">
|
||
|
|
<P>
|
||
|
|
<b>Common Lisp the Language, 2nd Edition</b>
|
||
|
|
<BR> <HR><A NAME=tex2html4252 HREF="node217.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html4250 HREF="node202.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html4244 HREF="node215.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html4254 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html4255 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
||
|
|
<B> Next:</B> <A NAME=tex2html4253 HREF="node217.html"> Loading Files</A>
|
||
|
|
<B>Up:</B> <A NAME=tex2html4251 HREF="node202.html"> File System Interface</A>
|
||
|
|
<B> Previous:</B> <A NAME=tex2html4245 HREF="node215.html"> Opening and Closing </A>
|
||
|
|
<HR> <P>
|
||
|
|
<H1><A NAME=SECTION002730000000000000000>23.3. Renaming, Deleting, and Other File Operations</A></H1>
|
||
|
|
<P>
|
||
|
|
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.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>rename-file <i>file</i> <i>new-name</i></tt><P>The specified <i>file</i> is renamed to <i>new-name</i> (which must be a file name).
|
||
|
|
The <i>file</i> 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).
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in March 1988
|
||
|
|
(PATHNAME-STREAM) <A NAME=27378> </A>
|
||
|
|
to specify exactly which streams may be used as pathnames.
|
||
|
|
See section <A HREF="node214.html#PATHNAMEFUNCTIONS">23.1.6</A>.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<tt>rename-file</tt> returns three values if successful. The first value
|
||
|
|
is the <i>new-name</i> with any missing components filled in by performing
|
||
|
|
a <tt>merge-pathnames</tt> operation using <i>file</i> as the defaults.
|
||
|
|
The second value is the <tt>truename</tt> of the file before it was renamed.
|
||
|
|
The third value is the <tt>truename</tt> of the file after it was renamed.
|
||
|
|
<P>
|
||
|
|
If the renaming operation is not successful, an error is signaled.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="old_change_begin" src="gif/old_change_begin.gif"><br>
|
||
|
|
It is an error to specify a file name containing a <tt>:wild</tt> component,
|
||
|
|
for <i>file</i> to contain a <tt>nil</tt> component where the file system does
|
||
|
|
not permit a <tt>nil</tt> component, or for the result of defaulting missing
|
||
|
|
components of <i>new-name</i> from <i>file</i> to contain a <tt>nil</tt> component
|
||
|
|
where the file system does not permit a <tt>nil</tt> component.
|
||
|
|
<br><img align=bottom alt="old_change_end" src="gif/old_change_end.gif">
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-WILD) <A NAME=27398> </A>
|
||
|
|
to specify that supplying a wild pathname
|
||
|
|
as the <i>file</i> argument to <tt>rename-file</tt> has implementation-dependent consequences;
|
||
|
|
<tt>rename-file</tt> might signal an error, for example,
|
||
|
|
or might rename all files that match the wild pathname.
|
||
|
|
<P>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-LOGICAL) <A NAME=27404> </A> to require <tt>rename-file</tt>
|
||
|
|
to accept logical pathnames (see section <A HREF="node208.html#LOGICALPATHNAMESSECTION">23.1.5</A>).
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Compatibility note:</b> This corresponds to the function
|
||
|
|
called <tt>renamef</tt> in MacLisp and Lisp Machine Lisp.
|
||
|
|
The name <tt>renamef</tt> is not used in Common Lisp
|
||
|
|
because the convention that a trailing <tt>f</tt> means ``file''
|
||
|
|
conflicts with the use of a trailing <tt>f</tt>
|
||
|
|
for forms related to <tt>setf</tt>.
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>delete-file <i>file</i></tt><P>The specified <i>file</i> is deleted. The <i>file</i> 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.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in March 1988
|
||
|
|
(PATHNAME-STREAM) <A NAME=27420> </A>
|
||
|
|
to specify exactly which streams may be used as pathnames.
|
||
|
|
See section <A HREF="node214.html#PATHNAMEFUNCTIONS">23.1.6</A>.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="old_change_begin" src="gif/old_change_begin.gif"><br>
|
||
|
|
<tt>delete-file</tt> returns a non-<tt>nil</tt> 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.
|
||
|
|
<P>
|
||
|
|
It is an error to specify a file name that contains a <tt>:wild</tt> component
|
||
|
|
or one that contains a <tt>nil</tt> component where the file system does not
|
||
|
|
permit a <tt>nil</tt> component.
|
||
|
|
<br><img align=bottom alt="old_change_end" src="gif/old_change_end.gif">
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-WILD) <A NAME=27431> </A>
|
||
|
|
to clarify that supplying a wild pathname
|
||
|
|
as the <i>file</i> argument to <tt>delete-file</tt> has implementation-dependent consequences;
|
||
|
|
<tt>delete-file</tt> might signal an error, for example,
|
||
|
|
or might delete all files that match the wild pathname.
|
||
|
|
<P>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-LOGICAL) <A NAME=27437> </A> to require <tt>delete-file</tt>
|
||
|
|
to accept logical pathnames (see section <A HREF="node208.html#LOGICALPATHNAMESSECTION">23.1.5</A>).
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Compatibility note:</b> This corresponds to the function
|
||
|
|
called <tt>deletef</tt> in MacLisp and Lisp Machine Lisp.
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>probe-file <i>file</i></tt><P>This predicate is false if there is no file named <i>file</i>,
|
||
|
|
and otherwise returns a pathname that is the true name of the file
|
||
|
|
(which may be different from <i>file</i> because of file links, version
|
||
|
|
numbers, or other artifacts of the file system).
|
||
|
|
Note that if the <i>file</i> is an open stream associated with a file,
|
||
|
|
then <tt>probe-file</tt> cannot return <tt>nil</tt> but will produce the
|
||
|
|
true name of the associated file.
|
||
|
|
See <tt>truename</tt> and the <tt>:probe</tt> value for the
|
||
|
|
<tt>:direction</tt> argument to <tt>open</tt>.
|
||
|
|
<P>
|
||
|
|
This corresponds to the function
|
||
|
|
called <tt>probef</tt> in MacLisp and Lisp Machine Lisp.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in March 1988
|
||
|
|
(PATHNAME-STREAM) <A NAME=27459> </A>
|
||
|
|
to specify exactly which streams may be used as pathnames.
|
||
|
|
See section <A HREF="node214.html#PATHNAMEFUNCTIONS">23.1.6</A>.
|
||
|
|
<P>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-WILD) <A NAME=27463> </A>
|
||
|
|
to clarify that <tt>probe-file</tt> accepts only non-wild pathnames;
|
||
|
|
an error is signaled if <tt>wild-pathname-p</tt> would be true of
|
||
|
|
the <i>file</i> argument.
|
||
|
|
<P>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-LOGICAL) <A NAME=27469> </A> to require <tt>probe-file</tt>
|
||
|
|
to accept logical pathnames (see section <A HREF="node208.html#LOGICALPATHNAMESSECTION">23.1.5</A>).
|
||
|
|
However, <tt>probe-file</tt> never returns a logical pathname.
|
||
|
|
<P>
|
||
|
|
X3J13 voted in January 1989
|
||
|
|
(CLOSED-STREAM-OPERATIONS) <A NAME=27475> </A>
|
||
|
|
to specify that <tt>probe-file</tt> is unaffected by
|
||
|
|
whether the first argument, if a stream, is open or closed. If the first
|
||
|
|
argument is a stream, <tt>probe-file</tt> behaves as if the function <tt>pathname</tt>
|
||
|
|
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 <tt>probe-file</tt>.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>file-write-date <i>file</i></tt><P><i>file</i> 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 <A HREF="node232.html#TIMESECTION">25.4.1</A>),
|
||
|
|
or <tt>nil</tt> if this cannot be determined.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in March 1988
|
||
|
|
(PATHNAME-STREAM) <A NAME=27487> </A>
|
||
|
|
to specify exactly which streams may be used as pathnames.
|
||
|
|
See section <A HREF="node214.html#PATHNAMEFUNCTIONS">23.1.6</A>.
|
||
|
|
<P>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-WILD) <A NAME=27491> </A>
|
||
|
|
to clarify that <tt>file-write-date</tt> accepts only non-wild pathnames;
|
||
|
|
an error is signaled if <tt>wild-pathname-p</tt> would be true of
|
||
|
|
the <i>file</i> argument.
|
||
|
|
<P>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-LOGICAL) <A NAME=27497> </A> to require <tt>file-write-date</tt>
|
||
|
|
to accept logical pathnames (see section <A HREF="node208.html#LOGICALPATHNAMESSECTION">23.1.5</A>).
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>file-author <i>file</i></tt><P><i>file</i> 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 <tt>nil</tt> if this cannot be determined.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in March 1988
|
||
|
|
(PATHNAME-STREAM) <A NAME=27506> </A>
|
||
|
|
to specify exactly which streams may be used as pathnames.
|
||
|
|
See section <A HREF="node214.html#PATHNAMEFUNCTIONS">23.1.6</A>.
|
||
|
|
<P>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-WILD) <A NAME=27510> </A>
|
||
|
|
to clarify that <tt>file-author</tt> accepts only non-wild pathnames;
|
||
|
|
an error is signaled if <tt>wild-pathname-p</tt> would be true of
|
||
|
|
the <i>file</i> argument.
|
||
|
|
<P>
|
||
|
|
X3J13 voted in June 1989 (PATHNAME-LOGICAL) <A NAME=27516> </A> to require <tt>file-author</tt>
|
||
|
|
to accept logical pathnames (see section <A HREF="node208.html#LOGICALPATHNAMESSECTION">23.1.5</A>).
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>file-position <i>file-stream</i> &optional <i>position</i></tt><P><tt>file-position</tt> returns or sets the current position within
|
||
|
|
a random-access file.
|
||
|
|
<P>
|
||
|
|
<tt>(file-position <i>file-stream</i>)</tt> returns a non-negative integer
|
||
|
|
indicating the current position within the <i>file-stream</i>, or <tt>nil</tt> if
|
||
|
|
this cannot be determined. The file position at the start of a file will
|
||
|
|
be zero. The value returned by <tt>file-position</tt> increases monotonically
|
||
|
|
as input or output operations are performed. For a character file,
|
||
|
|
performing a single <tt>read-char</tt> or <tt>write-char</tt> 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
|
||
|
|
<tt>#\Newline</tt> character and an external ASCII
|
||
|
|
carriage-return/line-feed sequence) and other aspects of the
|
||
|
|
implementation. For a binary file, every <tt>read-byte</tt> or <tt>write-byte</tt>
|
||
|
|
operation increases the file position by 1.
|
||
|
|
<P>
|
||
|
|
<tt>(file-position <i>file-stream</i> <i>position</i>)</tt> sets the position within
|
||
|
|
<i>file-stream</i> to be <i>position</i>. The <i>position</i> may be an integer,
|
||
|
|
or <tt>:start</tt> for the beginning of the stream, or <tt>:end</tt> for the end of the
|
||
|
|
stream.
|
||
|
|
If the integer is too large or otherwise inappropriate, an error
|
||
|
|
is signaled (the <tt>file-length</tt> function returns the length beyond
|
||
|
|
which <tt>file-position</tt> may not access). An integer returned by
|
||
|
|
<tt>file-position</tt> of one argument should, in general, be acceptable
|
||
|
|
as a second argument for use with the same file.
|
||
|
|
With two arguments,
|
||
|
|
<tt>file-position</tt> returns <tt>t</tt> if the repositioning was performed
|
||
|
|
successfully, or <tt>nil</tt> if it was not (for example,
|
||
|
|
because the file was not random-access).
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Implementation note:</b> Implementations that have character files represented
|
||
|
|
as a sequence of records of bounded size might choose to encode the
|
||
|
|
file position as, for example,
|
||
|
|
<i>record-number</i>*256+<i>character-within-record</i>.
|
||
|
|
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 <tt>file-position</tt> if, when decoded into
|
||
|
|
record number and character number, it turned out that the
|
||
|
|
specified record was too short for the specified character number.
|
||
|
|
<hr>
|
||
|
|
<b>Compatibility note:</b> This corresponds to the function
|
||
|
|
called <tt>filepos</tt> in MacLisp and Lisp Machine Lisp.
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>file-length <i>file-stream</i></tt><P><i>file-stream</i> must be a stream that is open to a file.
|
||
|
|
The length of the file is returned as a non-negative integer,
|
||
|
|
or <tt>nil</tt> if the length cannot be determined.
|
||
|
|
For a binary file,
|
||
|
|
the length is specifically
|
||
|
|
measured in units of the <tt>:element-type</tt> specified
|
||
|
|
when the file was opened (see <tt>open</tt>).
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Compatibility note:</b> This corresponds to the function
|
||
|
|
called <tt>lengthf</tt> in MacLisp and Lisp Machine Lisp.
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>file-string-length <i>file-stream</i> <i>object</i></tt><P>
|
||
|
|
X3J13 voted in June 1989 (MORE-CHARACTER-PROPOSAL) <A NAME=27566> </A> to add
|
||
|
|
the function <tt>file-string-length</tt>.
|
||
|
|
The <i>object</i> must be a string or a character. The function
|
||
|
|
<tt>file-string-length</tt> returns a non-negative integer
|
||
|
|
that is the difference between what the <tt>file-position</tt> of the
|
||
|
|
<i>file-stream</i> would be after and before writing the <i>object</i>
|
||
|
|
to the <i>file-stream</i>, or <tt>nil</tt> if this
|
||
|
|
difference cannot be determined. The value returned may
|
||
|
|
depend on the current state of the <i>file-stream</i>; that is, calling
|
||
|
|
<tt>file-string-length</tt> on the same arguments twice may in certain circumstances
|
||
|
|
produce two different integers.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<BR> <HR><A NAME=tex2html4252 HREF="node217.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html4250 HREF="node202.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html4244 HREF="node215.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html4254 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html4255 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
||
|
|
<B> Next:</B> <A NAME=tex2html4253 HREF="node217.html"> Loading Files</A>
|
||
|
|
<B>Up:</B> <A NAME=tex2html4251 HREF="node202.html"> File System Interface</A>
|
||
|
|
<B> Previous:</B> <A NAME=tex2html4245 HREF="node215.html"> Opening and Closing </A>
|
||
|
|
<HR> <P>
|
||
|
|
<HR>
|
||
|
|
<P><ADDRESS>
|
||
|
|
AI.Repository@cs.cmu.edu
|
||
|
|
</ADDRESS>
|
||
|
|
</BODY>
|