Options for searching the Unix man pages in Lion

There are several ways to look up command manual pages in the OS X Terminal.

If you are used to the Unix command line, then you will find yourself right at home with Apple's Terminal application in OS X. The tool launches bash as the default shell for user accounts, but you have the option of using others such as sh, zsh, and csh.

In addition to the shell environment, Apple offers a full set of BSD tools that enable you to script many tasks for automating just as you would on any Unix system.

The BSD library and other commands that Apple includes in its operating system are vast, and with hundreds of tools to choose from for anything from looking up hardware information to manipulating settings and files, it is nearly impossible to memorize what each is for. Additionally, some commands such as "whoami" are fairly basic, but others such as "rsync" or "ls" can have extensive options that add to the extreme memorization challenge.

Man pages in the Terminal
The man pages offer formatted instructions on how to use commands. In this case, typing 'man launchd' brought up the man page for the launchd command. Screenshot by Topher Kessler

Because of this, the Unix communities put together the "man pages," which are the instruction manuals for most of the commands in the system. When a developer creates a new command-line tool, he or she can provide information about it in a man page which you then access by typing "man <command>" at the command line. Even the most seasoned Terminal users access the Unix man pages, and, in fact, the more you use the Terminal the more you likely will access them.

With that said, one drawback of the man pages is they have historically been a bit cumbersome to access. In many cases the man pages are needed when you are halfway through assembling a command, which you'd have to delete to look up the page.

An alternative to using the same command line for man page lookup is of course to use another Terminal window or a Web search of "man <command>" so the window is next to your active one for easy reference. However, in OS X Lion Apple has a couple of other options for accessing the Unix man pages in the Terminal.

Command lookup window
By right-clicking highlighted words or by pressing the command lookup hot keys, you can invoke a separate window containing the man page of a typed command. Screenshot by Topher Kessler
  • Man page search
    If you are not sure what options are available to you for a command, you can use the tool "apropos" to search the man page database, but you can also access this quickly by pressing Control-Option-Command-forward slash after typing part or all of a command in the Terminal. For instance, typing "launchd" followed by pressing this key sequence will bring up a window that shows the results of typing "apropos launchd," which will show you about seven different commands that have "launchd" either in their names or descriptions.

  • Man page lookup
    Terminal has a command for looking up the actual man page for a command. After entering a full command name (Tab-completion will help do this), you can press Shift-Control-Command-question mark to bring up a separate window containing the man page for the command. If you do this for a partially typed command, you will get an error stating the command does not exist.

These hot-key sequences may be useful for some people, but they do have a couple of limitations. The first is that they only look up the last full word entered, which may be inconvenient if you have already typed some command options. For instance, if you are setting up a remote synchronization routine with rsync and wish to look up the man page, if you have already entered the command as "rsync -av --exclude" and then wish to look up how to use the "exclude" tag for the command, the system will perform the searches and man page lookups on the word "exclude" instead of the rsync command itself.

Command lookup mishaps
One problem with the command lookup hot keys is that they only work on the last word entered, which is not always the main command. Screenshot by Topher Kessler

This may be a problem, especially if, as in the rsync example above, you have assembled a complex command and wish to quickly look up more information about it. While in these instances you can easily either do a Web search or open a new Terminal window, Apple also makes these lookup options available in the mouse contextual menu, so if you highlight a word in the Terminal and right-click it, then you can select the options to open the man page for the word or search the man pages for the word.

These options for looking up commands in OS X are convenient; however, as with all man page lookups, there is the caveat that they only access the local man page database. Keep this in mind, because if you are logged in to a remote system that is older or has another operating system installed, then the command implementations on it may be different and it may have its own set of man pages. Therefore you would have to access the remote system's man pages by typing "man <command>" at the command line on that system, instead of relying on the Terminal's man page shortcuts.

Questions? Comments? Have a fix? Post them below or e-mail us!
Be sure to check us out on Twitter and the CNET Mac forums.

Featured Video