Using man to read manual pages and using apropos to find man pages

man for reading man pages, some examples of how to use man, and how to read a man page
xman a GUI man page browser
apropos a utility for finding man pages

man

Unix manual pages about how to use different Unix commands, like 'ls', or "diff", or about how to use C library functions like "strcpy", are accessable through the Unix man command.

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

Section 1 is for commands that you can enter on the command line (like "ls").
Section 2 is for Unix system calls that you can call from your program code
Section 3 is for library functions that you can call from your program (like C library functions such as printf).

You can veiw the man page for man to see more information about man and man pages, including all the sections:

% man man

To view a manual page for a command or library function, just type man followed by the command:

% man toupper

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, I'd type:

% man 2 write

Some of the manual sections are:

 1 Commands: Those commands that are typed in at the Unix shell prompt.
 2 System calls:  Those functions which must be performed by the kernel.  
 3 Library calls: Library functions (ex. man pages for C library functions)
   (note: for languages other than C, man pages may or may not exist for their libraries)

The man page is opened in a program named less. You can quit by typing 'q', and move down a page by typing the space bar, or use the arrow keys. For more information on using less, read its man page.

To learn more about man, read its man page:

	% man man

It may not be completely obvious how to read a man page, so lets look at an example. The man page for toupper 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 behaviour
       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 con
       version 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), tells me that the man page for toupper is in section 3 of the manual.

The NAME, DESCRIPTION, and RETURN VALUE, parts give me short and long versions of what the function does, what its parameter values 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 tells me if I need to include any header files to use this and if I need to explicitly link in any libraries, and gives me the full function prototype:

SYNOPSIS
       #include < ctype.h >	

       int toupper (int c);

xman

You can also access man pages by running the manual browser xman:

% xman

And then choose "Manual Page" button and the "Sections" button from there to choose man pages from the different sections of the manual.

apropos

Sometimes you do not know the name of a function or command that you want to use. The utility apropos searchs the manual page descriptions for key words that you list and finds commands/functions that it thinks are appropriate matches. For example, if I want to find the name of a function for getting the current working directory, but I can't remember this function's name, I 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 I can read some of the man pages for the results to see which one of these I want.