diff options
Diffstat (limited to 'static/netbsd/man2/timerfd.2')
| -rw-r--r-- | static/netbsd/man2/timerfd.2 | 323 |
1 files changed, 323 insertions, 0 deletions
diff --git a/static/netbsd/man2/timerfd.2 b/static/netbsd/man2/timerfd.2 new file mode 100644 index 00000000..20398881 --- /dev/null +++ b/static/netbsd/man2/timerfd.2 @@ -0,0 +1,323 @@ +.\" $NetBSD: timerfd.2,v 1.4 2021/09/23 13:59:27 uwe Exp $ +.\" +.\" Copyright (c) 2021 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 17, 2021 +.Dt TIMERFD 2 +.Os +.\" +.\" +.Sh NAME +.Nm timerfd , +.Nm timerfd_create , +.Nm timerfd_gettime , +.Nm timerfd_settime +.Nd create and interact with a timer descriptor +.\" +.\" +.Sh SYNOPSIS +.In sys/timerfd.h +.Ft int +.Fn timerfd_create "clockid_t clockid" "int flags" +.Ft int +.Fn timerfd_gettime "int fd" "struct itimerspec *tim" +.Ft int +.Fn timerfd_settime "int fd" "int flags" \ +"const struct itimerspec *tim" "struct itimerspec *otim" +.\" +.\" +.Sh DESCRIPTION +.Nm +presents an interface to interval timers associated with a file descriptor. +These timers are functionally equivalent to per-process timers but are +associated with a file descriptor, rather than a process. +Because they are associated with a file descriptor, they may be passed +to other processes, inherited across a fork, and multiplexed using +.Xr kevent 2 , +.Xr poll 2 , +or +.Xr select 2 . +When a +.Nm +object is no longer needed, it may be disposed of using +.Xr close 2 . +.Pp +The +.Fn timerfd_create +system call creates a +.Nm +object using the clock specified in the +.Fa clockid +argument. +Valid values for +.Fa clockid +are +.Dv CLOCK_REALTIME +and +.Dv CLOCK_MONOTONIC . +The following flags define the behavior of the resulting object: +.Bl -tag -width Dv +.It Dv TFD_CLOEXEC +This is an alias for the +.Dv O_CLOEXEC +flag; see +.Xr open 2 +for more information. +.It Dv TFD_NONBLOCK +This is an alias for the +.Dv O_NONBLOCK +flag; see +.Xr open 2 +for more information. +.El +.Pp +Each time a +.Nm +timer expires, an internal counter is incremented. +Reads from an +.Nm +object return the value of this counter in the caller's buffer as an +unsigned 64-bit integer and reset the counter to\~0. +If the value of the +.Nm +object's counter is\~0, +then reads will block, unless the +.Nm +object is set for non-blocking I/O. +.Pp +Writes to a +.Nm +object are not supported. +.Pp +The +.Fn timerfd_settime +system call sets the next expiration time of the +.Nm +object to the +.Va it_value +.Po +see +.Xr itimerspec 3 +.Pc +specified in the +.Fa tim +argument. +If the value is\~0, +the timer is disarmed. +If the argument +.Fa otim +is not +.Dv NULL +the old timer settings are returned. +The following flags may be specified to alter the behavior of the timer: +.Bl -tag -width "TFD_TIMER_CANCEL_ON_SET" +.It Dv TFD_TIMER_ABSTIME +The specified timer value is an absolute time. +This is equivalent to specifying +.Dv TIMER_ABSTIME +to +.Xr timer_settime 2 . +Otherwise, the time value is a relative time, equivalent to specifying +.Dv TIMER_RELTIME +to +.Xr timer_settime 2 . +.It Dv TFD_TIMER_CANCEL_ON_SET +If the +.Nm +object's clock ID is +.Dv CLOCK_REALTIME , +then the timer will be cancelled and its file descriptor will become +immediately readable if the system realtime clock is set using +.Xr clock_settime 2 +or +.Xr settimeofday 2 . +If the +.Nm +object's clock ID is not +.Dv CLOCK_REALTIME +this flag is ignored. +.El +.Pp +If the +.Va it_interval +of the +.Fa tim +argument is non-zero, then the timer reloads upon expiration. +.Pp +The +.Fn timerfd_gettime +system call returns the current settings of the +.Nm +object in the +.Fa tim +argument. +.\" +.\" +.Sh RETURN VALUES +The +.Fn timerfd_create +system call returns\~\-1 if an error occurs, +otherwise the return value is a descriptor representing the +.Nm +object. +.Pp +.Rv -std timerfd_gettime timerfd_settime +.\" +.\" +.Sh ERRORS +The +.Fn timerfd +system call fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Flags other than +.Dv TFD_CLOEXEC +and +.Dv TFD_NONBLOCK +are set in the +.Fa flags +argument. +.It Bq Er EINVAL +The +.Fa clockid +argument was something other than +.Dv CLOCK_REALTIME +or +.Dv CLOCK_MONOTONIC . +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.El +.Pp +The +.Fn timerfd_gettime +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa fd +is not a valid file descriptor. +.It Bq Er EFAULT +The +.Fa tim +argument points outside the allocated address space. +.It Bq Er EINVAL +The argument +.Fa fd +does not refer to a +.Nm timerfd +object. +.El +.Pp +The +.Fn timerfd_settime +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa fd +is not a valid file descriptor. +.It Bq Er EFAULT +The +.Fa tim +or +.Fa otim +arguments point outside the allocated address space. +.It Bq Er EINVAL +The argument +.Fa fd +does not refer to a +.Nm timerfd +object. +.It Bq Er EINVAL +Bits other than the defined +.Dv TFD_TIMER_ABSTIME +and +.Dv TFD_TIMER_CANCEL_ON_SET +bits are set in the +.Fa flags +argument. +.It Bq Er EINVAL +A nanosecond field in the +.Fa tim +argument specified a value less than zero or greater than or equal +to\~10^9. +.El +.Pp +A read from a +.Nm +object fails if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The value of the +.Nm +object's expiration counter is +.Dv 0 +and the +.Nm +object is set for non-blocking I/O. +.It Bq Er ECANCELED +The +.Nm +object was created with the clock ID +.Dv CLOCK_REALTIME , +was configured with the +.Dv TFD_TIMER_CANCEL_ON_SET +flag, and the system realtime clock was changed with +.Xr clock_settime 2 +or +.Xr settimeofday 2 . +.It Bq Er EINVAL +The size of the read buffer is less than 8 bytes +.Pq the size required to hold an unsigned 64-bit integer . +.El +.\" +.\" +.Sh SEE ALSO +.Xr clock_settime 2 , +.Xr close 2 , +.Xr kevent 2 , +.Xr open 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr select 2 , +.Xr settimeofday 2 , +.Xr timer_create 2 , +.Xr timer_gettime 2 , +.Xr timer_settime 2 +.\" +.\" +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 10 . +It is compatible with the +.Nm +interface that appeared in Linux 2.6.25. |