Skip to main content

user-homedir-pathname

user-homedir-pathname Function

Syntax:

user-homedir-pathname &optional host → pathname

Arguments and Values:

host—a string, a list of strings, or :unspecific.

pathname—a pathname, or nil.

Description:

user-homedir-pathname determines the pathname that corresponds to the user’s home directory on host. If host is not supplied, its value is implementation-dependent. For a description of :unspecific, see Section 19.2.1 (Pathname Components).

The definition of home directory is implementation-dependent, but defined in Common Lisp to mean the directory where the user keeps personal files such as initialization files and mail.

user-homedir-pathname returns a pathname without any name, type, or version component (those components are all nil) for the user’s home directory on host.

If it is impossible to determine the user’s home directory on host, then nil is returned. user-homedir-pathname never returns nil if host is not supplied.

Examples:

(pathnamep (user-homedir-pathname)) → true

Affected By:

The host computer’s file system, and the implementation.

Expanded Reference: user-homedir-pathname​

Basic Usage​

user-homedir-pathname returns a pathname corresponding to the user's home directory. The optional host argument specifies which host to query, defaulting to the local machine.

(pathnamep (user-homedir-pathname))
;; => T

Inspecting the Result​

The returned value is a pathname object, so standard pathname functions can be used to examine it.

(let ((home (user-homedir-pathname)))
  (eq (first (pathname-directory home)) :absolute))
;; => T

Building File Paths Relative to Home​

A common use is constructing paths to configuration files or data directories within the user's home.

(pathnamep (merge-pathnames ".config/myapp/settings.conf"
                            (user-homedir-pathname)))
;; => T

(pathnamep (merge-pathnames "Documents/data.csv"
                            (user-homedir-pathname)))
;; => T

Checking for a File in the Home Directory​

You can combine the result with probe-file to check whether a specific file exists under the home directory.

(let ((init-file (merge-pathnames ".sbclrc" (user-homedir-pathname))))
  (stringp (if (probe-file init-file)
               (format nil "Init file found: ~A" init-file)
               (format nil "No init file at ~A" init-file))))
;; => T

Important Notes​

The function returns a pathname that always has a trailing directory component (it names a directory, not a file). If the home directory cannot be determined, the implementation may return a default or signal an error. The optional host parameter is relevant primarily for implementations supporting logical or remote pathnames.