17.2. man and the Unix Manual

Unix manual pages provide documentation for Unix commands like ls, or rm, of system calls, and of library functions. You can read manual pages using the Unix man command. The apropos command can be used to search for Unix commands and library functions related to a topic supplied by a search pattern given as its command line argument. Many Unix and C library man pages are also available online, such as at kernel.org.

The Unix manual is divided into several sections. The first three are the most commonly used.

  1. Section 1 is for commands that you can enter on the command line (e.g., ls).

  2. Section 2 is for Unix system calls that you can call from program code (e.g., fork).

  3. Section 3 is for library functions that you can call from your program code (e.g., C library functions such as printf).

Run the man command to view the manual page with documentation about a command or function. The man page is opened in a program named less. You can quit less by typing q, move down a full a page by typing the space bar, or move up and down one line at a time using the arrow keys. You can also search for content using / syntax similar to Vim search.

To view the man page for the ls command, run:

$ man ls

Sometimes the same name is used for a command and a function. In this case you can get the correct man page by specifying the part of the manual in which it is contained. For example, to get the man page for the system call write, which appears in section 2 of the manual, type:

$ man 2 write

You can also read the manual page for man to learn more about it:

$ man man

17.2.1. Reading man pages

It may not be completely obvious how to read a man page, so lets look at an example of the toupper man page:

$ man toupper

The man page for the toupper library function look something like this:

TOUPPER(3)          Linux Programmer's Manual          TOUPPER(3)



NAME
       toupper, tolower - convert letter to upper or lower case

SYNOPSIS
       #include  <ctype.h>

       int toupper (int c);
       int tolower (int c);

DESCRIPTION
       toupper()  converts  the letter c to upper case, if possible.

       tolower() converts the letter c to lower case,  if  possible.

       If  c is not an unsigned char value, or EOF, the behavior
       of these functions is undefined.

RETURN VALUE
       The value returned is that of the converted letter,  or  c
       if the conversion was not possible.

CONFORMING TO
       ANSI C, BSD 4.3

BUGS
       The  details of what constitutes an uppercase or lowercase
       letter depend on the current  locale.   For  example,
       the default C locale does not know about umlauts, so
       no conversion is done for them.
       In some non-English locales, there are lowercase letters
       with  no  corresponding  uppercase  equivalent; the German
       sharp s is one example.

SEE ALSO
       isalpha(3), setlocale(3), locale(7)

GNU                   1993-04-04                 TOUPPER(3)

The first line, TOUPPER(3), says that the man page for toupper is in section 3 of the manual.

The NAME, DESCRIPTION, and RETURN VALUE, parts give short and long descriptions of what the function does, what its parameters are, and what it returns:

NAME
       toupper, tolower - convert letter to upper or lower case

DESCRIPTION
       toupper()  converts  the letter c to upper case, if possible.

RETURN VALUE
       The value returned is that of the converted letter,
       or  c if the conversion was not possible.

The SYNOPSIS part indicates if any header files need to be included to use this function, and if it is necessary to explicitly link in any libraries to compile an executable. It also lists the full function prototype:

SYNOPSIS
       #include < ctype.h >

       int toupper (int c);

The synopsis indicates that to call toupper a .c file must #include <ctype.h>, and that no library needs to be explicitly linked into a program that calls this function.

The SEE ALSO part lists other related functions. You can then run man on these to learn more about them (e.g., man isalpha).

SEE ALSO
       isalpha(3), setlocale(3), locale(7)

Man pages sometimes include examples of how to call the function.

17.2.2. apropos

Sometimes you do not know the name of a function or command that you want to use. The apropos command searches Unix manual page descriptions for key words that match the search pattern you list as a command line option and lists commands/functions that it thinks are appropriate matches. For example, if you want to find the name of a function for getting the current working directory, but you can’t remember the function’s name, you can ask apropos:

$ apropos "current working directory"
get_current_dir_name (3) - Get current working directory
getcwd (3)               - Get current working directory
getwd (3)                - Get current working directory

Then you can read some of the man pages for the results to see which one of these is the one you want:

$ man 3 getcwd

17.2.3. References

For more information see:

  • The man pages: man man, man apropos

  • kernel.org on-line version of Linux manual pages.