2

I'm looking at the -f flag on man which is described as:

   -f, --whatis
          Equivalent to whatis.  Display a short description from the manual page, if available.  See whatis(1) for details.

When I actually use -f entries always have a bracket at the end and sometimes you get multiple entries.

Examples of man -f results:

man -f grep:

grep (1)             - print lines matching a pattern

man -f man:

man (7)              - macros to format man pages
man (1)              - an interface to the on-line reference manuals

man -f git:

Git (3pm)            - Perl interface to the Git version control system
git (1)              - the stupid content tracker

I'm guessing all normal program descriptions are shown with (1).

Can anyone explain what other lists are being searched and how to identify what different numbers mean within the parenthesis?

Note: I also noticed that for git I can get the (3pm) manual page by doing man Git instead of man git. It seems counter-intuitive that man git would include the manual on git but not Git where as man -f git returns info on both.

Philip Kirkbride
  • 10,236
  • @steeldriver I still find it confusing. When I do man --whatis git I don't understand why I get back information on a Perl module relating to git. That information doesn't seem to be in the actual man file for git. Which led me the believe this information was possibly queried from multiple sources (?) – Philip Kirkbride Apr 17 '17 at 17:24
  • 1
    @PhilipKirkbride, you get information on a perl module relating to git because you have a man page for that module on your system. With man -f you are asking for information on any pages that are relevant to git, not just the manpage for the command line git itself. – user4556274 Apr 17 '17 at 17:30

4 Answers4

4

The thing in the parens (which on some systems may be a combination of letters and numbers, but most often is just a single digit) refers to a section in the manual. "The manual" is the combined volume of manuals available.

On my OpenBSD system, these sections are cited in the man(1) manual (also referred to as "the manual for the man command", which you can read with man man):

1         General commands (tools and utilities).
2         System calls and error numbers.
3         Library functions.
3p        perl(1) programmer's reference guide.
4         Device drivers.
5         File formats.
6         Games.
7         Miscellaneous information.
8         System maintenance and operation commands.
9         Kernel internals.

The section numbers are mostly the same across systems, but there may be minor deviations. The sections are not standardized, at least not by POSIX, so I think they are mostly traditional.

Sometimes, you will have to know what section you are looking for. Such is the case for the printf manual, for example. printf(1) refers to the printf utility of the shell, while printf(3) describes the C library routine printf(). If you type man printf, you will likely get printf(1). To get the manual for the C library function, use man 3 printf.

The sections seem to have been introduced with Third Edition UNIX coming out of Bell Labs in 1971 (the first UNIX written in C and not assembly language).

The manual of the Third Edition UNIX contained the following sections:

I.    Commands
II.   System calls
III.  Subroutines
IV.   Special files
V.    File formats
VI.   User-maintained programs
VII.  Miscellaneous
VIII. Maintenance
Kusalananda
  • 333,661
  • It's confusing because man git and man Git return two completely different results. Yet when I do man -f git, I get the description for both. – Philip Kirkbride Apr 17 '17 at 17:28
  • @PhilipKirkbride Yes, if you read those manual, you'll see that Git(3) is a Perl module manual, while git(1) is the manual for the git command that you use in the shell. – Kusalananda Apr 17 '17 at 17:31
2

extract from man man (5 paragraph):

   1   Executable programs or shell commands
   2   System calls (functions provided by the kernel)
   3   Library calls (functions within program libraries)
   4   Special files (usually found in /dev)
   5   File formats and conventions eg /etc/passwd
   6   Games
   7   Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
   8   System administration commands (usually only for root)
   9   Kernel routines [Non standard]
ctrl-alt-delor
  • 27,993
2

The numbers refer to which section of the manual the information is from (originally, which physical volume from the set of manuals you had on the shelf).

From man man:

   The table below shows the section numbers of the manual followed by the  types  of
   pages they contain.

   1   Executable programs or shell commands
   2   System calls (functions provided by the kernel)
   3   Library calls (functions within program libraries)
   4   Special files (usually found in /dev)
   5   File formats and conventions eg /etc/passwd
   6   Games
   7   Miscellaneous   (including  macro  packages  and  conventions),  e.g.  man(7),
       groff(7)
   8   System administration commands (usually only for root)
   9   Kernel routines [Non standard]

Some additional 'sections' were added later. For example, the (3pm) in your quoted text above refers to a perl module (or library).

user4556274
  • 8,995
  • 2
  • 33
  • 37
1

The number after the command tells you what section of the man pages the documentation for that command is in... for example, grep(1) means the man page for grep can be found in section 1 of the man pages.

Different flavors of UNIX and different distributions of Linux have different conventions as to which commands' documentation goes in which section.

ccs242
  • 159
  • 5