chdir

Function

Package: EXCL

Arguments: (&optional directory)

This function is designed to mimic the UNIX/DOS cd utility. In short, it extracts the directory component of directory and changes the current working directory to that. If the directory component is relative, the new directory is determined relative to the current working directory (as returned by current-directory). directory can be a pathname object or a string. 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
0	not specified	Change to the current user's home directory on UNIX, to c:\ on Windows.
1	A pathname object	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).
2	A string containing a /, :, or ; naming a pathname	Convert to a pathname object, then continue as in item 1 of this table.
3	A string without a /, ;, or :.	Add a / to the end of the string, convert to a pathname object, then continue as in item 1 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 /acl5.0/.

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.
"/acl5.0/"
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/
"/tmp/"
user(20): (chdir)
"/usr/tech/doe/"
user(21):

Note 1. A / is added to the end of a string that does contain a /, ;, or : order that (chdir "tmp") will work as `cd tmp' does in UNIX and DOS: change to the tmp subdirectory of the current 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.

chdir returns the namestring of the directory component changed to (which may not be the new 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 (`./lisp.exe', for example), you cannot do the first load of foreign code or dump an image with excl: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 excl: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.)

The top-level commands :cd, :popd, and :pushd also change the current directory.

See 3.0 Environment functions in os_interface.htm for more information on the current directory.

The general documentation description is in introduction.htm. The index in index.htm.