35.9 Contents of Directories

A directory is a kind of file that contains other files entered under various names. Directories are a feature of the file system.

SXEmacs can list the names of the files in a directory as a Lisp list, or display the names in a buffer using the ls shell command. In the latter case, it can optionally display information about each file, depending on the value of switches passed to the ls command.

Function: directory-files directory &optional full-name match-regexp nosort files-only

This function returns a list of the names of the files in the directory directory. By default, the list is in alphabetical order.

If full-name is non-nil, the function returns the files’ absolute file names. Otherwise, it returns just the names relative to the specified directory.

If match-regexp is non-nil, this function returns only those file names that contain that regular expression—the other file names are discarded from the list.

If nosort is non-nil, directory-files does not sort the list, so you get the file names in no particular order. Use this if you want the utmost possible speed and don’t care what order the files are processed in. If the order of processing is visible to the user, then the user will probably be happier if you do sort the names.

If files-only is the symbol t, then only the “files” in the directory will be returned; subdirectories will be excluded. If files-only is not nil and not t, then only the subdirectories will be returned. Otherwise, if files-only is nil (the default) then both files and subdirectories will be returned.

(directory-files "~lewis")
     ⇒ ("#foo#" "#foo.el#" "." ".."
         "dired-mods.el" "files.texi"
         "files.texi.~1~")

An error is signaled if directory is not the name of a directory that can be read.

Moreover, there is a generalised function which also performs a recursive descent within a directory tree. This function is especially optimised for large recursion depths and has an outstanding performance.

Function: directory-files-recur directory &optional full match nosort files-only depth symlink_is_file

Like directory-files but recursive and much faster.

Optional argument depth (a positive integer) specifies the recursion depth, use 0 to emulate old directory-files.

Optional argument symlink_is_file specifies whether symlinks should be resolved (which is the default behaviour) or whether they are treated as ordinary files (non-nil), in the latter case symlinks to directories are not recurred.

(directory-files-recur "/sys/class/dvb")
  ⇒ ("./dvb0.demux0" "./dvb0.demux0/dev" "./dvb0.demux0/uevent"
      "./dvb0.dvr0" "./dvb0.dvr0/dev" "./dvb0.dvr0/uevent"
      "./dvb0.frontend0" "./dvb0.frontend0/dev"
      "./dvb0.frontend0/uevent" "./dvb0.net0" "./dvb0.net0/dev"
      "./dvb0.net0/uevent")

(directory-files-recur "/sys/class/dvb" t nil nil nil 0)
  ⇒ ("/sys/class/dvb/dvb0.demux0" "/sys/class/dvb/dvb0.dvr0"
      "/sys/class/dvb/dvb0.frontend0" "/sys/class/dvb/dvb0.net0")

Function: insert-directory file switches &optional wildcard full-directory-p

This function inserts (in the current buffer) a directory listing for directory file, formatted with ls according to switches. It leaves point after the inserted text.

The argument file may be either a directory name or a file specification including wildcard characters. If wildcard is non-nil, that means treat file as a file specification with wildcards.

If full-directory-p is non-nil, that means file is a directory and switches do not contain ‘-d’, so that the listing should show the full contents of the directory. (The ‘-d’ option to ls says to describe a directory itself rather than its contents.)

This function works by running a directory listing program whose name is in the variable insert-directory-program. If wildcard is non-nil, it also runs the shell specified by shell-file-name, to expand the wildcards.

Variable: insert-directory-program

This variable’s value is the program to run to generate a directory listing for the function insert-directory.