The man Command Lies (Sometimes)
There are man pages with typographical errors, but that is not the issue of this post. Assuming you are using ksh or bash, how do you answer these questions:
- Is the man page for awk correct?
- Is the man page for pwd correct?
If you answered yes to both questions, you are wrong, but for different reasons.
I am not talking about awk, gawk, versus nawk. On Linux systems, awk is a symbolic link to gawk, so the two are the same. This is about documentation. On Linux, you have both the man command and the info command. The info command is a GNU command that has its own document format, and its own documents. If the info command cannot find an info document, it looks for a man page.
This is important to gawk, as the info docuement makes it clear that the official documentation for gawk is the info document and not the man page. While the man page contains a lot of usefule informaiton, it is not the complete reference. Only the info command provides the complete and authoritative reference. If you are looking for documentation on a command, start with the info command, and not the man command.
The pwd question involves a totally different issue. It involves the difference between the actual command and the built-in version of the command. There is an actual command called /bin/pwd, and the man pwd provides the correct documentation for this command. The caveat is that you don’t execute /bin/pwd, because it is also a built-in command to the shell. To find the documentation for built-in commands, you need to use man builtin or man builtins provides the documentation for bash built-in commands. For KornShell, you need to use man ksh. To show you the difference, execute the following commands:
cd /usr/tmp
pwd -P
pwd -L
/bin/pwd -P
/bin/pwd -L
The first two work, and the last two fail. The first two match the documentation for the built-in command, and the last two match the documentation for the /bin/pwd command.
So what commands are shell built–in commands, and which are not? With bash, you need to use man builtins to find the list, as the which command only tells you about /bin/pwd. For ksh, the answer is different. You can use the builtin command to provide a list of built-in commands. Of course, the builtin command is a built-in command. You can also use whence -a pwd, and you get a list of the alternatives. Now, if bash would just clone the whence command, I would be happy. Anything is better than which, which is a command, and not a built-in. whence is a built-in but not a command. Because of the limitation of which, users of the which command often create the alias described in the which man page. On many UNIX systems, which is an alias to whence -a, since ksh is the default shell, and only Bourne Shell users just don’t remember whence is the which on steroids.
