chdir

Function

Package: excl

ToC

DocOverview

CGDoc

RelNotes

FAQ

Index

PermutedIndex

Allegro CL version 9.0
Moderate update since 9.0 release.
8.2 version

chdir

Arguments: &optional directory

The :osi module has additional functionality relating to file handling. The symbol excl:chdir is exported from the new excl.osi package (as well as from the excl package). See OSI file handling functionality in os-interface.htm.

This function is designed to mimic the UNIX/DOS cd utility. directory, if supplied, must be a pathname or sting naming a directory (it cannot name a file). Assuming it exists, that directory will become the current working directory. If the directory is relative, the new directory is determined relative to the current working directory (as returned by current-directory). If directory is a string and does not contain a trailing / (so "/usr/tmp" rather than "/usr/tmp/" -- backslashes can be used when on Windows), it is filled in automatically.

If you happen to have the pathname of a file, applying either path-namestring or path-pathname to it will return a value suitable as an argument to chdir:

(setq path (pathname "/net/gemini/home/dm/xml-fns.cl"))
(chdir path) -> ERROR
(chdir (path-pathname path)) RETURNS "/net/gemini/home/dm/"
(chdir (path-namestring path)) RETURNS "/net/gemini/home/dm/"

This function does not modify the value of *default-pathname-defaults*. Therefore, after calling this function, it is likely that the current directory, as returned by current-directory, will be differrent from the directory specified in *default-pathname-defaults*. The related top-level command :cd does modify the value of *default-pathname-defaults*. The following form modifies both the current directory and *default-pathname-defaults*:

(setf *default-pathname-defaults* (pathname (chdir directory)))

Because of a mismatch between UNIX and Common Lisp interpreting of strings naming directories, string arguments are handled specially, as we describe now. The following table shows the behavior of chdir given various values of pathname:

pathname is	Action by chdir
not specified	Change to the current user's home directory. (See What user-homedir-pathname does on Windows in implementation.htm for a discussion of what a home directory means on Windows.)
A pathname object naming a directory	Extract the directory component of the pathname (translating first if it is a logical pathname). Change to that directory. Relative pathnames are resolved with respect to the current working directory (as returned by current-directory). This will not work is the pathname object names a file.
A string containing a /, : (colon), or ; (semicolon) naming a directory pathname (perhaps missing a final /)	Convert to a pathname object, then continue as in the `A pathname object' row of this table. See Note 1 below.
A string without a /, : (colon), or ; (semicolon).	Add a / to the end of the string, convert to a pathname object, then continue as in the `A pathname object' row of this table. See Note 1 below.

Examples. The current Unix user's home directory is /usr/tech/doe/. The directory /usr/tech/doe/tmp/ exists. The Allegro directory for the Lisp image is assumed to be /usr/local/acl/ though the actual value contains by default the release number and is in any case user-settable.

user(15): (chdir) ;; no argument: change to user home directory
"/usr/tech/doe/"
user(16): (chdir "sys:") 
   ;; a string naming a logical pathname which translates
   ;; to the Allegro directory (the value you see may be different
   ;; usually containing the release number).
"/usr/local/acl/"
user(17): (chdir)
"/usr/tech/doe/"
user(18): (chdir "tmp") ;; change to the tmp/ subdirectory
"tmp/"
user(19): (chdir (make-pathname :directory "tmp")) 
   ;; The absolute directory 
"/tmp/"
user(20): (chdir)
"/usr/tech/doe/"
user(21):

Note 1. A / is added to the end of a string that may contain a /, ;, or : but does not end in a / in order that (chdir "tmp") will work as `cd tmp' does in UNIX and DOS: change to the tmp subdirectory of the current directory. Also (chdir "/usr/tmp") will work as 'cd /usr/tmp' does, change to the tmp subdirectory of the /usr/ directory. Following the ANSI CL spec, (make-pathname :directory "tmp") creates the absolute pathname object with namestring "/tmp/" while (make-pathname :directory "tmp/") creates the relative pathname with namestring "tmp/". It is the second that follows the UNIX paradigm. Appending a / guarantees that effect. This means the directory argument cannot name a file. If there is a file named tmp in the /usr/ directory, when (chdir "/usr/tmp") adds a trailing /, it will then error because /usr/tmp/ does not name a directory.

chdir returns the namestring of the directory component of the pathname changed to. This may not be the new current directory (as returned by current-directory).

Warning about interaction between chdir and foreign loading and dumplisp: if the command line used to start Lisp identified the Allegro CL image with a relative pathname (`./mlisp', for example), you cannot do the first load of foreign code or dump an image with dumplisp after changing the directory with this function. Therefore, if you started Lisp with a relative pathname, do at least one foreign load before calling chdir and do not call dumplisp after calling chdir. (The problem is that when doing the first foreign load or a dumplisp, Lisp needs to examine the running image, which it finds by examining the command line that invoked the image. If Lisp is identified on the command line with a relative pathname and the current directory has been changed, the relative pathname merged with the current directory no longer points to the running image. Changing back to the original current directory fixes the problem.)

See :cd, :popd, and :pushd, which also change the current directory. See also os-interface.htm for general information on the interface between Allegro CL and the operating system.