Take the 2-minute tour ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.

help displays information about builtin commands. What is the source of help? Does it maintain a database for builtin commands, or does it read some files of each builtin commands (similar to the manpage of each utilities)?

Sometimes I find its information seems to expand that by --help

$ cd --help
bash: cd: --: invalid option
cd: usage: cd [-L|[-P [-e]]] [dir]

$ 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.

I thought help extract the help part of the executable, but for a python script pdf-merge.py, it isn't

$ help ./pdf-merge.py
bash: help: no help topics match `./pdf-merge.py'.  Try `help help' or `man -k ./pdf-merge.py' or `info ./pdf-merge.py'.

$ ./pdf-merge.py --help
usage: pdf-merge.py [-h] [-v] [--ask] [--output OUTPUT] [--title TITLE]
                    [--author AUTHOR] [--keyword KEYWORD] [--pdftk PDFTK]
                    [--gs GS] [--pdfmarks PDFMARKS] [--unicode]
                    PDF [PDF ...]

Merge PDFs preserving bookmarks. Thanks to Larry Cai for suggesting that
Unicode be supported and for discussion about the `--pdfmarks` option.

positional arguments:
  PDF                  an input PDF to merge

optional arguments:
  -h, --help           show this help message and exit
  -v, --version        show program's version number and exit
  --ask                pause for manual pdfmark tweaking
  --output OUTPUT      name of the output PDF
  --title TITLE        title of output PDF
  --author AUTHOR      author of output PDF
  --keyword KEYWORD    keywords for the output PDF
  --pdftk PDFTK        path to the pdftk executable
  --gs GS              path to the gs (Ghostscript) executable
  --pdfmarks PDFMARKS  path to pdfmarks file. If not given, a temporary file
                       is used. If given and the file is missing, execution
                       will stop after the file is created (before the
                       Ghostscript run). If given and the file exists, no
                       attempt will be make to use pdftk to generate the mark
                       file (I assume your input file is what you want).
  --unicode            instead of merging PDFs, convert PDF-formatted unicode
                       strings. For example `--unicode '<FEFF03B103B203B3>'
                       \u03b1\u03b2\u03b3`
share|improve this question
3  
Just to clarify, cd doesn't have a --help option. What you're seeing is the basic usage message you get when attempting to use an invalid option flag. –  terdon Jul 11 at 13:59
    
See also the man command, and in systems which support it the info command. –  keshlam Jul 11 at 22:03

4 Answers 4

up vote 19 down vote accepted

help is a bash builtin and it provides you only with the details of other bash builtins from buildtime.

The source for help is generated at compile time from the def files in the builtin directories of the bash source tree. If you look at the source code of help and cd you will notice that the information is part of $SHORT_DOC. help uses an array called shell_builtins to access the information.

share|improve this answer
1  
Further evidence: strings /bin/bash | grep 'Change the current directory to DIR' –  200_success Jul 12 at 0:49

Sometimes I find its information seems to expand that by --help

help cd and cd --help are fundamentally different. help is a command built into the shell, and it provides information about other commands that are built into the shell, meaning, they are not executables of their own, they are features of, e.g., bash. This can get a little confusing since some built-in commands also have standalone executable versions. In this case, they usually have their own manual page, and will expose an executable path if you ask which [command]. The information in the man page, or from [command] --help is for the executable; the info from help [command] is for the built-in, but hopefully they are more or less the same. If you look for a man page for a command that is only a built-in, you will probably get a page for the shell listing all of it's built-in commands.

--help (including the short form -h) is just a conventional label for a command line option to an executable. Many, but not all, CLI tools implement this, but they are not bound to and the information provided depends completely on the implementation. If you invoke --help on a shell built-in, you likely get "invalid option" and a brief "usage" message. If you invoke it on a standalone that doesn't implement it, you may also get an "invalid option", but exactly what happens again depends on the application.

If there are both built-in and standalone versions of a command available and you want to know which one is used when you invoke it, you can use type, another shell built-in.

> help type
type: type [-afptP] name [name ...]
Display information about command type.

For each NAME, indicate how it would be interpreted if used as a
command name.
[...]

> which echo
/bin/echo

> type echo
echo is a shell builtin

Here we can see that although there is a standalone executable echo, the echo your shell invokes is a built-in.

share|improve this answer

You already answered your own question:

nicolas@host:~$ help help
help: help [-s] [pattern ...]
    Display helpful information about builtin commands.  If PATTERN is
    specified, gives detailed help on all commands matching PATTERN,
    otherwise a list of the builtins is printed.  The -s option
    restricts the output for each builtin command matching PATTERN to
    a short usage synopsis.

Help is a BUILTIN command(means, bash internal command) to get information of other builtin commands. Since this third part script isn´t a builtin command of bash. If you run bash, call the builtin help an use strace you will get:

# strace bash -i -c "help cd"
---snip(long output)---
write(1, "cd: cd [-L|-P] [dir]\n"..., 21cd: cd [-L|-P] [dir]
) = 21
open("/usr/share/locale/locale.alias", O_RDONLY) = 3
fstat(3, {st_mode=S_IFREG|0644, st_size=2570, ...}) = 0
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7f38b765c000
read(3, "# Locale name alias data base.\n# "..., 4096) = 2570
read(3, ""..., 4096)                    = 0
close(3)                                = 0
munmap(0x7f38b765c000, 4096)            = 0
open("/usr/share/locale/pt_BR/LC_MESSAGES/bash.mo", O_RDONLY) = -1 ENOENT (No such file or directory)
open("/usr/share/locale/pt/LC_MESSAGES/bash.mo", O_RDONLY) = -1 ENOENT (No such file or directory)
open("/usr/share/locale/en/LC_MESSAGES/bash.mo", O_RDONLY) = -1 ENOENT (No such file or directory)
write(1, "    Change the current directory "..., 710    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 is the same as
    the current directory, i.e. `.'.  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, then try the word as a variable
    name.  If that variable has a value, then cd to the value of that
    variable.  The -P option says to use the physical directory structure
    instead of following symbolic links; the -L option forces symbolic links
) = 710
write(1, "    to be followed.\n"..., 20    to be followed.
) = 20
---snip(long output)---

Pretty much means that this information is generated at build time inside the bash binary.

share|improve this answer
    
They are not hard coded but are generated at build-time –  Ulrich Dangel Jul 11 at 13:55
    
thanks. (1) What do you mean by " call the builtin help an use strace"? (2) the information of usage is hard-coded in the executable of the built-in command cd? –  Tim Jul 11 at 13:55
    
@UlrichDangel - Thanks for the corretion. Hard-coded relates to something fixed on the source code, and not inside the binary during compilation time. My bad ;) @Tim. strace is a tool to see what a determined command is doing while in execution(libraries, system calls, files opened, etc). The method write shows that the help information comes from inside the binary(bash) while using the help builtin command, and not from opening a file(like a man page). –  nwildner Jul 11 at 14:04

I believe --help is part of the executable, it has to be implemented there. That's why you see different versions of --help, sometimes -h shorthand is allowed, others it's the non-prefixed "help"…

Edit

I misread part of your question. I'm unfamiliar with any of the inner workings of the "help" command itself.

share|improve this answer
    
How does the command help find the information of another command? –  Tim Jul 11 at 13:48

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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