5

I cringe to ask this question, but for many commands on OS-X and probably other POSIX systems, it's difficult for me to find needed documentation on the built-in commands.

For example, if I want to find out what the -P option of the cd command does, I would expect man cd to tell me, but alas it brings me to the dreaded "BSD General Commands" page.

Many of these commands (all?) don't support --help options, so the best I've been able to do is induce a terse usage message by giving in an invalid option. For example:

~ $ cd --tell-me-something-I-didnt-know-damn-you
-bash: cd: --: invalid option
cd: usage: cd [-L|-P] [dir]

I found the simple command section of the POSIX standard and that seems useful, but I have the feeling that I'm missing something fundamental. It shouldn't be that hard.

What is the correct way to get detailed usage information on built-in commands?

2
6

An easy way to get help on built in commands without wading through the shell's man page is help:

$ help cd
cd: cd [-L|[-P [-e]]] [dir]
Change the shell working directory.

Change the current directory to DIR.  The default DIR is the value of the
HOME shell variable.

The variable CDPATH defines the search path for the directory containing
DIR.  Alternative directory names in CDPATH are separated by a colon (:).
A null directory name is the same as the current directory.  If DIR begins
with a slash (/), then CDPATH is not used.

If the directory is not found, and the shell option `cdable_vars' is set,
the word is assumed to be  a variable name.  If that variable has a value,
its value is used for DIR.

Options:
    -L  force symbolic links to be followed
    -P  use the physical directory structure without following symbolic
    links
    -e  if the -P option is supplied, and the current working directory
    cannot be determined successfully, exit with a non-zero status

The default is to follow symbolic links, as if `-L' were specified.

Exit Status:
Returns 0 if the directory is changed, and if $PWD is set successfully when
-P is used; non-zero otherwise.
2
  • Yeah, for some reason this is not so well known, I only found out about it recently and have been using Linux for more than a decade.
    – terdon
    May 15 '13 at 11:03
  • That even works for busybox
    – wnrph
    May 16 '13 at 7:48
4

cd is a shell built-in, as you can see by typing type CMD:

$ type cd
cd is a shell builtin

Documentation on shell built-ins is in the shell man pages, sh(1), bash(1), and bash-builtins(1), under the heading Built-in Commands, Shell Builtin Commands, or Bash Builtin Commands; for example:

cd [-L | [-P [-e]]] [dir]

    Change the current directory to dir.  The variable HOME is the default dir.  The variable CDPATH defines the search path for the directory containing dir.  Alternative directory names in CDPATH are separated by a colon (:).  A null directory name in CDPATH is the same as the current directory, i.e., “.”.  If dir begins with a slash (/), then CDPATH is not used.  The -P option says to use the physical directory structure instead of following symbolic links (see also the -P option to the set builtin command); the -L option forces symbolic links to be followed.  If the -e option is supplied with -P, and the current working directory cannot be successfully determined after a successful directory change, cd will return an unsuccessful status.  An argument of - is equivalent to $OLDPWD.  If a non-empty directory name from CDPATH is used, or if - is the first argument, and the directory change is successful, the absolute pathname of the new working directory is written to the standard output.  The return value is true if the directory was successfully changed; false otherwise.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.