% -*- Mode: TeX -*- % Files % Directory % Directory Query % File Properties % Directory Modification %-------------------- Directory Query -------------------- %%% ========== DIRECTORY \begincom{directory}\ftype{Function} %% 23.5.0 3 \label Syntax:: \DefunWithValues directory {pathspec {\key}} {pathnames} \label Arguments and Values:: \issue{PATHNAME-LOGICAL:ADD} \param{pathspec}---a \term{pathname designator}, which may contain \term{wild} components. \endissue{PATHNAME-LOGICAL:ADD} \param{pathnames}---a \term{list} of \issue{PATHNAME-LOGICAL:ADD} \term{physical pathnames}. \endissue{PATHNAME-LOGICAL:ADD} \label Description:: %% 23.5.0 4 Determines which, if any, \term{files} that are present in the file system have names matching \param{pathspec}, and returns a \issue{RESULT-LISTS-SHARED:SPECIFY} \term{fresh} \endissue{RESULT-LISTS-SHARED:SPECIFY} \term{list} of \term{pathnames} corresponding to the \term{truenames} of those \term{files}. An \term{implementation} may be extended to accept \term{implementation-defined} keyword arguments to \funref{directory}. \label Examples:\None. \label Affected By:: The host computer's file system. \label Exceptional Situations:: \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} If the attempt to obtain a directory listing is not successful, an error \oftype{file-error} is signaled. \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label See Also:: \typeref{pathname}, \issue{PATHNAME-LOGICAL:ADD} \typeref{logical-pathname}, \endissue{PATHNAME-LOGICAL:ADD} \funref{ensure-directories-exist}, {\secref\FileSystemConcepts}, {\secref\OpenAndClosedStreams}, \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} {\secref\PathnamesAsFilenames} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label Notes:: If the \param{pathspec} is not \term{wild}, the resulting list will contain either zero or one elements. \clisp\ specifies ``{\key}'' in the argument list to \funref{directory} even though no \term{standardized} keyword arguments to \funref{directory} are defined. ``\f{:allow-other-keys t}'' may be used in \term{conforming programs} in order to quietly ignore any additional keywords which are passed by the program but not supported by the \term{implementation}. \endcom %%% ========== PROBE-FILE \begincom{probe-file}\ftype{Function} \label Syntax:: \DefunWithValues probe-file {pathspec} {truename} \label Arguments and Values:: \issue{PATHNAME-LOGICAL:ADD} \param{pathspec}---a \term{pathname designator}. \endissue{PATHNAME-LOGICAL:ADD} \issue{PATHNAME-LOGICAL:ADD} \param{truename}---a \term{physical pathname} or \nil. \endissue{PATHNAME-LOGICAL:ADD} \label Description:: \funref{probe-file} tests whether a file exists. %% 23.3.0 12 \funref{probe-file} returns \term{false} if there is no file named \param{pathspec}, and otherwise returns the \term{truename} of \param{pathspec}. If the \param{pathspec} \term{designator} is an open \term{stream}, then \funref{probe-file} produces the \term{truename} of its associated \term{file}. %!!! Sandra wonders if the following is implied by "pathname designator": \issue{CLOSED-STREAM-FUNCTIONS:ALLOW-INQUIRY} If \param{pathspec} is a \term{stream}, whether open or closed, it is coerced to a \term{pathname} as if by \thefunction{pathname}. \endissue{CLOSED-STREAM-FUNCTIONS:ALLOW-INQUIRY} \label Examples:\None. \label Affected By:: The host computer's file system. \label Exceptional Situations:: \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{PATHNAME-WILD:NEW-FUNCTIONS} An error \oftype{file-error} is signaled if \param{pathspec} is \term{wild}. \endissue{PATHNAME-WILD:NEW-FUNCTIONS} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} %% Wording changed per x3j13 (05-Oct-93) -kmp % If the probe attempt is not successful, % an error \oftype{file-error} is signaled. An error \oftype{file-error} is signaled if the \term{file system} cannot perform the requested operation. \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label See Also:: \funref{truename}, \funref{open}, \funref{ensure-directories-exist}, \typeref{pathname}, \issue{PATHNAME-LOGICAL:ADD} \typeref{logical-pathname}, \endissue{PATHNAME-LOGICAL:ADD} {\secref\FileSystemConcepts}, {\secref\OpenAndClosedStreams}, \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} {\secref\PathnamesAsFilenames} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label Notes:\None. \endcom %%% ========== ENSURE-DIRECTORIES-EXIST \begincom{ensure-directories-exist}\ftype{Function} \label Syntax:: \DefunWithValues ensure-directories-exist {pathspec {\key} verbose} {pathspec, created} \label Arguments and Values:: \param{pathspec}---a \term{pathname designator}. \param{verbose}---a \term{generalized boolean}. \param{created}---a \term{generalized boolean}. \label Description:: Tests whether the directories containing the specified \term{file} actually exist, and attempts to create them if they do not. If the containing directories do not exist and if \param{verbose} is \term{true}, then the \term{implementation} is permitted (but not required) to perform output to \term{standard output} saying what directories were created. If the containing directories exist, or if \param{verbose} is \term{false}, this function performs no output. The \term{primary value} is the given \term{pathspec} so that this operation can be straightforwardly composed with other file manipulation expressions. The \term{secondary value}, \param{created}, is \term{true} if any directories were created. \label Examples:\None. \label Affected By:: The host computer's file system. \label Exceptional Situations:: \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} %% Confusion over type of error signaled resolved by x3j13 05-Oct-93 %% (type-error => file-error). -kmp An error \oftype{file-error} is signaled if the host, device, or directory part of \param{pathspec} is \term{wild}. \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} If the directory creation attempt is not successful, an error \oftype{file-error} is signaled; if this occurs, it might be the case that none, some, or all of the requested creations have actually occurred within the \term{file system}. \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} %% Removed per X3J13 05-Oct-93. %% See first paragraph of Exceptional Situations above. -kmp % \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} % An error \oftype{file-error} might be signaled if \param{pathspec} % is a \term{designator} for a \term{wild} \term{pathname}. % \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label See Also:: \funref{probe-file}, \funref{open}, \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} {\secref\PathnamesAsFilenames} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label Notes:\None. \endcom %%% ========== TRUENAME \begincom{truename}\ftype{Function} \label Syntax:: \DefunWithValues truename {filespec} {truename} \label Arguments and Values:: \issue{PATHNAME-LOGICAL:ADD} \param{filespec}---a \term{pathname designator}. \endissue{PATHNAME-LOGICAL:ADD} \issue{PATHNAME-LOGICAL:ADD} \param{truename}---a \term{physical pathname}. \endissue{PATHNAME-LOGICAL:ADD} \label Description:: \funref{truename} tries to find the \term{file} indicated by \param{filespec} and returns its \term{truename}. %!!! Sandra wonders if the following is implied by "pathname designator": %% 23.1.2 6 If the \param{filespec} \term{designator} is an open \term{stream}, its associated \term{file} is used. \issue{CLOSED-STREAM-FUNCTIONS:ALLOW-INQUIRY} If \param{filespec} is a \term{stream}, \funref{truename} can be used whether the \term{stream} is open or closed. It is permissible for \funref{truename} to return more specific information after the \term{stream} is closed than when the \term{stream} was open. \endissue{CLOSED-STREAM-FUNCTIONS:ALLOW-INQUIRY} If \param{filespec} is a \term{pathname} it represents the name used to open the file. This may be, but is not required to be, the actual name of the file. \label Examples:: \code ;; An example involving version numbers. Note that the precise nature of ;; the truename is implementation-dependent while the file is still open. (with-open-file (stream ">vistor>test.text.newest") (values (pathname stream) (truename stream))) \EV #P"S:>vistor>test.text.newest", #P"S:>vistor>test.text.1" \OV #P"S:>vistor>test.text.newest", #P"S:>vistor>test.text.newest" \OV #P"S:>vistor>test.text.newest", #P"S:>vistor>_temp_._temp_.1" ;; In this case, the file is closed when the truename is tried, so the ;; truename information is reliable. (with-open-file (stream ">vistor>test.text.newest") (close stream) (values (pathname stream) (truename stream))) \EV #P"S:>vistor>test.text.newest", #P"S:>vistor>test.text.1" ;; An example involving TOP-20's implementation-dependent concept ;; of logical devices -- in this case, "DOC:" is shorthand for ;; "PS:" ... (with-open-file (stream "CMUC::DOC:DUMPER.HLP") (values (pathname stream) (truename stream))) \EV #P"CMUC::DOC:DUMPER.HLP", #P"CMUC::PS:DUMPER.HLP.13" \endcode \label Affected By:\None. \label Exceptional Situations:: An error \oftype{file-error} is signaled if an appropriate \term{file} cannot be located within the \term{file system} for the given \param{filespec}, \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} %% Additional constraint per x3j13 (05-Oct-93) -kmp or if the \term{file system} cannot perform the requested operation. \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{PATHNAME-WILD:NEW-FUNCTIONS} An error \oftype{file-error} is signaled if \param{pathname} is \term{wild}. \endissue{PATHNAME-WILD:NEW-FUNCTIONS} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label See Also:: \issue{PATHNAME-LOGICAL:ADD} \typeref{pathname}, \typeref{logical-pathname}, {\secref\FileSystemConcepts}, \endissue{PATHNAME-LOGICAL:ADD} \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} {\secref\PathnamesAsFilenames} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label Notes:: %% 23.1.2 7 \funref{truename} may be used to account for any \term{filename} translations performed by the \term{file system}. \endcom %-------------------- File Properties -------------------- %%% ========== FILE-AUTHOR \begincom{file-author}\ftype{Function} \label Syntax:: \DefunWithValues file-author {pathspec} {author} \label Arguments and Values:: \issue{PATHNAME-LOGICAL:ADD} \param{pathspec}---a \term{pathname designator}. \endissue{PATHNAME-LOGICAL:ADD} \param{author}---a \term{string} or \nil. \label Description:: %% 23.3.0 15 Returns a \term{string} naming the author of the \term{file} specified by \param{pathspec}, or \nil\ if the author's name cannot be determined. \label Examples:: \code (with-open-file (stream ">relativity>general.text") (file-author s)) \EV "albert" \endcode \label Affected By:: The host computer's file system. Other users of the \term{file} named by \param{pathspec}. \label Exceptional Situations:: \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{PATHNAME-WILD:NEW-FUNCTIONS} An error \oftype{file-error} is signaled if \param{pathspec} is \term{wild}. \endissue{PATHNAME-WILD:NEW-FUNCTIONS} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} %% Wording changed per x3j13 (05-Oct-93) -kmp % If the attempt to obtain authorship information is not successful, % an error \oftype{file-error} is signaled. An error \oftype{file-error} is signaled if the \term{file system} cannot perform the requested operation. \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label See Also:: \issue{PATHNAME-LOGICAL:ADD} \typeref{pathname}, \typeref{logical-pathname}, {\secref\FileSystemConcepts}, \endissue{PATHNAME-LOGICAL:ADD} \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} {\secref\PathnamesAsFilenames} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label Notes:\None. \endcom %%% ========== FILE-WRITE-DATE \begincom{file-write-date}\ftype{Function} \label Syntax:: \DefunWithValues file-write-date {pathspec} {date} \label Arguments and Values:: \issue{PATHNAME-LOGICAL:ADD} \param{pathspec}---a \term{pathname designator}. \endissue{PATHNAME-LOGICAL:ADD} \param{date}---a \term{universal time} or \nil. \label Description:: %% 23.3.0 14 Returns a \term{universal time} representing the time at which the \term{file} specified by \param{pathspec} was last written (or created), or returns \nil\ if such a time cannot be determined. \label Examples:: \code (with-open-file (s "noel.text" :direction :output :if-exists :error) (format s "~&Dear Santa,~2%I was good this year. ~ Please leave lots of toys.~2%Love, Sue~ ~2%attachments: milk, cookies~%") (truename s)) \EV #P"CUPID:/susan/noel.text" (with-open-file (s "noel.text") (file-write-date s)) \EV 2902600800 \endcode \label Affected By:: The host computer's file system. \label Exceptional Situations:: \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{PATHNAME-WILD:NEW-FUNCTIONS} An error \oftype{file-error} is signaled if \param{pathspec} is \term{wild}. \endissue{PATHNAME-WILD:NEW-FUNCTIONS} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} %% Wording changed per x3j13 (05-Oct-93) -kmp % If the attempt to obtain write-date information is not successful, % an error \oftype{file-error} is signaled. An error \oftype{file-error} is signaled if the \term{file system} cannot perform the requested operation. \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label See Also:: {\secref\UniversalTime}, \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} {\secref\PathnamesAsFilenames} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label Notes:\None. \endcom %-------------------- Directory Modification -------------------- %%% ========== RENAME-FILE \begincom{rename-file}\ftype{Function} \label Syntax:: \DefunWithValues rename-file {filespec new-name} {defaulted-new-name, old-truename, new-truename} \label Arguments and Values:: \issue{PATHNAME-LOGICAL:ADD} \param{filespec}---a \term{pathname designator}. \endissue{PATHNAME-LOGICAL:ADD} \param{new-name}---a \term{pathname designator} %!!! it used to say (or pathname string symbol), so I added this for now ... ?? other than a \term{stream}. \param{defaulted-new-name}---a \term{pathname} \param{old-truename}---a \term{physical pathname}. \param{new-truename}---a \term{physical pathname}. \label Description:: %% 23.3.0 3 \funref{rename-file} modifies the file system in such a way that the file indicated by \param{filespec} is renamed to %% Per X3J13. -kmp 05-Oct-93 %\param{new-name}. \param{defaulted-new-name}. %% 23.3.0 6 %!!! Sandra asks whether this first is a prohition on "filespec" or "new-name" or both? It is an error to specify a filename containing a \term{wild} component, for \param{filespec} to contain a \nil\ component where the file system does not permit a \nil\ component, or for the result of defaulting missing components of \param{new-name} from \param{filespec} to contain a \nil\ component where the file system does not permit a \nil\ component. \issue{PATHNAME-LOGICAL:ADD} If \param{new-name} is a \term{logical pathname}, \funref{rename-file} returns a \term{logical pathname} as its \term{primary value}. \endissue{PATHNAME-LOGICAL:ADD} %% 23.3.0 4 \funref{rename-file} returns three values if successful. The \term{primary value}, \param{defaulted-new-name}, is the resulting name which is composed of \param{new-name} with any missing components filled in by performing a \funref{merge-pathnames} operation using \param{filespec} as the defaults. The \term{secondary value}, \param{old-truename}, is the \term{truename} of the \term{file} before it was renamed. The \term{tertiary value}, \param{new-truename}, is the \term{truename} of the \term{file} after it was renamed. If the \param{filespec} \term{designator} is an open \term{stream}, then the \term{stream} itself and the file associated with it are affected (if the \term{file system} permits). \label Examples:: \code ;; An example involving logical pathnames. (with-open-file (stream "sys:chemistry;lead.text" :direction :output :if-exists :error) (princ "eureka" stream) (values (pathname stream) (truename stream))) \EV #P"SYS:CHEMISTRY;LEAD.TEXT.NEWEST", #P"Q:>sys>chem>lead.text.1" (rename-file "sys:chemistry;lead.text" "gold.text") \EV #P"SYS:CHEMISTRY;GOLD.TEXT.NEWEST", #P"Q:>sys>chem>lead.text.1", #P"Q:>sys>chem>gold.text.1" \endcode \label Affected By:\None. \label Exceptional Situations:: %% 23.3.0 5 If the renaming operation is not successful, an error \oftype{file-error} is signaled. \issue{PATHNAME-WILD:NEW-FUNCTIONS} An error \oftype{file-error} might be signaled if \param{filespec} is \term{wild}. %!!! Sandra asks whether this should extend to "new-name" as well? \endissue{PATHNAME-WILD:NEW-FUNCTIONS} \label See Also:: \issue{PATHNAME-LOGICAL:ADD} \funref{truename}, \typeref{pathname}, \typeref{logical-pathname}, {\secref\FileSystemConcepts}, \endissue{PATHNAME-LOGICAL:ADD} \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} {\secref\PathnamesAsFilenames} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label Notes:\None. \endcom %%% ========== DELETE-FILE \begincom{delete-file}\ftype{Function} \label Syntax:: \DefunWithValues delete-file {filespec} {\t} \label Arguments and Values:: \issue{PATHNAME-LOGICAL:ADD} \param{filespec}---a \term{pathname designator}. \endissue{PATHNAME-LOGICAL:ADD} \label Description:: Deletes the \term{file} specified by \param{filespec}. %!!! Sandra thinks this makes no sense. -kmp 12-Dec-91 If the \param{filespec} \term{designator} is an open \term{stream}, then \param{filespec} and the file associated with it are affected (if the file system permits), in which case \param{filespec} might be closed immediately, and the deletion might be immediate or delayed until \param{filespec} is explicitly closed, depending on the requirements of the file system. It is \term{implementation-dependent} whether an attempt to delete a nonexistent file is considered to be successful. %% 23.3.0 8 %% 23.3.0 9 \funref{delete-file} returns \term{true} if it succeeds, or signals an error \oftype{file-error} if it does not. %% 23.3.0 10 The consequences are undefined if \param{filespec} has a \term{wild} component, or if \param{filespec} has a \nil\ component and the file system does not permit a \nil\ component. \label Examples:: \code (with-open-file (s "delete-me.text" :direction :output :if-exists :error)) \EV NIL (setq p (probe-file "delete-me.text")) \EV #P"R:>fred>delete-me.text.1" (delete-file p) \EV T (probe-file "delete-me.text") \EV \term{false} (with-open-file (s "delete-me.text" :direction :output :if-exists :error) (delete-file s)) \EV T (probe-file "delete-me.text") \EV \term{false} \endcode \label Affected By:\None. \label Exceptional Situations:: If the deletion operation is not successful, an error \oftype{file-error} is signaled. \issue{PATHNAME-WILD:NEW-FUNCTIONS} An error \oftype{file-error} might be signaled if \param{filespec} is \term{wild}. \endissue{PATHNAME-WILD:NEW-FUNCTIONS} \label See Also:: \issue{PATHNAME-LOGICAL:ADD} \typeref{pathname}, \typeref{logical-pathname}, {\secref\FileSystemConcepts}, \endissue{PATHNAME-LOGICAL:ADD} \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} {\secref\PathnamesAsFilenames} \endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \label Notes:\None. \endcom %-------------------- File Errors -------------------- \begincom{file-error}\ftype{Condition Type} \label Class Precedence List:: \typeref{file-error}, \typeref{error}, \typeref{serious-condition}, \typeref{condition}, \typeref{t} \label Description:: \Thetype{file-error} consists of error conditions that occur during an attempt to open or close a file, or during some low-level transactions with a file system. The ``offending pathname'' is initialized by \theinitkeyarg{pathname} to \funref{make-condition}, and is \term{accessed} by \thefunction{file-error-pathname}. \label See Also:: \function{file-error-pathname}, \funref{open}, \funref{probe-file}, \funref{directory}, \funref{ensure-directories-exist} \endcom%{file-error}\ftype{Condition Type} %%% ========== FILE-ERROR-PATHNAME \begincom{file-error-pathname}\ftype{Function} \label Syntax:: \DefunWithValues file-error-pathname {condition} {pathspec} \label Arguments and Values:: \param{condition}---a \term{condition} \oftype{file-error}. \param{pathspec}---a \term{pathname designator}. \label Description:: Returns the ``offending pathname'' of a \term{condition} \oftype{file-error}. \label Examples:\None. \label Side Effects:\None. \label Affected By:\None. \label Exceptional Situations:: % This might signal an error (probably TYPE-ERROR, but you can't say that % because it's not been voted in yet) if argument is not of correct type. % (Part of the issue here is whether anyone might define other signatures.) \label See Also:: \typeref{file-error}, {\secref\Conditions} \label Notes:\None. %% Removed because no primitive is provided to do this! -kmp %It is an error to use \macref{setf} with \funref{file-error-pathname}. \endcom