I am using debian8 (jessie) and I went to find read the manpage for open. instead I got a warning:
$ man 3 open
No manual entry for open in section 3
See 'man 7 undocumented' for help when manual pages are not available.
I have the manpage-dev package installed,so where is the programmers manpage (man 3) for open?
You want man 2 open for the C library interface, not man 3 open.
It is indeed in manpages-dev (not manpage-dev). man 3 open gives a Perl manual page.
# Show the corresponding source groff file
man -w 2 open
/usr/share/man/man2/open.2.gz
# Show which package this file belongs to
dpkg -S /usr/share/man/man2/open.2.gz
manpages-dev: /usr/share/man/man2/open.2.gz
# Or use dlocate to show which package this file belongs to
dlocate /usr/share/man/man2/open.2.gz
manpages-dev: /usr/share/man/man2/open.2.gz
The manpage sections are described in the manpages themselves. Enter man man in a shell session to see the various sections and general content:
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]
Section 2 describes system calls where section 3 covers library routines. Library routines that are simply wrappers for system calls are described in section 2 as well.
Just to clarify the reason for this further, the manpage is in section 2 because it is a system call (implemented more or less directly as part of the kernel, rather than the C library).
This distinction can seem somewhat arbitrary, especially with older system calls that are now library functions (fork is still in section 2 even though it is now a wrapper for clone), unless you already know it. In general, look in section 3 first, then try section 2 if you can't find it or it looks like it might not be relevant. Also, some of the functions in section 2 are internal or obsolete linux-specific functions that are not supposed to be called by normal programs (e.g. getdents, gettid).
You can also install the manpages-posix-dev package to get a set of manpages that is written from a portable perspective rather than containing linux-specific information. In this package, all of the manpages provided for C functions are in section 3p.
When I am unsure in what section a certain manpage is, I use the -a option.
-a, --all
By default, man will exit after displaying the most suitable manual page it finds.
Using this option forces man to display all the manual pages with names that match the
search criteria.
From the example in the manpage for man:
man -a intro
Display, in succession, all of the available intro manual pages
contained within the manual. It is possible to quit between
successive displays or skip any of them.
In this situation, is useful to see the entire list of all available pages with this manpage name by using one of the commands:
$ man -k ^open$
$ apropos -r ^open$
$ man -f open
$ whatis open
The result will be the same:
open (1) - start a program on a new virtual terminal (VT).
open (2) - open and possibly create a file or device
Or view the content of all existing manpages and thus identify required:
$ man -a open
apropos, orman --names-onlywith one of--regexor--wildcard. Seeman man.openisn't a function, it's a system call. That's a pedantic difference, but the relevance here is that system calls are in section 2, while library functions are in section 3.