Re: Man page for revised timerfd API

[Geoff Clare <geoff@gclare.org.uk>]

Michael Kerrisk <mtk-manpages@gmx.net> wrote, on 26 Sep 2007:
>
> .TH TIMERFD_CREATE 2 2007-09-26 Linux "Linux Programmer's Manual"
> .SH NAME
> timerfd_create, timerfd_settime, timer_gettime \-

s/timer_/timerfd_/

> timers that notify via file descriptors
> .SH SYNOPSIS
> .\" FIXME . This header file may well change
> .\" FIXME . Probably _GNU_SOURCE will be required
> .\" FIXME . May require: Link with \fI\-lrt\f
> .nf
> .B #include <sys/timerfd.h>
> .sp
> .BI "int timerfd_create(int " clockid );
> .sp
> .BI "int timerfd_settime(int " fd ", int " flags ,
> .BI "                    const struct itimerspec *" new_value ,
> .BI "                    struct itimerspec *" curr_value );
> .sp
> .BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value );
> .fi
> .SH DESCRIPTION
> These system calls create and operate on a timer
> that delivers timer expiration notifications via a file descriptor.
> They provide an alternative to the use of
> .BR setitimer (2)
> or
> .BR timer_create (3),
> with the advantage that the file descriptor may be monitored by
> .BR poll (2)
> and
> .BR select (2).
> 
> The use of these three system calls is analogous to the use of
> .BR timer_create (2),
> .BR timer_settime (2),
> and
> .BR timer_gettime (2).

It might be worth mentioning here that there is no timerfd function
analogous to timer_getoverrun() because the equivalent information
is available when the file descriptor is read.

[...]
> .SS Operating on a timer file descriptor
> The file descriptor returned by
> .BR timerfd_create (2)
> supports the following operations:
> .TP
> .BR read (2)
> If the timer has already expired one or more times since it was created,
> or since the last
> .BR read (2),

Nit-pick: this should say "last successful read(2)".  Presumably a
read() that failed with EINVAL would not reset the count.

> then the buffer given to
> .BR read (2)
> returns an unsigned 8-byte integer
> .RI ( uint64_t )
> containing the number of expirations that have occurred.
> .IP
> If no timer expirations have occurred at the time of the
> .BR read (2),
> then the call either blocks until the next timer expiration,
> or fails with the error
> .B EAGAIN
> if the file descriptor has been made non-blocking
> (via the use of the
> .BR fcntl (2)
> .B F_SETFL
> operation to set the
> .B O_NONBLOCK
> flag).
> .IP
> A
> .BR read (2)
> will fail with the error
> .B EINVAL
> if the size of the supplied buffer is less than 8 bytes.

You should also add this error to your read(2) man page.

[...]
> .SH "RETURN VALUE"
> On success,
> .BR timerfd_create ()
> returns a new file descriptor.
> On error, \-1 is returned and
> .I errno
> is set to indicate the error.
> 
> .BR timer_settime ()
> and
> .BR timer_gettime ()
> return 0 on success;

s/timer_/timerfd_/ on the two .BR lines above.

> on error they return \-1, and set
> .I errno
> to indicate the error.
> .SH ERRORS
> .\" FIXME -- there need to be errors for all syscalls here
> .BR tinerfd_create ()

s/tiner/timer/

> can fail with the following errors:
> .\" FIXME Davide, are there any other errors for timerfd_create()?
> .TP
> .B EINVAL
> The
> .I clockid
> argument is neither
> .B CLOCK_MONOTONIC
> nor
> .BR CLOCK_REALTIME .
> .TP
> .B EMFILE
> The per-process limit of open file descriptors has been reached.
> .TP
> .B ENFILE
> The system-wide limit on the total number of open files has been
> reached.
> .TP
> .B ENODEV
> Could not mount (internal) anonymous i-node device.
> .TP
> .B ENOMEM
> There was insufficient kernel memory to create the timer.
> .PP
> .BR timer_settime ()
> and
> .BR timer_gettime ()
> can fail with the following errors:

s/timer_/timerfd_/ on the two .BR lines above.

[...]
>         printf("read: %llu; total=%d\\n", exp, tot_exp);

Another nit-pick, but you should really cast the exp argument to
(unsigned long long) to match the format %llu.  Although uint64_t is
the same size as unsigned long long on all current Linux systems (as
far as I know), one day there might be a system where unsigned long
long is, say, 128 bit.

Regards,
Geoff.