2

When I type man regex into a shell, this loads

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

NAME
       regcomp, regexec, regerror, regfree - POSIX regex functions

SYNOPSIS
........

when I type man 7 regex I get a different man page

REGEX(7)                                                     Linux Programmer's Manual                                                     REGEX(7)

NAME
       regex - POSIX.2 regular expressions

DESCRIPTION
........

What is happening here?

the_velour_fog
  • 12,270

1 Answers1

4

You can find more about this from man man. The man pages are broken into different sections. This is so things are grouped with like things, and you can have the same name in different spots (like, say, stat which exists in several sections).

The sections, as defined in my old Fedora's man man are:

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 conven‐
       tions), e.g. man(7), groff(7)
8   System administration commands (usually only for root)
9   Kernel routines [Non standard]
Eric Renouf
  • 18,431
  • so both these documents are just sections in a larger man document? – the_velour_fog Sep 26 '15 at 23:37
  • They are documents for different things. The first one is in section 3, so it is documenting the regex.h library. The second, man 7 regex documents POSIX regular expressions, which are used by many shell commands – Eric Renouf Sep 26 '15 at 23:39
  • 1
    I see, so do the writers of the man page for a given program - set a "default" section number that will be loaded when someone simply enters man <program> ? – the_velour_fog Sep 26 '15 at 23:43
  • Yes, the section number is generally both included in the man page itself (e.g., the REGEX(3) and REGEX(7) titles in your examples), and that affects where it gets installed. For linux at least they typically they go in /usr/share/man/manX where that X is the section, so /usr/share/man/man3 and /usr/share/man/man7 for your two regex examples. – Eric Renouf Sep 26 '15 at 23:55
  • Also, my comment may have misinterpreted your comment question. In general man pages are searched in order, and if you just type man <program> the user will get the first section that has an document for <program>. The user can specify the section they would like to use with the number as in man 7 regex saying to look in section 7, otherwise they're search 1-9 in order and first one "wins". man -a <program> will show all sections that have entries for that document. Also useful is apropos <name> which will give a list of potentially relevent man pages – Eric Renouf Sep 26 '15 at 23:58
  • Also, also useful is whatis <name> which will list all the sections that have an entry for that name – Eric Renouf Sep 26 '15 at 23:59
  • thanks whatis <name> thats very helpful! So if I understand your answer correctly, if the man page is for a program - that doesnt obviously provide 2 System calls, 3 Library calls etc then a section 1 man page is the only appropriate section for that program? eg I just ran whatis for rsync, grep, sed, awk and they only have section one man pages – the_velour_fog Sep 27 '15 at 00:08
  • Right, executables would go in section 1,and if they don't have the same name as a library or function they won't show up anywhere else – Eric Renouf Sep 27 '15 at 00:13
  • thanks so much Eric!, all that confused and frustrated me for years - especially since the man pages are a gateway to understanding the unix eco system, thanks :D – the_velour_fog Sep 27 '15 at 00:16