The Revised Maclisp ManualThe PitmanualPage A-19
Published by HyperMeta Inc.
Prev | Index | Next
[Blue Marble]
Climate Change
What is the carbon footprint of a hamburger?
What if we ate less meat?


File names

NamestringConceptSimple Filename Format

The simplest kind of file specification is a plain textual description of the file desired. This can be in the form of either a symbol (or string in implementations with strings). It has no structure and its meaning or even validity as file name specifier varies from implementation to implementation. Typically, Maclisp programs try to carry around filenames internally as namelists and use the namestring format when displaying filenames to users, especially users who might not be familiar with Lisp's namelist format.

Namestrings may be fully qualified specifications (those with all the parts of the filename present):

Tops-20 "PS:<JD>MY.FILE.3" 
Multics ">udd>RedTape>MoreRedTape>JDoe>my.file" 

They may also have parts omitted (which will be filled in by merging with other filenames later or which Lisp will fill in automatically with its default filenames if the parts are still unfilled when you try to actually reference such partially filled out filenames).

ITS "DSK: MY FILE" ; No directory 
Tops-20 "<JD>*.FOO" ; No device, filename1, or version 
"FOO.*; Only the filename1 is specified 

Users of Tops-20 should take note of the fact that "*" in Maclisp almost never means to quantify over all matching files, as it would for most other programs. Rather, it just means that this part of the name has been omitted. Maclisp handling of the Tops-20 file system leaves something to be desired, to say the least. It does fairly well considering it was not at all designed originally to handle this sort of file structure, but it has a lot of deficiencies. The "*" wildcard convention is not supported in any of the default primitives.

Using symbols instead of strings will also work. This is primarily useful in loading files interactively. Remember, of course, that odd symbols must be syntactically quoted with slash or vertical bars. e.g.,

ITS FOO/;BAR ; Directory and filename1 only 
Tops-20 BAR/.LSP ; Filename1 and filename2 only 
either FOO ;Filename1 only 

NamelistConceptStructured Filename Format

An alternative to the somewhat `flat' representation of filenames as namestrings is the namelist format. Namelists, being lists, have some structure to them and even offer some illusion of file system independence if used correctly.

Simple namelist formats look like:

ITS ((dev dir) fn1 fn2) 
Tops-20 ((dev dir) fn1 fn2 version) 
Multics (dir fn1 fn2) 

For example:

Multics (>udd>JRGensym foo bar) ; >udd>JRGensym> 

It is also possible to omit components from a namelist. This can be done by the user in either of two ways. Either he can place *'s in place of the omitted components or he can actually omit the relevant part of the list (if it is the tail of the list). If the system creates a partially specified namelist, it will never omit parts of the structure, but rather will always use the format with *'s in the omitted fields. Lisp tries to be smart about omitted directories and devices. Hence, if it sees only one item in the (dir dev) spec, it will assume it is a directory unless it knows it to be a device. If this ambiguity disturbs you, use a * in the field you wish to not specify. Here are some typical examples of partial filespecs and their meanings under common file systems. Note that the same filespec in namelist format can often have a useful meaning on either of the two systems:

Filename On ITS... On Tops-20... 
(X Y) X Y X.Y 
((FOO *) X Y) FOO:X Y FOO:X.Y 
((* FOO) X Y) FOO;X Y <FOO>X.Y 

There is also an old-style namelist format which is for compatibility with Old-I/O. Its use is not recommended. It has the form:

ITS (fn1 fn2 dev dir) 
Tops-20 (fn1 fn2 [version] dev dir) 

Loading into Lisp

LOADFunction(LOAD filespec)

Opens filespec for input and causes its contents to be be executed.

If the file is an ASCII file, it reads and evaluates successive forms in the file (without printing their return values), returning T when done. If the file is a FASL file (compiled code), it is fasloaded and a fixnum is returned (see FASLOAD).

By convention, if (SSTATUS FEATURE NOLDMSG) has been done, files do not type out the normal “;Loading ...” message (see HERALD).

Note: In versions of lisp before 1914, if an error occurs during the load, the file object will not get closed until the garbage-collection which follows.

Web-Only Note:

It was brought to my attention that the wording for this last note is bad. I meant ^^version^^ 1914, not before the year 1914. I left the bad wording in place rather than quietly fix it in case anyone had been waiting all these years to have that clarified.

FASLOADSpecial Form(FASLOAD . namelist)

Loads a FASL file into the lisp environment. namelist is not evaluated.

The return value is a fixnum. It is poor style to rely on the meaning of the return value, though it happens to be the new value of the variable BPORG.

Note: FASLOAD'ing within a FASLOAD works pretty well. Naturally, you can only FASLOAD between functions; “Evaluated constants” (see SQUID) within a function may not do FASLOAD's. If you don't understand this last item, don't worry -- it's not the sort of thing you're likely to do by accident.


[PDP-10 Only] The variable FASLOAD is bound to a list of property names which fasload should warn about if something in the current fasl file is clobbering an already existing copy of. Setting (or binding) FASLOAD to NIL will muffle redefinition warnings. Alternatively, one can be more paranoid and set it to more conservative values, such as (EXPR SUBR LSUBR FEXPR FSUBR ARRAY MACRO), which will warn about redefining any of these properties on a symbol during a FASLOAD.

INCLUDESpecial Form(INCLUDE . namelist)

INCLUDE is a special form which takes a file name. If this form is evaluated in the course of UREAD'ing or LOAD'ing a file, the effect is to include the text of the inserted file in place of the include. The compiler will also respect INCLUDE's at toplevel.



INCLUDEFFunction(INCLUDEF filespec)

This is just like INCLUDE, but it evaluates the filename first. This is so that site-dependent or filesystem-dependent tests can be placed in the argument (see (STATUS OPSYS), etc.)

Manipulating Filenames

DEFAULTFFunction(DEFAULTF filespec)

Merges filespec with the current file defaults, changing the file defaults to the merged value, which is also returned.

Similar to (SETQ DEFAULTF (MERGEF filespec DEFAULTF)).


[PDP-10 Only] This variable contains the default filename to be used by Lisp file-I/O operations when an incomplete file descriptor is named in a primitive file-I/O interaction. It is usually not assigned directly; more commonly it is manipulated via the DEFAULTF function.

It is sometimes useful to bind DEFAULTF to itself to keep the file defaults from changing during the execution of some expression. For example, if it is known that F is a function that changes the file defaults (i.e., assigns DEFAULTF), such changes can be suppressed when undesirable by binding DEFAULTF around the call to F as in:



Returns the truename of the file (tracing any file links, converting > or .0 files to their actual version number, reading through any links and making any specified ITS file translations.) The result is in namelist format. (On ITS, it is the name returned by the .RCHST system call on the file's channel.)

MERGEFFunction(MERGEF filespec1 filespec2)

MERGEF is used for applying defaults to file specifiers, which may be namelists or namestrings. Returns a namelist obtained by selecting components from filespec1 and filespec2, which are converted to namelists. If any component of filespec1 is *, the corresponding component of filespec2 is selected in its place. It is an error if filespec2 is not that long (*** is it? ***). When a component of filespec1 is not *, it is selected and the corresponding component of filespec2 is skipped. If either filespec1 or filespec2 ends with a dotted atom other than a *, this atom is added to the end of the namelist if it's not already there. (*** What is this about? ***) If filespec1 ends with a dotted *, the rest of filespec2 is copied over.

(MERGEF x NIL) strips off the last component of x.

*** Note: This documentation is very old and I can't imagine that it's even remotely correct any more. Take it all with a grain of salt and we'll fix the description some day!


(MERGEF '((A B) * *) '((D E) F G)) => ((A B) F G)

NAMELISTFunction(NAMELIST filespec)

Namelist converts its argument to a namelist. Omitted or * components in the argument produce *'s in the result.




Namestring converts its argument from a namelist to a namestring. It is the opposite of namelist.




SHORTNAMESTRING is just like NAMESTRING except that there is no mention of directory or device in the resulting string.


(shortnamestring '(abc d e)) => "d.e" ; Tops-20

Miscellaneous File Utility Functions

LENGTHFFunction(LENGTHF fileobj)

[PDP-10 Only] Argument must be a (not-necessarily-open) SFA or file object. Returns the length of the file object -- if open in ASCII mode, then in characters; if open in FIXNUM mode, then in words.

FASLPFunction(FASLP filename)

[PDP-10 Only] Returns T if filename names a FASL file and NIL otherwise. This actually opens the file and checks its format.

Creating, Naming, Moving, etc.

PROBEFFunction(PROBEF filename)

[PDP-10 Only] Returns NIL if filename doesn't exist. Returns the truename of filename if it does exist.

RENAMEFFunction(RENAMEF oldfilename newfilename)

[PDP-10 Only] Renames a file. If oldfilename is a file object, the file is closed in the process.

DELETEFFunction(DELETEF filespec)

Where filespec specifies a file, deletes that file. The return value is the namelist of the file actually deleted, i.e. filespec MERGEF'd over the defaults.


(deletef "")	=> (>udd>ap>junk foo bar) ; Multics
(deletef '|foo bar|)	=> ((ml loser) foo bar)   ; ITS

Multiple-File Access

Mapping Over FilesConceptStar Conventions

There are several functions which allow users to do actions (using a star convention) to all files which match a partially specified filename.

The namelists used by ALLFILES, MAPALLFILES, DIRECTORY, and MAPDIRECTORY may have omitted or starred components which have the following meaning:

As a device, the DSK device. 
As a directory, matches any directories on DSK
 the default directory on other devices. 
As a first filename, matches any files with that first filename. 
As a second filename, matches any files with that second filename. 
As a version, matches any files with that version. 

As a safety feature, the namestring "*" is not permitted.

This is a powerful and necessary facility, but please use *extreme* care when mapping any kind of operation over files using a star convention. Tellers of Maclisp lore are quick to relate the tale of a poor Maclisp user who used an overly general pattern match on a system with very little built-in protection and deleted a major portion of the file system before he realized what was happening...


The argument, spec, is a list of partially specified namelists. The return value is a list of namelists which are precise (i.e. do not contain any stars or dotted parts) specifications of all files in the file system which match the given spec. Whatever search rules are customary in the particular operating system are used. There is no guarantee as to the order of the filenames returned. To obtain an ordering, use SORT or SORTCAR on the result.

ALLFILES with a precise namelist as an argument can be used as a predicate to determine whether or not a file exists (or you could use PROBEF).


[ITS and TOPS-10 Only] This just applies fn to each file matched by namelists as in

(MAPC fn (ALLFILES namelists))

but it saves consing the intermediate list which would be the return value from ALLFILES.

DIRECTORYFunction(DIRECTORY namelists [props])

[ITS and TOPS-10 Only] If props is not supplied, this is like (ALLFILES namelists) but instead of namelists, it returns a list of file descriptors where each descriptor has a namelist in the car and a property list in the cdr. Typical properties are:

WORDS size of file in PDP-10 words. 
CHARACTERS size of file in ascii characters. 
BITS size in bits. 
BYTESIZE size of bytes file was written in. 
BYTES size of file in bytes. 
CREDATE date of creation. 
CRETIME time of creation. 
REFDATE date of most recent reference. 
LINK On ITS, name linked to. 
PACK On ITS, pack number. 
 On TOPS-10, structure name and unit number (e.g., DSKB0
UNDUMPED On ITS, T if file not yet backed up on magtape. 
NOREAP On ITS, T if the don't-reap bit is set. 
AUTHOR On TOPS-10, author's ppn. 
PROTECTION On TOPS-10, protection code. 
MODE On TOPS-10, mode written in. 
VERSION On TOPS-10, version number from RIB. 
SPOOL On TOPS-10, spooling name. 

If props is supplied, only those properties are mentioned in the property list. As a special case, if LINK does not appear in the properties, no info about files which are links will be supplied at all.

MAPDIRECTORYFunction(MAPDIRECTORY fn namelists [props])

[ITS and TOPS-10 Only] This just like doing

(MAPC fn (DIRECTORY namelists [props]))

but, as with MAPALLFILES, it saves consing the intermediate list which would be the return value from DIRECTORY.

[Blue Marble]
Climate Change
Are you part of the problem
or part of the solution?

The Revised Maclisp Manual (Sunday Morning Edition)
Published Sunday, December 16, 2007 06:17am EST, and updated Sunday, July 6, 2008.
Prev | Index | Next