diff options
Diffstat (limited to 'usr/src/man/man3c')
| -rw-r--r-- | usr/src/man/man3c/Makefile | 5 | ||||
| -rw-r--r-- | usr/src/man/man3c/epoll_create.3c | 5 | ||||
| -rw-r--r-- | usr/src/man/man3c/epoll_ctl.3c | 19 | ||||
| -rw-r--r-- | usr/src/man/man3c/epoll_wait.3c | 5 | ||||
| -rw-r--r-- | usr/src/man/man3c/timerfd_create.3c | 358 |
5 files changed, 208 insertions, 184 deletions
diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile index f0eff75478..517fd867d0 100644 --- a/usr/src/man/man3c/Makefile +++ b/usr/src/man/man3c/Makefile @@ -1217,6 +1217,8 @@ MANLINKS= FD_CLR.3c \ timer_gettime.3c \ timerclear.3c \ timercmp.3c \ + timerfd_gettime.3c \ + timerfd_settime.3c \ timerisset.3c \ timersub.3c \ tmpnam_r.3c \ @@ -2256,6 +2258,9 @@ timercmp.3c := LINKSRC = timeradd.3c timerisset.3c := LINKSRC = timeradd.3c timersub.3c := LINKSRC = timeradd.3c +timerfd_gettime.3c := LINKSRC = timerfd_create.3c +timerfd_settime.3c := LINKSRC = timerfd_create.3c + tempnam.3c := LINKSRC = tmpnam.3c tmpnam_r.3c := LINKSRC = tmpnam.3c diff --git a/usr/src/man/man3c/epoll_create.3c b/usr/src/man/man3c/epoll_create.3c index 3dd9abf5f7..6f54f638f7 100644 --- a/usr/src/man/man3c/epoll_create.3c +++ b/usr/src/man/man3c/epoll_create.3c @@ -26,7 +26,6 @@ epoll_create, epoll_create1 \- create an epoll instance .fi .SH DESCRIPTION -.sp .LP The \fBepoll_create()\fR and \fBepoll_create1()\fR functions both create an \fBepoll\fR(5) instance that can be operated upon via \fBepoll_ctl\fR(3C), @@ -50,12 +49,10 @@ Instance should be closed upon an .RE .SH RETURN VALUES -.sp .LP Upon succesful completion, 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error. .SH ERRORS -.sp .LP The \fBepoll_create()\fR and \fBepoll_create1()\fR functions will fail if: .sp @@ -89,7 +86,6 @@ The maximum allowable number of files is currently open in the system. .sp .SH NOTES -.sp .LP The \fBepoll\fR(5) facility is implemented for purposes of offering @@ -99,6 +95,5 @@ applications should continue to prefer using event ports via the interfaces. See \fBepoll\fR(5) for compatibility details and restrictions. .SH SEE ALSO -.sp .LP \fBepoll_ctl\fR(3C), \fBepoll_wait\fR(3C), \fBepoll\fR(5) diff --git a/usr/src/man/man3c/epoll_ctl.3c b/usr/src/man/man3c/epoll_ctl.3c index ccf3139396..19c02f2abb 100644 --- a/usr/src/man/man3c/epoll_ctl.3c +++ b/usr/src/man/man3c/epoll_ctl.3c @@ -21,7 +21,6 @@ epoll_ctl \- control an epoll instance .fi .SH DESCRIPTION -.sp .LP The \fBepoll_ctl()\fR function executes the operation specified by \fIop\fR (as parameterized by \fIevent\fR) on the \fIepfd\fR epoll instance. @@ -93,6 +92,7 @@ of any combination of the following event flags: .ne 2 .na \fBEPOLLIN\fR +.ad .RS 14n Data other than high priority data may be read without blocking. For streams, this flag is set in the returned \fIevents\fR even if the message is of @@ -103,6 +103,7 @@ zero length. .ne 2 .na \fBEPOLLPRI\fR +.ad .RS 14n Normal data (priority band equals 0) may be read without blocking. For streams, this flag is set in the returned \fIevents\fR even if the message is of zero @@ -113,6 +114,7 @@ length. .ne 2 .na \fBEPOLLOUT\fR +.ad .RS 14n Normal data (priority band equals 0) may be written without blocking. .RE @@ -121,6 +123,7 @@ Normal data (priority band equals 0) may be written without blocking. .ne 2 .na \fBEPOLLRDNORM\fR +.ad .RS 14n Normal data (priority band equals 0) may be read without blocking. For streams, this flag is set in the returned \fIrevents\fR even if the message is of @@ -131,6 +134,7 @@ zero length. .ne 2 .na \fBEPOLLRDBAND\fR +.ad .RS 14n Data from a non-zero priority band may be read without blocking. For streams, this flag is set in the returned \fIrevents\fR even if the message is of @@ -141,6 +145,7 @@ zero length. .ne 2 .na \fBEPOLLWRNORM\fR +.ad .RS 14n The same as \fBEPOLLOUT\fR. .RE @@ -149,6 +154,7 @@ The same as \fBEPOLLOUT\fR. .ne 2 .na \fBEPOLLWRBAND\fR +.ad .RS 14n Priority data (priority band > 0) may be written. This event only examines bands that have been written to at least once. @@ -158,6 +164,7 @@ bands that have been written to at least once. .ne 2 .na \fBEPOLLMSG\fR +.ad .RS 14n This exists only for backwards binary and source compatibility with Linux; it has no meaning and is ignored. @@ -167,6 +174,7 @@ it has no meaning and is ignored. .ne 2 .na \fBEPOLLERR\fR +.ad .RS 14n An error has occurred on the device or stream. This flag is only valid in the returned \fIevents\fR field. @@ -176,6 +184,7 @@ returned \fIevents\fR field. .ne 2 .na \fBEPOLLHUP\fR +.ad .RS 14n A hangup has occurred on the stream. This event and \fBEPOLLOUT\fR are mutually exclusive; a stream can never be writable if a hangup has occurred. However, @@ -190,6 +199,7 @@ in the \fIevents\fR field specified via \fBepoll_ctl()\fR. .ne 2 .na \fBEPOLLRDHUP\fR +.ad .RS 14n The stream socket peer shutdown the writing half of the connection and no further data will be readable via the socket. This event is not mutually @@ -200,6 +210,7 @@ exclusive with \fBEPOLLIN\fR. .ne 2 .na \fBEPOLLWAKEUP\fR +.ad .RS 14n This exists only for backwards binary and source compatibility with Linux; it has no meaning and is ignored. @@ -209,6 +220,7 @@ it has no meaning and is ignored. .ne 2 .na \fBEPOLLONESHOT\fR +.ad .RS 14n Sets the specified event to be in one-shot mode, whereby the event association with the \fBepoll\fR(5) instance specified by \fIepfd\fR is removed atomically @@ -221,6 +233,7 @@ races inherent in multithreaded use of \fBepoll_wait\fR(3C). .ne 2 .na \fBEPOLLET\fR +.ad .RS 14n Sets the specified event to be edge-triggered mode instead of the default mode of level-triggered. In this mode, events will be induced by @@ -231,14 +244,12 @@ with caution. .RE .SH RETURN VALUES -.sp .LP Upon succesful completion, \fBepoll_ctl()\fR returns 0. If an error occurs, -1 is returned and errno is set to indicate the error. .SH ERRORS -.sp .LP \fBepoll_ctl()\fR will fail if: .sp @@ -283,7 +294,6 @@ specified \fBepoll\fR(5) instance. .sp .SH NOTES -.sp .LP The \fBepoll\fR(5) facility is implemented for purposes of offering @@ -293,7 +303,6 @@ applications should continue to prefer using event ports via the interfaces. See \fBepoll\fR(5) for compatibility details and restrictions. .SH SEE ALSO -.sp .LP \fBepoll_create\fR(3C), \fBepoll_wait\fR(3C), \fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), diff --git a/usr/src/man/man3c/epoll_wait.3c b/usr/src/man/man3c/epoll_wait.3c index 670eebe89c..6ae9e0f9c4 100644 --- a/usr/src/man/man3c/epoll_wait.3c +++ b/usr/src/man/man3c/epoll_wait.3c @@ -29,7 +29,6 @@ epoll_wait, epoll_pwait \- wait for epoll events .fi .SH DESCRIPTION -.sp .LP The \fBepoll_wait()\fR function waits for events on the \fBepoll\fR(5) instance specified by \fIepfd\fR. The \fIevents\fR parameter must point to @@ -46,7 +45,6 @@ signal mask upon return, and is therefore similar to the relationship between \fBselect\fR(3C) and \fBpselect\fR(3C). .SH RETURN VALUES -.sp .LP Upon successful completion, \fBepoll_wait()\fR and \fBepoll_pwait()\fR return the number of events, or 0 if none was pending and \fItimeout\fR milliseconds @@ -54,7 +52,6 @@ elapsed. If an error occurs, -1 is returned and errno is set to indicate the error. .SH ERRORS -.sp .LP The \fBepoll_wait()\fR and \fBepoll_pwait()\fR functions will fail if: .sp @@ -96,7 +93,6 @@ is not greater than zero. .sp .SH NOTES -.sp .LP The \fBepoll\fR(5) facility is implemented for purposes of offering @@ -106,7 +102,6 @@ applications should continue to prefer using event ports via the interfaces. See \fBepoll\fR(5) for compatibility details and restrictions. .SH SEE ALSO -.sp .LP \fBepoll_create\fR(3C), \fBepoll_ctl\fR(3C), \fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), diff --git a/usr/src/man/man3c/timerfd_create.3c b/usr/src/man/man3c/timerfd_create.3c index 167b905d1e..84df47e245 100644 --- a/usr/src/man/man3c/timerfd_create.3c +++ b/usr/src/man/man3c/timerfd_create.3c @@ -1,181 +1,201 @@ -'\" te -.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. -.\" This file and its contents are supplied under the terms of the -.\" Common Development and Distribution License ("CDDL"), version 1.0. -.\" You may only use this file in accordance with the terms of version -.\" 1.0 of the CDDL. -.\" -.\" A full copy of the text of the CDDL should have accompanied this -.\" source. A copy of the CDDL is also available via the Internet at -.\" http://www.illumos.org/license/CDDL. -.TH TIMERFD 3C "Feb 23, 2015" -.SH NAME -timerfd_create, timerfd_settime, timerfd_gettime \- create and manipulate -timers via a file descriptor interface -.SH SYNOPSIS - -.LP -.nf -#include <sys/timerfd.h> - -\fBint\fR \fBtimerfd_create\fR(\fBint\fR \fIclockid\fR, \fBint\fR \fIflags\fR); -.fi - -.LP -.nf -\fBint\fR \fBtimerfd_settime\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIflags\fR, - \fBconst struct itimerspec *restrict\fR \fIvalue\fR, - \fBstruct itimerspec *restrict\fR \fIovalue\fR); -.fi - -.LP -.nf -\fBint\fR \fBtimerfd_gettime\fR(\fBint\fR \fIfd\fR, \fBstruct itimerspec *\fR\fIvalue\fR); -.fi - -.SH DESCRIPTION -.sp -.LP +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved. +.\" +.Dd Feb 23, 2105 +.Dt TIMERFD 3C +.Os +.Sh NAME +.Nm timerfd_create , +.Nm timerfd_settime , +.Nm timerfd_gettime +.Nd create and manipulate timers via a file descriptor interface +.Sh SYNOPSIS +.In sys/timerfd.h +.Ft int +.Fo timerfd_create +.Fa "int clockid" +.Fa "int flags" +.Fc +.Ft int +.Fo timerfd_settime +.Fa "int fd" +.Fa "int flags" +.Fa "const struct itimerspec *restrict value" +.Fa "struct itimterspec *restrict ovalue" +.Fc +.Ft int +.Fo timerfd_gettime +.Fa "int fd" +.Fa "struct itimerspec *value" +.Fc +.Sh DESCRIPTION These routines create and manipulate timers in which events are associated with a file descriptor, allowing for timer-based events to be used -in file-descriptor based facilities like -\fBpoll\fR(2), \fBport_get\fR(3C) or \fBepoll_wait\fR(3C). - -The \fBtimerfd_create()\fR function creates a timer with the clock -type specified by \fIclockid\fR. The \fBCLOCK_REALTIME\fR and -\fBCLOCK_HIGHRES\fR clock types, as defined in \fBtimer_create\fR(3C), -are supported by \fBtimerfd_create()\fR. (Note that \fBCLOCK_MONOTONIC\fR -may be used as an alias for \fBCLOCK_HIGHRES\fR.) - -.sp -The \fIflags\fR argument specifies additional parameters for the -timer instance, and can have any of the following values: - -.sp -.ne 2 -.na -\fBTFD_CLOEXEC\fR -.ad -.RS 12n +in file-descriptor based facilities like +.Xr poll 2 , +.Xr port_get 3C +or +.Xr epoll_wait 3C . +The +.Fn timerfd_create +function creates a timer with the clock +type specified by +.Fa clockid . +The +.Sy CLOCK_REALTIME +and +.Sy CLOCK_HIGHRES +clock types, as defined in +.Xr timer_create 3C , +are supported by +.Fn timerfd_create . +(Note that +.Sy CLOCK_MONOTONIC +may be used as an alias for +.Sy CLOCK_HIGHRES Ns .) +.Pp +The +.Fa flags +argument specifies additional parameters for the timer instance, and can have +any of the following values: +.Bl -hang -width Ds +.It Sy TFD_CLOEXEC +.Bd -filled -compact Instance will be closed upon an -\fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR. -.RE - -.sp -.ne 2 -.na -\fBTFD_NONBLOCK\fR -.ad -.RS 12n -Instance will be set to be non-blocking. A \fBread\fR(2) on a -\fBtimerfd\fR instance that has been initialized with -\fBTFD_NONBLOCK\fR will return \fBEAGAIN\fR in lieu of blocking if the -timer has not expired since the last \fBtimerfd_settime()\fR or successful -\fBread()\fR. -.RE - -.sp -The following operations can be performed upon a \fBtimerfd\fR instance: - -.sp -.ne 2 -.na -\fBread\fR(2) -.ad -.RS 12n +.Xr exec 2 ; +see +.Xr open 2 Ns 's +description of +.Sy O_CLOEXEC . +.Ed +.It Sy TFD_NONBLOCK +.Bd -filled -compact +Instance will be set to be non-blocking. A +.Xr read 2 +on a +.Sy timerfd +instance that has been initialized with +.Sy TFD_NONBLOCK +will return +.Sy EAGAIN +in lieu of blocking if the +timer has not expired since the last +.Fn timerfd_settime +or successful +.Fn read . +.Ed +.El +.Pp +The following operations can be performed upon a +.Sy timerfd +instance: +.Bl -hang -width Ds +.It Sy read(2) +.Bd -filled -compact Atomically reads and clears the number of timer expirations since the -last successful \fBread\fR(2) or \fBtimerfd_settime()\fR. Upon success, +last successful +.Xr read 2 +or +.Fn timerfd_settime . +Upon success, the number of expirations will be copied into the eight byte buffer passed to the system call. If there have been no expirations of the -timer since the last successful \fBread\fR(2) or \fBtimerfd_settime()\fR, -\fBread\fR(2) will block until at least the next expiration, -or return \fBEAGAIN\fR if the instance was created with -\fBTFD_NONBLOCK\fR. Note that if multiple threads are blocked in -\fBread\fR(2) for the same timer, only one of them will return upon +timer since the last successful +.Xr read 2 +or +.Fn timerfd_sttime , +.Xr read 2 +will block until at least the next expiration, +or return +.Sy EAGAIN +if the instance was created with +.Sy TFD_NONBLOCK . +Note that if multiple threads are blocked in +.Xr read 2 +for the same timer, only one of them will return upon a single timer expiration. - -If the buffer specified to \fBread\fR(2) is less than -eight bytes in length, \fBEINVAL\fR will be returned. -.RE - -.sp -.ne 2 -.na -\fBpoll\fR(2), \fBport_get\fR(3C), \fBepoll_wait\fR(3C) -.ad -.RS 12n +.Pp +If the buffer specified to +.Xr read 2 +is less than +eight bytes in length, +.Sy EINAVL +will be returned. +.Ed +.It Sy poll(2), port_get(3C), epoll_wait(3C) +.Bd -filled -compact Provide notification when the timer expires or has expired in the past without -a more recent \fBread\fR(2). Note that threads being simultaneously -blocked in \fBread\fR(2) and \fBpoll\fR(2) (or equivalents) for the same +a more recent +.Xr read 2 . +Note that threads being simultaneously +blocked in +.Xr read 2 +and +.Xr poll 2 +(or equivalents) for the same timer constitute an application-level race; on a timer expiration, -the thread blocked in \fBpoll\fR(2) may or may not return depending on how -it is scheduled with respect to the thread blocked in \fBread\fR(2). -.RE - -.sp -.ne 2 -.na -\fBtimerfd_gettime()\fR -.ad -.RS 12n +the thread blocked in +.Xr poll 2 +may or may not return depending on how +it is scheduled with respect to the thread blocked in +.Xr read 2 . +.Ed +.It Sy timerfd_gettime() +.Bd -filled -compact Returns the amount of time until the next timer expiration, with the -same functional signature and semantics as \fBtimer_gettime\fR(3C). -.RE - -.sp -.ne 2 -.na -\fBtimerfd_settime()\fR -.ad -.RS 12n +same functional signature and semantics as +.Xr timer_gettime 3C . +.Ed +.It Sy timerfd_settime() +.Bd -filled -compact Sets or disarms the timer, with the -same functional signature and semantics as \fBtimer_settime\fR(3C). -.RE - -.SH RETURN VALUES -.sp -.LP +same functional signature and semantics as +.Xr timer_settime 3C . +.Ed +.El +.Sh RETURN VALUES Upon succesful completion, a file descriptor associated with the instance -is returned. Otherwise, -1 is returned and errno -is set to indicate the error. -.SH ERRORS -.sp -.LP -The \fBtimerfd_create()\fR function will fail if: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -The \fIflags\fR are invalid. -.RE - -.sp -.ne 2 -.na -\fB\fBEMFILE\fR\fR -.ad -.RS 10n -There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling -process. -.RE - -.sp -.ne 2 -.na -\fB\fBEPERM\fR\fR -.ad -.RS 10n -The \fIclock_id\fR, is \fBCLOCK_HIGHRES\fR and the -{\fBPRIV_PROC_CLOCK_HIGHRES\fR} is not asserted in the effective set of the -calling process. -.RE - -.SH SEE ALSO -.sp -.LP -\fBpoll\fR(2), \fBport_get\fR(3C), \fBepoll_wait\fR(3C), -\fBtimer_create\fR(3C), \fBtimer_gettime\fR(3C), \fBtimer_settime\fR(3C), -\fBprivileges\fR(5), \fBtimerfd\fR(5) - +is returned. Otherwise, +.Sy -1 +is returned and errno is set to indicate the error. +.Sh ERRORS +The +.Fn timerfd_create() +function will fail if: +.Bl -tag -width Er +.It Er EINAL +The +.Fa flags +are invalid. +.It Er EMFILE +There are currently +.Pf { Sy OPEN_MAX Ns } +file descriptors open in the calling process. +.It Er EPERM +The +.Fa clock_id , +is +.Sy CLOCK_HIGHRES +and the +.Pf { Sy PRIV_PROC_CLOCK_HIGHRES Ns } +is not asserted in the effective set of the calling process. +.El +.Sh SEE ALSO +.Xr poll 2 , +.Xr port_get 3C , +.Xr epoll_wait 3C , +.Xr timer_create 3C , +.Xr timer_gettime 3C , +.Xr timer_settime 3C , +.Xr privileages 5 , +.Xr timerfd 5 |