Re: The time(2) man page conflicts with glibc

[Zack Weinberg <zackw at panix dot com>]

On Wed, Dec 16, 2015 at 9:07 AM, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> Yes, but the raw system call can give us EFAULT. That needs to be
> documented.
>
> By the way, what's the reason that one can't tell if it returns
> an error when time() in libc.a is used?

time() in libc.a assumes that the syscall cannot fail, so it doesn't
set errno.  And -EFAULT = (time_t) -14 = 1969-12-31T23:59:46Z is
something that time() could return *without* its being an error.  It's
kind of the same problem as strtol() has, except I honestly don't see
any way libc.a could tell the difference.

Given what other people have said about not changing the kernel-level
behavior, here's a new suggestion for the manpages:

RETURN VALUE

    Time in seconds since the Epoch.

ERRORS

    EFAULT `t` is non-NULL and points outside your accessible
    address space (but see BUGS).

    On systems where the C library time() wrapper  function invokes
    an implementation provided by the vdso(7) (so that there is no
    trap into the kernel), an invalid address may instead trigger a
    SIGSEGV signal.  Note that whether vdso(7) is used may depend
    on whether a program is statically or dynamically linked.

BUGS

    Error returns from this system call are indistinguishable from
    successful reports that the time is a few seconds _before_ the
    Epoch, so the C library never sets `errno` as a result of this call.

   The `t` argument is obsolescent and should always be NULL in
   new code.  When `t` is NULL, the call cannot fail.