Programming Language - Common Lisp 20. Files

Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.
Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT
Programming Language|Common Lisp
20. Files
Files i ii Programming Language|Common Lisp

20.1 File System Concepts Since treatment of open streams by the le system may vary considerably between implementa-
tions , however, a closed stream might be the most reliable kind of argument for some of these
This section describes the Common Lisp interface to le systems. The model used by this in- functions|in particular, those in Figure 20{3. For example, in some le systems , open les are
terface assumes that les are named by lenames , that a lename can be represented by a written under temporary names and not renamed until closed and/or are held invisible until
pathname object , and that given a pathname a stream can be constructed that connects to a le closed . In general, any code that is intended to be portable should use such functions carefully.
whose lename it represents.
For information about opening and closing les , and manipulating their contents, see Chapter 21 directory probe-le truename
(Streams).
Figure 20{3. File Functions where Closed Streams Might Work Best
Figure 20{1 lists some operators that are applicable to les and directories.
compile-le le-length open
delete-le
directory
le-position
le-write-date
probe-le
rename-le
20.1.3 Truenames
le-author load with-open-le Many le systems permit more than one lename to designate a particular le .
Figure 20{1. File and Directory Operations Even where multiple names are possible, most le systems have a convention for generating a
canonical lename in such situations. Such a canonical lename (or the pathname representing
such a lename ) is called a truename .
The truename of a le may dier from other lenames for the le because of symbolic links,
20.1.1 Coercion of Streams to Pathnames version numbers, logical device translations in the le system , logical pathname translations
within Common Lisp, or other artifacts of the le system .
A stream associated with a le is either a le stream or a synonym stream whose target is a
stream associated with a le . Such streams can be used as pathname designators . The truename for a le is often, but not necessarily, unique for each le . For instance, a Unix le
with multiple hard links could have several truenames .
Normally, when a stream associated with a le is used as a pathname designator , it denotes the
pathname used to open the le ; this may be, but is not required to be, the actual name of the
le . 20.1.3.1 Examples of Truenames
Some functions, such as truename and delete-le, coerce streams to pathnames in a dierent way For example, a DEC TOPS-20 system with les PS:<JOE>FOO.TXT.1 and PS:<JOE>FOO.TXT.2
that involves referring to the actual le that is open, which might or might not be the le whose might permit the second le to be referred to as PS:<JOE>FOO.TXT.0, since the \.0" notation
name was opened originally. Such special situations are always notated specically and are not denotes \newest" version of several les . In the same le system , a \logical device" \JOE:"
the default. might be taken to refer to PS:<JOE>" and so the names JOE:FOO.TXT.2 or JOE:FOO.TXT.0 might
refer to PS:<JOE>FOO.TXT.2. In all of these cases, the truename of the le would probably be
PS:<JOE>FOO.TXT.2.
20.1.2 File Operations on Open and Closed Streams If a le is a symbolic link to another le (in a le system permitting such a thing), it is conven-
Many functions that perform le operations accept either open or closed streams as arguments ; tional for the truename to be the canonical name of the le after any symbolic links have been
see Section 21.1.3 (Stream Arguments to Standardized Functions). followed; that is, it is the canonical name of the le whose contents would become available if an
Of these, the functions in Figure 20{2 treat open and closed streams dierently. input stream to that le were opened.
In the case of a le still being created (that is, of an output stream open to such a le ), the exact
delete-le le-author probe-le truename of the le might not be known until the stream is closed. In this case, the function
directory le-write-date truename truename might return dierent values for such a stream before and after it was closed. In fact,
before it is closed, the name returned might not even be a valid name in the le system |for
Figure 20{2. File Functions that Treat Open and Closed Streams Dierently example, while a le is being written, it might have version :newest and might only take on
a specic numeric value later when the le is closed even in a le system where all les have
numeric versions.
Files 20{1 20{2 Programming Language|Common Lisp

directory Function pathspec |a pathname designator .

truename |a physical pathname or nil.
Syntax: Description:
directory pathspec &key ! pathnames probe-le tests whether a le exists.
Arguments and Values: probe-le returns false if there is no le named pathspec , and otherwise returns the truename of
pathspec |a pathname designator , which may contain wild components. pathspec .
pathnames |a list of physical pathnames . If the pathspec designator is an open stream , then probe-le produces the truename of its
Description: associated le . If pathspec is a stream , whether open or closed, it is coerced to a pathname as if
by the function pathname.
Determines which, if any, les that are present in the le system have names matching pathspec ,
and returns a fresh list of pathnames corresponding to the truenames of those les . Aected By:
An implementation may be extended to accept implementation-dened keyword arguments to The host computer's le system.
directory. Exceptional Situations:
Aected By: An error of type le-error is signaled if pathspec is wild .
The host computer's le system. An error of type le-error is signaled if the le system cannot perform the requested operation.
Exceptional Situations: See Also:
If the attempt to obtain a directory listing is not successful, an error of type le-error is signaled. truename, open, ensure-directories-exist, pathname, logical-pathname, Section 20.1 (File
System Concepts), Section 21.1.1.1.2 (Open and Closed Streams), Section 19.1.2 (Pathnames as
See Also: Filenames)
pathname, logical-pathname, ensure-directories-exist, Section 20.1 (File System Concepts),
Notes:
Section 21.1.1.1.2 (Open and Closed Streams), Section 19.1.2 (Pathnames as Filenames) ensure-directories-exist Function
If the pathspec is not wild , the resulting list will contain either zero or one elements. Syntax:
Common Lisp species \&key" in the argument list to directory even though no standardized
keyword arguments to directory are dened. \:allow-other-keys t" may be used in conforming
ensure-directories-exist pathspec &key verbose ! pathspec, created
programs in order to quietly ignore any additional keywords which are passed by the program but Arguments and Values:
not supported by the implementation . pathspec |a pathname designator .
verbose |a generalized boolean .
probe-le Function created |a generalized boolean .
Description:
Syntax: Tests whether the directories containing the specied le actually exist, and attempts to create
probe-le pathspec ! truename them if they do not.
Arguments and Values:

If the containing directories do not exist and if verbose is true , then the implementation is (values (pathname stream)
permitted (but not required) to perform output to standard output saying what directories were
!
(truename stream)))
created. If the containing directories exist, or if verbose is false , this function performs no output.
!
#P"S:>vistor>test.text.newest", #P"S:>vistor>test.text.1"
or
!
#P"S:>vistor>test.text.newest", #P"S:>vistor>test.text.newest"
The primary value is the given pathspec so that this operation can be straightforwardly composed or
#P"S:>vistor>test.text.newest", #P"S:>vistor> temp . temp .1"
with other le manipulation expressions. The secondary value , created , is true if any directories
were created. ;; In this case, the file is closed when the truename is tried, so the
Aected By: ;; truename information is reliable.

(with-open-file (stream ">vistor>test.text.newest")
The host computer's le system. (close stream)
Exceptional Situations: (values (pathname stream)
!
(truename stream)))
An error of type le-error is signaled if the host, device, or directory part of pathspec is wild . #P"S:>vistor>test.text.newest", #P"S:>vistor>test.text.1"
If the directory creation attempt is not successful, an error of type le-error is signaled; if this
occurs, it might be the case that none, some, or all of the requested creations have actually ;; An example involving TOP-20's implementation-dependent concept
occurred within the le system . ;; of logical devices -- in this case, "DOC:" is shorthand for
;; "PS:<DOCUMENTATION>" ...
See Also: (with-open-file (stream "CMUC::DOC:DUMPER.HLP")
probe-le, open, Section 19.1.2 (Pathnames as Filenames) (values (pathname stream)
!
(truename stream)))
#P"CMUC::DOC:DUMPER.HLP", #P"CMUC::PS:<DOCUMENTATION>DUMPER.HLP.13"
truename Function Exceptional Situations:

An error of type le-error is signaled if an appropriate le cannot be located within the le
system for the given lespec , or if the le system cannot perform the requested operation.
Syntax:
! truename
truename lespec An error of type le-error is signaled if pathname is wild .
Arguments and Values: See Also:
lespec |a pathname designator . pathname, logical-pathname, Section 20.1 (File System Concepts), Section 19.1.2 (Pathnames as
Filenames)
truename |a physical pathname .
Notes:
Description: truename may be used to account for any lename translations performed by the le system .
truename tries to nd the le indicated by lespec and returns its truename . If the lespec
designator is an open stream , its associated le is used. If lespec is a stream , truename can be
used whether the stream is open or closed. It is permissible for truename to return more specic
information after the stream is closed than when the stream was open. If lespec is a pathname le-author Function
it represents the name used to open the le. This may be, but is not required to be, the actual
name of the le. Syntax:
Examples: le-author pathspec ! author
;; An example involving version numbers. Note that the precise nature of Arguments and Values:
;; the truename is implementation-dependent while the file is still open. pathspec |a pathname designator .
(with-open-file (stream ">vistor>test.text.newest")

author |a string or nil. (format s "~&Dear Santa,~2%I was good this year. ~
Description: Please leave lots of toys.~2%Love, Sue~

~2%attachments: milk, cookies~%")
Returns a string naming the author of the le specied by pathspec , or nil if the author's name
!
(truename s))
cannot be determined. #P"CUPID:/susan/noel.text"
Examples: (with-open-file (s "noel.text")
!
(file-write-date s))
2902600800
(with-open-file (stream ">relativity>general.text")
!
(file-author s)) Aected By:
"albert" The host computer's le system.
Aected By: Exceptional Situations:
The host computer's le system. An error of type le-error is signaled if pathspec is wild .
Other users of the le named by pathspec . An error of type le-error is signaled if the le system cannot perform the requested operation.
Exceptional Situations: See Also:
An error of type le-error is signaled if pathspec is wild . Section 25.1.4.2 (Universal Time), Section 19.1.2 (Pathnames as Filenames)
An error of type le-error is signaled if the le system cannot perform the requested operation.
See Also:
pathname, logical-pathname, Section 20.1 (File System Concepts), Section 19.1.2 (Pathnames as
rename-le Function
Filenames)
Syntax:
rename-le lespec new-name ! defaulted-new-name, old-truename, new-truename
le-write-date Function Arguments and Values:
lespec |a pathname designator .
Syntax: new-name |a pathname designator other than a stream .
le-write-date pathspec ! date
defaulted-new-name |a pathname
pathspec |a pathname designator . old-truename |a physical pathname .
date |a universal time or nil. new-truename |a physical pathname .
Description: Description:
Returns a universal time representing the time at which the le specied by pathspec was last rename-le modies the le system in such a way that the le indicated by lespec is renamed to
written (or created), or returns nil if such a time cannot be determined. defaulted-new-name .
Examples: It is an error to specify a lename containing a wild component, for lespec to contain a nil
component where the le system does not permit a nil component, or for the result of defaulting
(with-open-file (s "noel.text" missing components of new-name from lespec to contain a nil component where the le system
:direction :output :if-exists :error) does not permit a nil component.

If new-name is a logical pathname , rename-le returns a logical pathname as its primary value . If the lespec designator is an open stream , then lespec and the le associated with it are
aected (if the le system permits), in which case lespec might be closed immediately, and
rename-le returns three values if successful. The primary value , defaulted-new-name , is the re- the deletion might be immediate or delayed until lespec is explicitly closed, depending on the
sulting name which is composed of new-name with any missing components lled in by performing requirements of the le system.
a merge-pathnames operation using lespec as the defaults. The secondary value , old-truename ,
is the truename of the le before it was renamed. The tertiary value , new-truename , is the true- It is implementation-dependent whether an attempt to delete a nonexistent le is considered to be
name of the le after it was renamed. successful.
If the lespec designator is an open stream , then the stream itself and the le associated with it delete-le returns true if it succeeds, or signals an error of type le-error if it does not.
are aected (if the le system permits).
The consequences are undened if lespec has a wild component, or if lespec has a nil compo-
Examples: nent and the le system does not permit a nil component.
;; An example involving logical pathnames. Examples:
(with-open-file (stream "sys:chemistry;lead.text"
!
:direction :output :if-exists :error) (with-open-file (s "delete-me.text" :direction :output :if-exists :error))
!
(princ "eureka" stream) NIL
!
(setq p (probe-file "delete-me.text")) #P"R:>fred>delete-me.text.1"
!
(values (pathname stream) (truename stream)))
! false
#P"SYS:CHEMISTRY;LEAD.TEXT.NEWEST", #P"Q:>sys>chem>lead.text.1" (delete-file p) T
(probe-file "delete-me.text")
!
(rename-file "sys:chemistry;lead.text" "gold.text")
#P"SYS:CHEMISTRY;GOLD.TEXT.NEWEST", (with-open-file (s "delete-me.text" :direction :output :if-exists :error)
!
#P"Q:>sys>chem>lead.text.1", (delete-file s))
! false
#P"Q:>sys>chem>gold.text.1" T
(probe-file "delete-me.text")
Exceptional Situations: Exceptional Situations:
If the renaming operation is not successful, an error of type le-error is signaled.
If the deletion operation is not successful, an error of type le-error is signaled.
An error of type le-error might be signaled if lespec is wild .
An error of type le-error might be signaled if lespec is wild .
See Also: See Also:
truename, pathname, logical-pathname, Section 20.1 (File System Concepts), Section 19.1.2
(Pathnames as Filenames) pathname, logical-pathname, Section 20.1 (File System Concepts), Section 19.1.2 (Pathnames as
Filenames)
delete-le Function le-error Condition Type

Syntax: Class Precedence List:
!t
delete-le lespec
le-error, error, serious-condition, condition, t
Arguments and Values: Description:
lespec |a pathname designator .
The type le-error consists of error conditions that occur during an attempt to open or close
Description: a le, or during some low-level transactions with a le system. The \oending pathname" is
Deletes the le specied by lespec . initialized by the :pathname initialization argument to make-condition, and is accessed by the
function le-error-pathname.

See Also:
le-error-pathname, open, probe-le, directory, ensure-directories-exist
le-error-pathname Function
Syntax:
le-error-pathname condition ! pathspec
condition|a condition of type le-error.
pathspec |a pathname designator .
Description:
Returns the \oending pathname" of a condition of type le-error.
Exceptional Situations:
See Also:
le-error, Chapter 9 (Conditions)

Programming Language - Common Lisp 20. Files

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Programming Language - Common Lisp 20. Files

Transféré par

Droits d'auteur :

Formats disponibles

Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.

Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT