2

For an exercise at the university, we are asked to extend Minix (v2) with a system call utctime that properly calculates the leap seconds (which Minix' implementation of time does not do).

We've created a new system call, and created a new library function that wraps this system call that was added to <time.h>.

Now, we'd like to add a man-page for utctime. However, time has both a man-page in section 2 (system calls) as well as section 3 (library calls).

Should we add the utctime to both of these? Or only to 2 because it is not a standardized C library call?

Qqwy
  • 415
  • 4
  • 9

2 Answers2

2

I'd suggest section 2. Consider, for instance, the open system call — actually, the C library function wrapper over the open system call — which is documented only in section 2.

Andy Dalton
  • 13,654
  • 1
  • 25
  • 45
1

If the function lives in the kernel itself, not a userspace C library, then put it in section 2.

Section 3 is not only for libc functions, they can be other libraries which provide low-level operating system subroutines that are not part of the kernel. For example PAM function manual pages are stored in section 3.

In this case if you have a kernel system call and a library function, put the man page for the system call in section 2 and the man page for the library function in section 3.

theferrit32
  • 111
  • 3
  • So in this case the library function `time_t utctime(time_t *)` was added to `/usr/includes/time.h`, with its source defined in `/usr/src/lib/libc/sys-minix/utctime.c`. And it is a direct wrapper of the system call, only performing `_SYSCALL(PM_PROC_NR, UTCTUME, &m);` and returning the proper field of the message-object from the function (as well as, akin to `time`, setting the pointer passed as argument if not NULL to the same value). Would this be 'enough of a library function' to create a section-3 man page for besides the section-2 page or not? – Qqwy Mar 22 '18 at 04:21
  • 1
    Yes, if `utctime` is a modification to libc and lives in userspace (not compiled into the kernel) then it is a library function, even if it is a trivial wrapper of a kernel function. In most systems, library code when executed runs in an entirely different memory region with different privileges from the kernel code. Consider `execv` and `execve`. `execve` is a kernel function and in section 2. `execv` is a function in [libc](https://code.woboq.org/userspace/glibc/posix/execv.c.html) that just calls `execve` without a customizable env parameter, and its man page is in section 3. – theferrit32 Mar 22 '18 at 18:11