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?

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.

| improve this answer | |
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.

| improve this answer | |
  • 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 4: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 that just calls execve without a customizable env parameter, and its man page is in section 3. – theferrit32 Mar 22 '18 at 18:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.