Introduction to Unix
../_images/ksus4.jpg ../_images/UNIX_blocks4.jpeg

2.5. Using man

Linux for Programmers and Users, Section 3.6

man

Displays documentation of commands, configuration files, system calls and library functions.

SYNOPSIS

man [section] name

man -k topic

-k topic

Search the manual pages for documentation related to the specified topic.

Man pages are organized in a number of sections. Commands are found in Section 1. If no section is specified, the first section containing a page for the specified name is displayed. The typical contents of the manual page sections are as follows.

  1. User Commands
  2. Systems Calls
  3. Library Functions
  4. Special Files
  5. File Formats
  6. Games
  7. Miscellaneous
  8. System Administration commands
  9. Kernel interfaces

You may need to use section number when entry exists in multiple sections. For example, passwd is documented in section 1 and 5. The printf command is documented in sections 1, 1p, 3 and 3p.

Note

Manual page documentation is not available for most internal shell commands – try help cd.

Use man man first to know how man should be used.

Note

Even though man is mainly treated as a reference manual, you can use it as a guide for not-too-complex commands. Most commands occur in Section 1, so man command generally retrieves the correct man page for the command.

2.5.1. Understanding a man Page

The specification for the allowed usage of each command is documented in the command’s manual page according to the Backus–Naur Form (BNF). - See Understanding a man Page and Figure A-5, pg 598.

Sequence Meaning
[ strings ] Strings may appear zero or one times.
{ strings }* Strings may appear zero or more times.
{ strings }+ Strings may appear one or more times.
string1|string2 string1 or string2 may appear.
-optionlist Zero or more single letter options may follow a dash.

See also

Structure of a Command for details on types of command arguments.

Example: wc [ -c | -m | -C ] [ -lw ] [ file ... ]

  • Most useful information is available in SYNOPSIS and DESCRIPTION.
  • When options are grouped in [ ] without a |, one or more of them can be used. (-l, -w and -lw are valid.)
  • The | signifies an OR condition. (Only one of -c, -m or -C can be used.)
  • The … means that multiple occurrences of the preceding item are possible. (wc can be used with multiple files.)
  • EXIT STATUS indicates values returned on error.

Note

The man documentation lists all options that can be used with a command. But must you use an option if it solves the problem? That depends on whether the application needs to be portable or not. Portability often means POSIX-compliance, so you may not use an option even if it solves the problem.

The exit status returned by a program has importance when you use the program in a shell script. Mention that it often makes sense to invoke a command B only after command A has completed execution in an expected manner. The shell scripting language can check the exit status to determine if a program behaved in the way it was meant to.