I was trying to read the man page for fstat, and I got fstat(2), fstat(3) and fstat(3P).

Having in the past used a system (2) command, I know the difference is that I have to write a prototype myself to announce the function (which is reflected in the fstat(2) man page).

But never have I seen that a function is both a C function (3) and a system function (2) at the same time. What would be the benefit of using one over the other? How would C even differentiate whether I am using (2) or (3).

Also, I understand that sys/stat.h is platform specific, so which of (2) and (3) would be safer to use for cross-platform? Since I don't see a prototype line in the Windows page example, I assume it is a (3)

Please explain this to be because I cannot wrap my head around why both would exist.

CodePudding user response：

Web-based manpages are always a second-best option, since they can only show you a generic view of the interfaces. If you use the man command on your own system (at least for Unix-like systems), the result should reflect your actual installation, assuming you've correctly installed the documentation for your distribution.

Section 2 of the manual is intended for the description of system calls rather than standard library APIs. However, at least in the case of Linux documentation, section 2 is also used to describe the library wrappers around the system calls, which effectively documents the particular features implemented by the standard C library, normally glibc. In such cases, section 3P is used to document the to contain documentation extracted or adapted from the Posix standard. So if you want to write portable code, use only the features documented in section 3P. If you are happy to use all the extensions available to you on your system, use section 2.

man7.org and linux.die.net use different manpage repositories; on the latter, section 3P doesn't exist and the Posix programming manual is found in section 3. So https://www.man7.org/linux/man-pages/man3/fstat.3p.html and https://linux.die.net/man/3/fstat contain the same information. If you use a linux distribution, you'll probably find that man 3 fstat actually gives you the page from section 3p.

In any event, there is only one interface in the C library, which should conform to the Posix standard, but may extend it.

CodePudding user response：

The difference is that stat(2) is the system call, and stat(3) is the glibc stub function that applications are supposed to use to call it.

The syscalls(2) man page more or less sums this up:

System calls are generally not invoked directly, but rather via wrapper functions in glibc (or perhaps some other library). For details of direct invocation of a system call, see intro(2). Often, but not always, the name of the wrapper function is the same as the name of the system call that it invokes. For example, glibc contains a function chdir() which invokes the underlying "chdir" system call.

Often the glibc wrapper function is quite thin, doing little work other than copying arguments to the right registers before invoking the system call, and then setting errno appropriately after the system call has returned. (These are the same steps that are performed by syscall(2), which can be used to invoke system calls for which no wrapper function is provided.)