The time(2) man page conflicts with glibc

The time(2) man page conflicts with glibc

[H.J. Lu]

TIME(2)                    Linux Programmer's Manual                   TIME(2)

NAME
       time - get time in seconds

SYNOPSIS
       #include <time.h>

       time_t time(time_t *t);

DESCRIPTION
       time()  returns  the  time  as  the  number of seconds since the Epoch,
       1970-01-01 00:00:00 +0000 (UTC).

       If t is non-NULL, the return value is also stored in the memory pointed
       to by t.

RETURN VALUE
       On  success,  the value of time in seconds since the Epoch is returned.
       On error, ((time_t) -1) is returned, and errno is set appropriately.

ERRORS
       EFAULT t points outside your accessible address space.

CONFORMING TO
       SVr4, 4.3BSD, C89, C99, POSIX.1-2001.  POSIX does not specify any error
       conditions.

But x86-64 glibc has

0000000000000000 <time>:
   0: b8 c9 00 00 00       mov    $0xc9,%eax
   5: 0f 05                 syscall
   7: c3                   retq

I didn't check what kernel returns when memory is invalid.


H.J.

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

[Zack Weinberg]

On Tue, Dec 15, 2015 at 8:58 AM, H.J. Lu <hjl.tools@gmail.com> wrote:
...
>        time_t time(time_t *t);
...
>        If t is non-NULL, the return value is also stored in the memory pointed
>        to by t.
...
>        On error, ((time_t) -1) is returned, and errno is set appropriately.
...
>        EFAULT t points outside your accessible address space.
...
>    0: b8 c9 00 00 00       mov    $0xc9,%eax
>    5: 0f 05                 syscall
>    7: c3                   retq
>
> I didn't check what kernel returns when memory is invalid.

I did.  The *actual system call* does indeed return -EFAULT when
memory is invalid, which will be observed as 0xfffffffffffffff2 in the
return value.  However, the *vDSO shortcut* (which does not trap into
the kernel) will just segfault the application.  This is an observable
ABI difference between statically and dynamically linked binaries.

Given the extreme obsolescence of the argument to `time`, I would
recommend that the *kernel* be changed to fire an actual SIGSEGV
instead of returning -EFAULT from the syscall version of `time`, and
then that can be the documented behavior, with the historic behavior
relegated to the BUGS section of the manpage.

(Is the vDSO mapped into processes with statically linked executable
images?  If so, we could also consider changing glibc to use it
always.)

Test program and results:

$ cat test.c
#include <time.h>
#include <stdio.h>
#include <errno.h>

int main(void)
{
  time_t a;
  time_t b;
  errno = 0;
  a = time(&b);
  printf("%016llx %016llx %d\n",
         (unsigned long long)a, (unsigned long long)b, errno);

  errno = 0;
  a = time(0);
  printf("%016llx %d\n", (unsigned long long)a, errno);

  errno = 0;
  a = time((time_t *)0x8000FFFF0000FFFF);
  printf("%016llx %d\n", (unsigned long long)a, errno);
  return 0;
}

$ gcc test.c && ./a.out
0000000056701f0d 0000000056701f0d 0
0000000056701f0d 0
Segmentation fault

$ gcc -static test.c && ./a.out
0000000056701f22 0000000056701f22 0
0000000056701f22 0
fffffffffffffff2 0

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

[Andreas Schwab]

Zack Weinberg <zackw-VmQCmMdMyN0AvxtiuMwx3w@public.gmane.org> writes:

> I did.  The *actual system call* does indeed return -EFAULT when
> memory is invalid, which will be observed as 0xfffffffffffffff2 in the
> return value.  However, the *vDSO shortcut* (which does not trap into
> the kernel) will just segfault the application.  This is an observable
> ABI difference between statically and dynamically linked binaries.

Undefined behaviour can change any time in any way and is not part of
the ABI.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab-l3A5Bk7waGM@public.gmane.org
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 437 bytes --]

On 15 Dec 2015 09:14, Zack Weinberg wrote:
> Given the extreme obsolescence of the argument to `time`, I would
> recommend that the *kernel* be changed to fire an actual SIGSEGV
> instead of returning -EFAULT from the syscall version of `time`, and
> then that can be the documented behavior, with the historic behavior
> relegated to the BUGS section of the manpage.

meh.  it would be out of character for the kernel to do this.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

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

[Zack Weinberg]

On Tue, Dec 15, 2015 at 9:55 AM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> On 15 Dec 2015 09:14, Zack Weinberg wrote:
>> Given the extreme obsolescence of the argument to `time`, I would
>> recommend that the *kernel* be changed to fire an actual SIGSEGV
>> instead of returning -EFAULT from the syscall version of `time`, and
>> then that can be the documented behavior, with the historic behavior
>> relegated to the BUGS section of the manpage.
>
> meh.  it would be out of character for the kernel to do this.

Why?
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 729 bytes --]

On 15 Dec 2015 10:19, Zack Weinberg wrote:
> On Tue, Dec 15, 2015 at 9:55 AM, Mike Frysinger wrote:
> > On 15 Dec 2015 09:14, Zack Weinberg wrote:
> >> Given the extreme obsolescence of the argument to `time`, I would
> >> recommend that the *kernel* be changed to fire an actual SIGSEGV
> >> instead of returning -EFAULT from the syscall version of `time`, and
> >> then that can be the documented behavior, with the historic behavior
> >> relegated to the BUGS section of the manpage.
> >
> > meh.  it would be out of character for the kernel to do this.
> 
> Why?

because it returns EFAULT for other syscalls when you pass bad pointers.
projects like LTP utilize that to verify edge case functionality.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

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

[Rich Felker]

On Tue, Dec 15, 2015 at 01:38:26PM -0500, Mike Frysinger wrote:
> On 15 Dec 2015 10:19, Zack Weinberg wrote:
> > On Tue, Dec 15, 2015 at 9:55 AM, Mike Frysinger wrote:
> > > On 15 Dec 2015 09:14, Zack Weinberg wrote:
> > >> Given the extreme obsolescence of the argument to `time`, I would
> > >> recommend that the *kernel* be changed to fire an actual SIGSEGV
> > >> instead of returning -EFAULT from the syscall version of `time`, and
> > >> then that can be the documented behavior, with the historic behavior
> > >> relegated to the BUGS section of the manpage.
> > >
> > > meh.  it would be out of character for the kernel to do this.
> > 
> > Why?
> 
> because it returns EFAULT for other syscalls when you pass bad pointers.
> projects like LTP utilize that to verify edge case functionality.

Programs could also be calling the syscall directly (using syscall()
or asm) and using it as a (very cheap, fail-safe) way to verify that
an address is writable before attempting to write to it. Breaking this
would be a kernel API regression. However the library function time()
has UB for invalid pointers and no obligation to support them.

Rich

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

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1372 bytes --]

On 16 Dec 2015 02:08, Rich Felker wrote:
> On Tue, Dec 15, 2015 at 01:38:26PM -0500, Mike Frysinger wrote:
> > On 15 Dec 2015 10:19, Zack Weinberg wrote:
> > > On Tue, Dec 15, 2015 at 9:55 AM, Mike Frysinger wrote:
> > > > On 15 Dec 2015 09:14, Zack Weinberg wrote:
> > > >> Given the extreme obsolescence of the argument to `time`, I would
> > > >> recommend that the *kernel* be changed to fire an actual SIGSEGV
> > > >> instead of returning -EFAULT from the syscall version of `time`, and
> > > >> then that can be the documented behavior, with the historic behavior
> > > >> relegated to the BUGS section of the manpage.
> > > >
> > > > meh.  it would be out of character for the kernel to do this.
> > > 
> > > Why?
> > 
> > because it returns EFAULT for other syscalls when you pass bad pointers.
> > projects like LTP utilize that to verify edge case functionality.
> 
> Programs could also be calling the syscall directly (using syscall()
> or asm) and using it as a (very cheap, fail-safe) way to verify that
> an address is writable before attempting to write to it. Breaking this
> would be a kernel API regression. However the library function time()
> has UB for invalid pointers and no obligation to support them.

sure, but that still doesn't mean the kernel should be sending SEGV.
which is what this subthread was about.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

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

[Rich Felker]

On Wed, Dec 16, 2015 at 03:34:32PM -0500, Mike Frysinger wrote:
> On 16 Dec 2015 02:08, Rich Felker wrote:
> > On Tue, Dec 15, 2015 at 01:38:26PM -0500, Mike Frysinger wrote:
> > > On 15 Dec 2015 10:19, Zack Weinberg wrote:
> > > > On Tue, Dec 15, 2015 at 9:55 AM, Mike Frysinger wrote:
> > > > > On 15 Dec 2015 09:14, Zack Weinberg wrote:
> > > > >> Given the extreme obsolescence of the argument to `time`, I would
> > > > >> recommend that the *kernel* be changed to fire an actual SIGSEGV
> > > > >> instead of returning -EFAULT from the syscall version of `time`, and
> > > > >> then that can be the documented behavior, with the historic behavior
> > > > >> relegated to the BUGS section of the manpage.
> > > > >
> > > > > meh.  it would be out of character for the kernel to do this.
> > > > 
> > > > Why?
> > > 
> > > because it returns EFAULT for other syscalls when you pass bad pointers.
> > > projects like LTP utilize that to verify edge case functionality.
> > 
> > Programs could also be calling the syscall directly (using syscall()
> > or asm) and using it as a (very cheap, fail-safe) way to verify that
> > an address is writable before attempting to write to it. Breaking this
> > would be a kernel API regression. However the library function time()
> > has UB for invalid pointers and no obligation to support them.
> 
> sure, but that still doesn't mean the kernel should be sending SEGV.
> which is what this subthread was about.

The kernel is not causing SIGSEGV as far as I can tell; it's purely
the library function time that's causing this.

Rich
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Zack Weinberg]

On Wed, Dec 16, 2015 at 4:59 PM, Rich Felker <dalias-8zAoT0mYgF4@public.gmane.org> wrote:
>> > Programs could also be calling the syscall directly (using syscall()
>> > or asm) and using it as a (very cheap, fail-safe) way to verify that
>> > an address is writable before attempting to write to it. Breaking this
>> > would be a kernel API regression. However the library function time()
>> > has UB for invalid pointers and no obligation to support them.
>>
>> sure, but that still doesn't mean the kernel should be sending SEGV.
>> which is what this subthread was about.
>
> The kernel is not causing SIGSEGV as far as I can tell; it's purely
> the library function time that's causing this.

... Do you consider the vDSO to be part of the kernel, or part of the C library?
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Rich Felker]

On Wed, Dec 16, 2015 at 05:27:03PM -0500, Zack Weinberg wrote:
> On Wed, Dec 16, 2015 at 4:59 PM, Rich Felker <dalias@libc.org> wrote:
> >> > Programs could also be calling the syscall directly (using syscall()
> >> > or asm) and using it as a (very cheap, fail-safe) way to verify that
> >> > an address is writable before attempting to write to it. Breaking this
> >> > would be a kernel API regression. However the library function time()
> >> > has UB for invalid pointers and no obligation to support them.
> >>
> >> sure, but that still doesn't mean the kernel should be sending SEGV.
> >> which is what this subthread was about.
> >
> > The kernel is not causing SIGSEGV as far as I can tell; it's purely
> > the library function time that's causing this.
> 
> .... Do you consider the vDSO to be part of the kernel, or part of the C library?

The vdso is library code provided by the kernel, but there's no
fundamental reason to expect it to behave identically to the system
call. Applications making the system call themselves directly will
never end up calling the vdso code, so it doesn't matter if its
behavior in corner cases like this is the same as the syscall.

Said differently, the vdso function is a _new_ stable kernel API
that's functionally similar to the syscall, not the same API, since
you call it in a very different way.

Rich

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

[Zack Weinberg]

On Wed, Dec 16, 2015 at 5:44 PM, Rich Felker <dalias-8zAoT0mYgF4@public.gmane.org> wrote:
> On Wed, Dec 16, 2015 at 05:27:03PM -0500, Zack Weinberg wrote:
>> > The kernel is not causing SIGSEGV as far as I can tell; it's purely
>> > the library function time that's causing this.
>>
>> .... Do you consider the vDSO to be part of the kernel, or part of the C library?
>
> The vdso is library code provided by the kernel, but there's no
> fundamental reason to expect it to behave identically to the system
> call. Applications making the system call themselves directly will
> never end up calling the vdso code, so it doesn't matter if its
> behavior in corner cases like this is the same as the syscall.

OK.  I'm just asking because the segfault happens inside the vDSO, or
anyway that's what it looks like from the debugger.

(I don't have a problem with keeping everything the way it is
behavior-wise, for the record.)

zw
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1826 bytes --]

On 16 Dec 2015 16:59, Rich Felker wrote:
> On Wed, Dec 16, 2015 at 03:34:32PM -0500, Mike Frysinger wrote:
> > On 16 Dec 2015 02:08, Rich Felker wrote:
> > > On Tue, Dec 15, 2015 at 01:38:26PM -0500, Mike Frysinger wrote:
> > > > On 15 Dec 2015 10:19, Zack Weinberg wrote:
> > > > > On Tue, Dec 15, 2015 at 9:55 AM, Mike Frysinger wrote:
> > > > > > On 15 Dec 2015 09:14, Zack Weinberg wrote:
> > > > > >> Given the extreme obsolescence of the argument to `time`, I would
> > > > > >> recommend that the *kernel* be changed to fire an actual SIGSEGV
> > > > > >> instead of returning -EFAULT from the syscall version of `time`, and
> > > > > >> then that can be the documented behavior, with the historic behavior
> > > > > >> relegated to the BUGS section of the manpage.
> > > > > >
> > > > > > meh.  it would be out of character for the kernel to do this.
> > > > > 
> > > > > Why?
> > > > 
> > > > because it returns EFAULT for other syscalls when you pass bad pointers.
> > > > projects like LTP utilize that to verify edge case functionality.
> > > 
> > > Programs could also be calling the syscall directly (using syscall()
> > > or asm) and using it as a (very cheap, fail-safe) way to verify that
> > > an address is writable before attempting to write to it. Breaking this
> > > would be a kernel API regression. However the library function time()
> > > has UB for invalid pointers and no obligation to support them.
> > 
> > sure, but that still doesn't mean the kernel should be sending SEGV.
> > which is what this subthread was about.
> 
> The kernel is not causing SIGSEGV as far as I can tell; it's purely
> the library function time that's causing this.

i'm fully aware of that.  please see the context in this subthread.
i've already trimmed all unrelated content.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

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

[Andreas Schwab]

In which way does it conflict?

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab-l3A5Bk7waGM@public.gmane.org
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[H.J. Lu]

On Tue, Dec 15, 2015 at 6:16 AM, Andreas Schwab <schwab-l3A5Bk7waGM@public.gmane.org> wrote:
> In which way does it conflict?

On error, ((time_t) -1) is returned, and errno is set appropriately.


-- 
H.J.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Michael Kerrisk (man-pages)]

On 12/15/2015 03:17 PM, H.J. Lu wrote:
> On Tue, Dec 15, 2015 at 6:16 AM, Andreas Schwab <schwab@suse.de> wrote:
>> In which way does it conflict?
> 
> On error, ((time_t) -1) is returned, and errno is set appropriately.


So, how would the following text be for the man page?

    ERRORS
       EFAULT t  points  outside your accessible address space.  On sys‐
              tems 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.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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

[H.J. Lu]

On Wed, Dec 16, 2015 at 5:38 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On 12/15/2015 03:17 PM, H.J. Lu wrote:
>> On Tue, Dec 15, 2015 at 6:16 AM, Andreas Schwab <schwab-l3A5Bk7waGM@public.gmane.org> wrote:
>>> In which way does it conflict?
>>
>> On error, ((time_t) -1) is returned, and errno is set appropriately.
>
>
> So, how would the following text be for the man page?
>
>     ERRORS
>        EFAULT t  points  outside your accessible address space.  On sys‐
>               tems 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.
>

time never sets errno.  You can't tell if it returns error when time
in libc.a is used.

-- 
H.J.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Michael Kerrisk (man-pages)]

On 12/16/2015 02:53 PM, H.J. Lu wrote:
> On Wed, Dec 16, 2015 at 5:38 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> On 12/15/2015 03:17 PM, H.J. Lu wrote:
>>> On Tue, Dec 15, 2015 at 6:16 AM, Andreas Schwab <schwab-l3A5Bk7waGM@public.gmane.org> wrote:
>>>> In which way does it conflict?
>>>
>>> On error, ((time_t) -1) is returned, and errno is set appropriately.
>>
>>
>> So, how would the following text be for the man page?
>>
>>     ERRORS
>>        EFAULT t  points  outside your accessible address space.  On sys‐
>>               tems 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.
>>
> 
> time never sets errno.  You can't tell if it returns error when time
> in libc.a is used.

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?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Zack Weinberg]

On Wed, Dec 16, 2015 at 9:07 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Michael Kerrisk (man-pages)]

Hello Zack,

On 12/16/2015 03:50 PM, Zack Weinberg wrote:
> On Wed, Dec 16, 2015 at 9:07 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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.

Nice! I've added that new text.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Paul Eggert]

Zack Weinberg wrote:
> When `t` is NULL, the call cannot fail.

This doesn't make it clear what happens when the time_t values roll around after 
the year 2038, on 32-bit time_t hosts. How about adding some further text along 
the following lines?

In GNU/Linux time(NULL) cannot fail with errno == EOVERFLOW, even on ABIs where 
time_t is a signed 32-bit integer and when the clock ticks past the time 2**31 
(2038-01-19 03:14:08 UTC, ignoring leap seconds). Instead, the behavior is 
undefined when the system time is out of time_t range. Applications intended to 
run after 2038 should use ABIs with time_t wider than 32 bits.

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

[Michael Kerrisk (man-pages)]

Hello Paul,

On 12/17/2015 12:05 AM, Paul Eggert wrote:
> Zack Weinberg wrote:
>> When `t` is NULL, the call cannot fail.
> 
> This doesn't make it clear what happens when the time_t values roll around after 
> the year 2038, on 32-bit time_t hosts. How about adding some further text along 
> the following lines?
> 
> In GNU/Linux time(NULL) cannot fail with errno == EOVERFLOW, even on ABIs where 
> time_t is a signed 32-bit integer and when the clock ticks past the time 2**31 
> (2038-01-19 03:14:08 UTC, ignoring leap seconds). Instead, the behavior is 
> undefined when the system time is out of time_t range. Applications intended to 
> run after 2038 should use ABIs with time_t wider than 32 bits.
> .

Seems reasonable. I've added something close that. Thanks!

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html