RTFM

by Quintessence

I don't know about you, but sometimes I neglect to just read the manual of things. Sometimes, I just get lost in a sea of what manual entries to read. So here's a quick primer to help us all man up.

Counting men

It might surprise you to know, but man CMD is not the only man entry there is. Let's say you are writing a C program and you want to learn more information about printf. If you were to just enter man printf (try it) you would see the manual entry for the printf command, not the function in the C library. In order to see the printf C Library entry you would need to use man 3 printf, since man 3 is what is used for the C library.

How many are there? There are actually eight sections in total:

  1. User Commands
  2. System Calls
  3. C Library Functions
  4. Devices and Special Files
  5. File Formats and Conventions
  6. Games et al
  7. Misc.
  8. System Administration tools and Daemons

Here you can see that man 3 is needed for C Library functions. If you want to check how current the information is on a man page, you can just scroll to the bottom where the date and other relevant information is located. Helpful tidbit: man uses your default pager, so it will have similar / the same key bindings as vim. This means you can hop to the bottom of a man page with shift+G.

Going on a Quest

A helpful flag for looking up what entries a string of text has is -k. If you man man you can see that -k is "Equivalent to apropos.", which means that it's used to search the man pages. (You can verify this with man apropos 😂)

If you know some basic regex it can come in handy with your searches. Using a quick example (trimmed for length):

$  man -k printf
Tcl_NewStringObj(3tcl), Tcl_NewUnicodeObj(3tcl), Tcl_SetStringObj(3tcl), Tcl_SetUnicodeObj(3tcl), Tcl_GetStringFromObj(3tcl), Tcl_GetString(3tcl), Tcl_GetUnicodeFromObj(3tcl), Tcl_GetUnicode(3tcl), Tcl_GetUniChar(3tcl), Tcl_GetCharLength(3tcl), Tcl_GetRange(3tcl), Tcl_AppendToObj(3tcl), Tcl_AppendUnicodeToObj(3tcl), Tcl_AppendObjToObj(3tcl), Tcl_AppendStringsToObj(3tcl), Tcl_AppendStringsToObjVA(3tcl), Tcl_AppendLimitedToObj(3tcl), Tcl_Format(3tcl), Tcl_AppendFormatToObj(3tcl), Tcl_ObjPrintf(3tcl), Tcl_AppendPrintfToObj(3tcl), Tcl_SetObjLength(3tcl), Tcl_AttemptSetObjLength(3tcl), Tcl_ConcatObj(3tcl) - manipulate Tcl objects as strings
(( snip ))
curl_maprintf(3), curl_mfprintf(3), curl_mprintf(3), curl_msnprintf(3), curl_msprintf curl_mvaprintf(3), curl_mvfprintf(3), curl_mvprintf(3), curl_mvsnprintf(3), curl_mvsprintf(3) - formatted output conversion
fmtcheck(3)              - sanitizes user-supplied printf(3)-style format string
format(ntcl)             - Format a string in the style of sprintf
(( snip ))

Glancing through the output you'll see that this includes lines like curl_maprintf(3) just because printf is a substring - basically it gives you too much beyond what you want and stops being helpful. If you happen to know a little bit of regex, you can do this instead:

$  man -k '^printf'
printf(1)                - formatted output
printf(3), fprintf(3), sprintf(3), snprintf(3), asprintf(3), dprintf(3), vprintf(3), vfprintf(3), vsprintf(3), vsnprintf(3), vasprintf(3), vdprintf(3) - formatted output conversion

For those unfamiliar with regex, ^ is the anchor used for the beginning of a string. This means your search only returns lines in the man pages that start with printf, which reduces the results to something helpful and manageable. This is another way to scope through the sections if you don't want to memorize them: here you can see that printf(1) is a command and printf(3) is are the C library calls from the output.

If you're ever unsure which man entry you've pulled, maybe you walked away from your desk or any other number of reasons, just take a quick look at the top of the man page. For man printf:

PRINTF(1)                 BSD General Commands Manual                PRINTF(1)

NAME
     printf -- formatted output

man 3 printf:

PRINTF(3)                BSD Library Functions Manual                PRINTF(3)

NAME
     printf, fprintf, sprintf, snprintf, asprintf, dprintf, vprintf, vfprintf, vsprintf, vsnprintf, vasprintf, vdprintf
     -- formatted output conversion

The top line shows you which manual section is open, in this case (1) and subsequently (3) and it also tells you the title of that section,"Commands" and "Functions" respectively.

Of course if man -k isn't particularly fruitful for any number of reasons, you can always man ITEM, man 2 ITEM, etc. until you hit the correct section for the ITEM you're trying to look up.