|
Kansas State University at Salina Introduction to Unix |
|
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.
- User Commands
- Systems Calls
- Library Functions
- Special Files
- File Formats
- Games
- Miscellaneous
- System Administration commands
- 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.
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.
