man(1)
Shell command
Shows the manual page of a command or a C function. Sections 1, 2 and 3, man 3 printf, man -k to search, and how to read a page.
man [section] pageDescription
man displays the documentation installed on your machine, one page per command, system call or C library function. It is the fastest reference when you write C: the header to include, the exact prototype, the return value and the error cases are on the same page, offline.
The manual is split into numbered sections. Three of them get used every day:
| Section | Contents | Example |
|---|---|---|
| 1 | shell commands and programs | man 1 printf, the command |
| 2 | system calls, provided by the kernel | man 2 write |
| 3 | library functions, including the libc | man 3 printf, the C function |
That is why people write printf(3) or write(2): the number says which page you mean. Section 7, “miscellaneous”, holds overviews such as man 7 signal.
man -k word searches the names and short descriptions of every page, like the apropos command. It is the right reflex when you are looking for a function without knowing its name.
Reading a page
A page almost always follows the same outline. NAME gives the name and a one-line summary. LIBRARY tells you which library to link: -lc, the libc, is linked automatically, while the functions in <math.h> need -lm with glibc. SYNOPSIS gives the #include lines and the prototypes, to copy as they are. Then come DESCRIPTION, RETURN VALUE, ERRORS for the values of errno, and SEE ALSO for related pages.
The page opens in a pager, less by default: Space moves forward, b moves back, /word searches and n jumps to the next match, q quits.
Pitfalls
man printfopens the shell command, not the C function: without a number, section 1 is searched before section 3. Always give the section for a function.Several functions often share a page:
man 3 putcharshows theputs(3)page, which also coversfputc,putcandfputs.On Debian and Ubuntu, sections 2 and 3 come from the
manpages-devpackage. If it is missing,man 3 strlenfinds nothing:sudo apt install manpages-dev.On macOS, section 3 describes Apple's C library, not glibc. For Linux-specific behavior, the online version on man7.org is the reference.
Example
In the terminal of a Grademe exercise, which has the pages for sections 1, 2 and 3:
$ man printf | head -4PRINTF(1) User Commands PRINTF(1)
NAME printf - format and print data$ man 2 printfman: No entry for printf in section 2 of the manual.$ man 3 printf | head -5printf(3) Library Functions Manual printf(3)
NAME printf, fprintf, dprintf, vprintf, vfprintf, vdprintf, - formatted output conversion$ man -k "compare two strings"strcasecmp, strncasecmp(3) - compare two strings ignoring casestrcmp, strncmp(3) - compare two stringsstrcoll(3) - compare two strings using the current locale$ man 3 strlen | head -14strlen(3) Library Functions Manual strlen(3)
NAME strlen - calculate the length of a string
LIBRARY Standard C library (libc, -lc)
SYNOPSIS #include <string.h>
size_t strlen(const char *s);
DESCRIPTIONWithout a number, printf gives the page for the printf(1) command. printf is not a system call, hence the refusal in section 2. The man -k search finds strcmp without your having to know its name, and the top of strlen(3) is enough to write the call: #include <string.h>, a const char * in, a size_t out.