CD(1POSIX)

from the POSIX Programmer's Manual — CD(1POSIX) 💖

okay bestie, this is the one that moves your entire existence to a different folder. let's go 🦋

🌸 PROLOG 🌸

This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux. 😭

---

✨ NAME ✨

cd — change the working directory 💅

🎀 SYNOPSIS 🎀

cd [-L|-P] [directory]

cd -

💜 DESCRIPTION 💜

The cd utility shall change the working directory of the current shell execution environment (see Section 2.12, Shell Execution Environment) by executing the following steps in sequence. (In the following steps, the symbol curpath represents an intermediate value used to simplify the description of the algorithm used by cd. There is no requirement that curpath be made visible to the application.) 👑

1. If no directory operand is given and the HOME environment variable is empty or undefined, the default behavior is implementation-defined and no further steps shall be taken.
2. If no directory operand is given and the HOME environment variable is set to a non-empty value, the cd utility shall behave as if the directory named in the HOME environment variable was specified as the directory operand. 🏠
3. If the directory operand begins with a <slash> character, set curpath to the operand and proceed to step 7.
4. If the first component of the directory operand is dot or dot-dot, proceed to step 6.
5. Starting with the first pathname in the <colon>-separated pathnames of CDPATH (see the ENVIRONMENT VARIABLES section) if the pathname is non-null, test if the concatenation of that pathname, a <slash> character if that pathname did not end with a <slash> character, and the directory operand names a directory. If the pathname is null, test if the concatenation of dot, a <slash> character, and the operand names a directory. In either case, if the resulting string names an existing directory, set curpath to that string and proceed to step 7. Otherwise, repeat this step with the next pathname in CDPATH until all pathnames have been tested. 🔍
6. Set curpath to the directory operand.
7. If the -P option is in effect, proceed to step 10. If curpath does not begin with a <slash> character, set curpath to the string formed by the concatenation of the value of PWD, a <slash> character if the value of PWD did not end with a <slash> character, and curpath.
8. The curpath value shall then be converted to canonical form as follows, considering each component from beginning to end, in sequence:
   • a. Dot components and any <slash> characters that separate them from the next component shall be deleted.
   • b. For each dot-dot component, if there is a preceding component and it is neither root nor dot-dot, then:
     • i. If the preceding component does not refer (in the context of pathname resolution with symbolic links followed) to a directory, then the cd utility shall display an appropriate error message and no further steps shall be taken.
     • ii. The preceding component, all <slash> characters separating the preceding component from dot-dot, dot-dot, and all <slash> characters separating dot-dot from the following component (if any) shall be deleted.
   • c. An implementation may further simplify curpath by removing any trailing <slash> characters that are not also leading <slash> characters, replacing multiple non-leading consecutive <slash> characters with a single <slash>, and replacing three or more leading <slash> characters with a single <slash>. If, as a result of this canonicalization, the curpath variable is null, no further steps shall be taken.
9. If curpath is longer than {PATH_MAX} bytes (including the terminating null) and the directory operand was not longer than {PATH_MAX} bytes (including the terminating null), then curpath shall be converted from an absolute pathname to an equivalent relative pathname if possible. This conversion shall always be considered possible if the value of PWD, with a trailing <slash> added if it does not already have one, is an initial substring of curpath. Whether or not it is considered possible under other circumstances is unspecified. Implementations may also apply this conversion if curpath is not longer than {PATH_MAX} bytes or the directory operand was longer than {PATH_MAX} bytes.
10. The cd utility shall then perform actions equivalent to the chdir() function called with curpath as the path argument. If these actions fail for any reason, the cd utility shall display an appropriate error message and the remainder of this step shall not be executed. If the -P option is not in effect, the PWD environment variable shall be set to the value that curpath had on entry to step 9 (i.e., before conversion to a relative pathname). If the -P option is in effect, the PWD environment variable shall be set to the string that would be output by pwd -P. If there is insufficient permission on the new directory, or on any parent of that directory, to determine the current working directory, the value of the PWD environment variable is unspecified. 😬

If, during the execution of the above steps, the PWD environment variable is set, the OLDPWD environment variable shall also be set to the value of the old working directory (that is the current working directory immediately prior to the call to cd).

---

💅 OPTIONS 💅

The cd utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.

The following options shall be supported by the implementation:

• -L — Handle the operand dot-dot logically; symbolic link components shall not be resolved before dot-dot components are processed (see steps 8. and 9. in the DESCRIPTION). 🧠
• -P — Handle the operand dot-dot physically; symbolic link components shall be resolved before dot-dot components are processed (see step 7. in the DESCRIPTION). 🔥

If both -L and -P options are specified, the last of these options shall be used and all others ignored. If neither -L nor -P is specified, the operand shall be handled dot-dot logically; see the DESCRIPTION. ✨

---

🌈 OPERANDS 🌈

The following operands shall be supported:

• directory — An absolute or relative pathname of the directory that shall become the new working directory. The interpretation of a relative pathname by cd depends on the -L option and the CDPATH and PWD environment variables. If directory is an empty string, the results are unspecified. 🙈
• - — When a <hyphen-minus> is used as the operand, this shall be equivalent to the command:

cd "$OLDPWD" && pwd

which changes to the previous working directory and then writes its name. 🔁

---

🍓 STDIN 🍓

Not used. 💀

🧚 INPUT FILES 🧚

None.

---

👑 ENVIRONMENT VARIABLES 👑

The following environment variables shall affect the execution of cd:

• CDPATH — A <colon>-separated list of pathnames that refer to directories. The cd utility shall use this list in its attempt to change the directory, as described in the DESCRIPTION. An empty string in place of a directory pathname represents the current directory. If CDPATH is not set, it shall be treated as if it were an empty string. 🗺️
• HOME — The name of the directory, used when no directory operand is specified. 🏡
• LANG — Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
• LC_ALL — If set to a non-empty string value, override the values of all the other internationalization variables.
• LC_CTYPE — Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments).
• LC_MESSAGES — Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
• NLSPATH — Determine the location of message catalogs for the processing of LC_MESSAGES.
• OLDPWD — A pathname of the previous working directory, used by cd -. ⏪
• PWD — This variable shall be set as specified in the DESCRIPTION. If an application sets or unsets the value of PWD, the behavior of cd is unspecified. 🚨

---

🌙 ASYNCHRONOUS EVENTS 🌙

Default.

⭐ STDOUT ⭐

If a non-empty directory name from CDPATH is used, or if cd - is used, an absolute pathname of the new working directory shall be written to the standard output as follows:

"%s\n", <new directory>

Otherwise, there shall be no output. 🤫

💜 STDERR 💜

The standard error shall be used only for diagnostic messages.

🫶 OUTPUT FILES 🫶

None.

🦋 EXTENDED DESCRIPTION 🦋

None.

---

🔥 EXIT STATUS 🔥

The following exit values shall be returned:

• 0 — The directory was successfully changed. 🎉
• >0 — An error occurred. 😭

😤 CONSEQUENCES OF ERRORS 😤

The working directory shall remain unchanged. periodt.

The following sections are informative.

---

💖 APPLICATION USAGE 💖

Since cd affects the current shell execution environment, it is always provided as a shell regular built-in. If it is called in a subshell or separate utility execution environment, such as one of the following:

(cd /tmp)
nohup cd
find . -exec cd {} \;

it does not affect the working directory of the caller's environment. 😭

The user must have execute (search) permission in directory in order to change to it. 🔑

---

🌸 EXAMPLES 🌸

The following template can be used to perform processing in the directory specified by location and end up in the current working directory in use before the first cd command was issued:

cd location
if [ $? -ne 0 ]
then
    print error message
    exit 1
fi
... do whatever is desired as long as the OLDPWD environment variable
    is not modified
cd -

---

and bestie, that's only part 1 of this page — more is coming, don't go anywhere ✨

🌸 RATIONALE 🌸

ok so bestie, let's talk why any of this exists 💭

CDPATH? Yeah, that came in with the System V shell. And the way it works is literally analogous to how the PATH variable works in the shell — same energy, different department. The BSD C shell had its own lil version of this, a shell parameter called cdpath. iykyk 🫶

---

Now, a common extension: when HOME is undefined, you can grab the login directory straight from the user database for whoever's invoking the thing. Cute, right? But this does not occur on System V implementations — so don't go expecting it there, fr fr 🙈

---

Okay here's the tea 🍵 Some historical shells — the KornShell, for example — would do something extra special when the directory name had a dot-dot component in it. Instead of grabbing the actual parent directory, they'd select the logical parent — like, they'd move up one level toward the '/' in the pathname while remembering what the user typed 🧠✨, rather than doing the equivalent of:

chdir("..");

And in a shell like that, these two commands would not necessarily produce equivalent output for all directories:

cd .. && ls      ls ..

😭 the audacity

---

So here's where we landed: this behavior is now the default. ✨ But it's not consistent with the definition of dot-dot in most historical practice — meaning, yeah, this behavior was optionally available in the KornShell, but other shells historically just did not support this functionality at all. 💀

The logical pathname gets stored in the PWD environment variable when the cd utility completes, and that value is what's used to construct the next directory name whenever cd is invoked with the -L option. That's the whole loop, bestie. Slay 💅

---

🔮 FUTURE DIRECTIONS 🔮

None.

yeah. nothing. that's it. the future is a void, and it is peaceful 🦋

---

👀 SEE ALSO 👀

• Section 2.12, Shell Execution Environment, pwd
• The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines
• The System Interfaces volume of POSIX.1‐2017, chdir()

go read those if you want the full lore, bestie, I'm just the vibes-forward summary 📚✨

---

©️ COPYRIGHT ©️

ok so this part is the legal bit and I'm gonna hand it to you straight, no filter, because lawyers do not play 🫶

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

and then, the real relatable bit 💀

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

like, if something looks cursed in here, it's probably a conversion oopsie, not a Standard oopsie. report it, don't @ me 🙈

---

and that's the whole page, bestie!! 🎀 this one came to you from IEEE/The Open Group, dated 2017, and it lives in the manual as CD(1POSIX) — main character title, honestly 👑 now go cd somewhere cute 💖