Finding the right man

syscalls and Library Functions

Technically speaking, a syscall is a low-level system service with an

ugly interface. Most programmers never use syscalls directly. Instead,

they use a C library function that wraps the actual syscall.

For example, the library function exit(), declared in stdlib.h, wraps

the _exit() syscall, but a significant difference exists between the

two. exit() ensures that open files are closed, streams are flushed, and

functions registered with atexit() are called before program

termination, but _exit() doesn't perform any of these operations. Yet

when Linux programmers use the term "syscall," they're often referring

to the C library wrapper function, not the actual syscall. In this

article, I will use the terms "library function" and "syscall" to

distinguish between the two.

man Pages

Library functions are declared in various header files. How can you tell

which header you should #include to use a certain library function? The

man command provides this information. Alas, syscalls are usually

documented in section 2, whereas library functions are in section 3. By

default, man displays the lower sections first; therefore, man will

often display the wrong function (i.e., the syscall rather than the

library function). You can explicitly indicate which section you wish to

view with the following command:

$man 3 funcname

In some cases, syscalls that use a minimal wrapper are NOT documented in

the C library section. Thus, the command above will not find a library

function funcname in these cases. To ensure that you get the

information you need, first type the man command without the section

number. If the documentation appears in section 2, then always check to

see if there is also documentation in section 3. Note that some

functions -- open(), for example -- are documented in section 1. In

these cases, look explicitly in sections 2 and 3 as well.

Setting man's Search Path

Many versions of the man program enable you to specify the search path

for man pages. Type the following command:

$man man

This will show you if your man version supports the MANSECT environment

variable and the -S command option. If it does, you can set MANSECT to

3:2:1:4:5:6:7:8:tcl:l:p:o to ensure that the documentation in section 3

is displayed first. To determine the current MANSECT configuration, look

at the /etc/man.config configuration file.

ITWorld DealPost: The best in tech deals and discounts.
Shop Tech Products at Amazon