diff options
Diffstat (limited to 'usr/src/man/man3c')
| -rw-r--r-- | usr/src/man/man3c/Makefile | 14 | ||||
| -rw-r--r-- | usr/src/man/man3c/epoll_create.3c | 104 | ||||
| -rw-r--r-- | usr/src/man/man3c/epoll_ctl.3c | 300 | ||||
| -rw-r--r-- | usr/src/man/man3c/epoll_wait.3c | 113 | ||||
| -rw-r--r-- | usr/src/man/man3c/flock.3c | 209 | ||||
| -rw-r--r-- | usr/src/man/man3c/inotify_add_watch.3c | 120 | ||||
| -rw-r--r-- | usr/src/man/man3c/inotify_init.3c | 107 | ||||
| -rw-r--r-- | usr/src/man/man3c/inotify_rm_watch.3c | 81 | ||||
| -rw-r--r-- | usr/src/man/man3c/lockf.3c | 15 | ||||
| -rw-r--r-- | usr/src/man/man3c/madvise.3c | 32 | ||||
| -rw-r--r-- | usr/src/man/man3c/priv_addset.3c | 13 | ||||
| -rw-r--r-- | usr/src/man/man3c/psignal.3c | 9 | ||||
| -rw-r--r-- | usr/src/man/man3c/signalfd.3c | 192 | ||||
| -rw-r--r-- | usr/src/man/man3c/timerfd_create.3c | 181 |
14 files changed, 1477 insertions, 13 deletions
diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile index a31d024d15..975c56e921 100644 --- a/usr/src/man/man3c/Makefile +++ b/usr/src/man/man3c/Makefile @@ -110,6 +110,9 @@ MANFILES= __fbufsize.3c \ enable_extended_FILE_stdio.3c \ encrypt.3c \ end.3c \ + epoll_create.3c \ + epoll_ctl.3c \ + epoll_wait.3c \ err.3c \ euclen.3c \ eventfd.3c \ @@ -128,6 +131,7 @@ MANFILES= __fbufsize.3c \ fgetpos.3c \ fgetwc.3c \ floating_to_decimal.3c \ + flock.3c \ flockfile.3c \ fmtmsg.3c \ fnmatch.3c \ @@ -202,6 +206,9 @@ MANFILES= __fbufsize.3c \ imaxdiv.3c \ index.3c \ initgroups.3c \ + inotify_init.3c \ + inotify_add_watch.3c \ + inotify_rm_watch.3c \ insque.3c \ is_system_labeled.3c \ isaexec.3c \ @@ -408,6 +415,7 @@ MANFILES= __fbufsize.3c \ sigfpe.3c \ siginterrupt.3c \ signal.3c \ + signalfd.3c \ sigqueue.3c \ sigsetops.3c \ sigstack.3c \ @@ -470,6 +478,7 @@ MANFILES= __fbufsize.3c \ timer_delete.3c \ timer_settime.3c \ timeradd.3c \ + timerfd_create.3c \ tmpfile.3c \ tmpnam.3c \ toascii.3c \ @@ -733,6 +742,8 @@ MANLINKS= FD_CLR.3c \ endusershell.3c \ endutent.3c \ endutxent.3c \ + epoll_create1.3c \ + epoll_pwait.3c \ erand48.3c \ errno.3c \ errx.3c \ @@ -1581,6 +1592,9 @@ _etext.3c := LINKSRC = end.3c edata.3c := LINKSRC = end.3c etext.3c := LINKSRC = end.3c +epoll_create1.3c := LINKSRC = epoll_create.3c +epoll_pwait.3c := LINKSRC = epoll_wait.3c + errx.3c := LINKSRC = err.3c verr.3c := LINKSRC = err.3c verrx.3c := LINKSRC = err.3c diff --git a/usr/src/man/man3c/epoll_create.3c b/usr/src/man/man3c/epoll_create.3c new file mode 100644 index 0000000000..3dd9abf5f7 --- /dev/null +++ b/usr/src/man/man3c/epoll_create.3c @@ -0,0 +1,104 @@ +'\" 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 EPOLL_CREATE 3C "Apr 17, 2014" +.SH NAME +epoll_create, epoll_create1 \- create an epoll instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/epoll.h> + +\fBint\fR \fBepoll_create\fR(\fBint\fR \fIsize\fR); +.fi + +.LP +.nf +\fBint\fR \fBepoll_create1\fR(\fBint\fR \fIflags\fR); +.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), +\fBepoll_wait\fR(3C) and \fBepoll_pwait\fR(3C). \fBepoll\fR instances are +represented as file descriptors, and should be closed via \fBclose\fR(2). + +The only difference between the two functions is their signature; +\fBepoll_create()\fR takes a size argument that +is vestigal and is only meaningful in as much as it must be greater than +zero, while \fBepoll_create1()\fR takes a flags argument that can have +any of the following values: + +.sp +.ne 2 +.na +\fBEPOLL_CLOEXEC\fR +.ad +.RS 12n +Instance should be closed upon an +\fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR. +.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 +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +Either the \fIsize\fR is zero (\fBepoll_create()\fR) or the \fIflags\fR +are invalid (\fBepoll_create1()\fR). +.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\fBENFILE\fR\fR +.ad +.RS 10n +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.SH NOTES +.sp +.LP + +The \fBepoll\fR(5) facility is implemented for purposes of offering +compatibility for Linux-borne applications; native +applications should continue to prefer using event ports via the +\fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C) +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 new file mode 100644 index 0000000000..ccf3139396 --- /dev/null +++ b/usr/src/man/man3c/epoll_ctl.3c @@ -0,0 +1,300 @@ +'\" 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 EPOLL_CTL 3C "Apr 17, 2014" +.SH NAME +epoll_ctl \- control an epoll instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/epoll.h> + +\fBint\fR \fBepoll_ctl\fR(\fBint\fR \fIepfd\fR, \fBint\fR \fIop\fR, \fBint\fR \fIfd\fR, \fBstruct epoll_event *\fR\fIevent\fR); +.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. +Valid values for \fIop\fR: + +.sp +.ne 2 +.na +\fBEPOLL_CTL_ADD\fR +.ad +.RS 12n +For the \fBepoll\fR(5) instance specified by \fIepfd\fR, +associate the file descriptor specified by \fIfd\fR with the event specified +by \fIevent\fR. +.RE + +.sp +.ne 2 +.na +\fBEPOLL_CTL_DEL\fR +.ad +.RS 12n +For the \fBepoll\fR(5) instance specified by \fIepfd\fR, +remove all event associations for the file descriptor specified by \fIfd\fR. +\fIevent\fR is ignored, and may be NULL. +.RE + +.sp +.ne 2 +.na +\fBEPOLL_CTL_MOD\fR +.ad +.RS 12n +For the \fBepoll\fR(5) instance specified by \fIepfd\fR, modify the event +association for the file descriptor specified by \fIfd\fR to be that +specified by \fIevent\fR. + +.RE + +The \fIevent\fR parameter has the following structure: + +.in +4 +.nf +typedef union epoll_data { + void *ptr; + int fd; + uint32_t u32; + uint64_t u64; +} epoll_data_t; + +struct epoll_event { + uint32_t events; + epoll_data_t data; +}; +.fi +.in -4 + +The \fIdata\fR field specifies the datum to +be associated with the event and +will be returned via \fBepoll_wait\fR(3C). +The \fIevents\fR field denotes both the desired events (when specified via +\fBepoll_ctl()\fR) and the events that have occurred (when returned via +\fBepoll_wait\fR(3C)). +In either case, the +\fIevents\fR field is a bitmask constructed by a logical \fBOR\fR operation +of any combination of the following event flags: + +.sp +.ne 2 +.na +\fBEPOLLIN\fR +.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 +zero length. +.RE + +.sp +.ne 2 +.na +\fBEPOLLPRI\fR +.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 +length. +.RE + +.sp +.ne 2 +.na +\fBEPOLLOUT\fR +.RS 14n +Normal data (priority band equals 0) may be written without blocking. +.RE + +.sp +.ne 2 +.na +\fBEPOLLRDNORM\fR +.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 +zero length. +.RE + +.sp +.ne 2 +.na +\fBEPOLLRDBAND\fR +.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 +zero length. +.RE + +.sp +.ne 2 +.na +\fBEPOLLWRNORM\fR +.RS 14n +The same as \fBEPOLLOUT\fR. +.RE + +.sp +.ne 2 +.na +\fBEPOLLWRBAND\fR +.RS 14n +Priority data (priority band > 0) may be written. This event only examines +bands that have been written to at least once. +.RE + +.sp +.ne 2 +.na +\fBEPOLLMSG\fR +.RS 14n +This exists only for backwards binary and source compatibility with Linux; +it has no meaning and is ignored. +.RE + +.sp +.ne 2 +.na +\fBEPOLLERR\fR +.RS 14n +An error has occurred on the device or stream. This flag is only valid in the +returned \fIevents\fR field. +.RE + +.sp +.ne 2 +.na +\fBEPOLLHUP\fR +.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, +this event and \fBEPOLLIN\fR, \fBEPOLLRDNORM\fR, \fBEPOLLRDBAND\fR, +\fBEPOLLRDHUP\fR or +\fBEPOLLPRI\fR are not mutually exclusive. This flag is only valid in the +the \fIevents\fR field returned from \fBepoll_wait\fR(3C); it is not used +in the \fIevents\fR field specified via \fBepoll_ctl()\fR. +.RE + +.sp +.ne 2 +.na +\fBEPOLLRDHUP\fR +.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 +exclusive with \fBEPOLLIN\fR. +.RE + +.sp +.ne 2 +.na +\fBEPOLLWAKEUP\fR +.RS 14n +This exists only for backwards binary and source compatibility with Linux; +it has no meaning and is ignored. +.RE + +.sp +.ne 2 +.na +\fBEPOLLONESHOT\fR +.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 +as the event is returned via \fBepoll_wait\fR(3C). Use of this mode allows +for resolution of some of the +races inherent in multithreaded use of \fBepoll_wait\fR(3C). +.RE + +.sp +.ne 2 +.na +\fBEPOLLET\fR +.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 +transitions on an event source rather than the state of the event source. +While perhaps superficially appealing, this mode introduces several new +potential failure modes for user-level software and should be used +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 +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +\fIepfd\fR is not a valid file descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +The memory associated with \fIevent\fR was not mapped. +.RE + +.sp +.ne 2 +.na +\fB\fBEEXIST\fR\fR +.ad +.RS 10n +The operation specified was \fBEPOLL_CTL_ADD\fR and the specified file +descriptor is already associated with an event for the specified +\fBepoll\fR(5) instance. +.RE + +.sp +.ne 2 +.na +\fB\fBENOENT\fR\fR +.ad +.RS 10n +The operation specified was \fBEPOLL_CTL_MOD\fR or \fBEPOLL_CTL_DEL\fR and +the specified file descriptor is not associated with an event for the +specified \fBepoll\fR(5) instance. +.RE + +.sp +.SH NOTES +.sp +.LP + +The \fBepoll\fR(5) facility is implemented for purposes of offering +compatibility for Linux-borne applications; native +applications should continue to prefer using event ports via the +\fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C) +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), +\fBepoll\fR(5) diff --git a/usr/src/man/man3c/epoll_wait.3c b/usr/src/man/man3c/epoll_wait.3c new file mode 100644 index 0000000000..670eebe89c --- /dev/null +++ b/usr/src/man/man3c/epoll_wait.3c @@ -0,0 +1,113 @@ +'\" 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 EPOLL_WAIT 3C "Apr 17, 2014" +.SH NAME +epoll_wait, epoll_pwait \- wait for epoll events +.SH SYNOPSIS + +.LP +.nf +#include <sys/epoll.h> + +\fBint\fR \fBepoll_wait\fR(\fBint\fR \fIepfd\fR, \fBstruct epoll_event *\fR\fIevents\fR, + \fBint\fR \fImaxevents\fR, \fBint\fR \fItimeout\fR); +.fi + +.LP +.nf +\fBint\fR \fBepoll_pwait\fR(\fBint\fR \fIepfd\fR, \fBstruct epoll_event *\fR\fIevents\fR, + \fBint\fR \fImaxevents\fR, \fBint\fR \fItimeout\fR, + \fBconst sigset_t *\fR\fIsigmask\fR); +.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 +an array of \fImaxevents\fR \fIepoll_event\fR structures to be +filled in with pending events. The \fItimeout\fR argument specifies the +number of milliseconds to wait for an event if none is pending. A +\fItimeout\fR of -1 denotes an infinite timeout. + +The \fBepoll_pwait()\fR is similar to \fBepoll_wait()\fR, but takes an +additional \fIsigmask\fR argument that specifies the desired signal mask +when \fBepoll_pwait()\fR is blocked. It is equivalent to atomically +setting the signal mask, calling \fBepoll_wait()\fR, and restoring the +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 +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 +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +\fIepfd\fR is not a valid file descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +The memory associated with \fIevents\fR was not mapped or was not writable. +.RE + +.sp +.ne 2 +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +A signal was received during the \fBepoll_wait()\fR or \fBepoll_pwait()\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +Either \fIepfd\fR is not a valid \fBepoll\fR(5) instance or \fImaxevents\fR +is not greater than zero. +.RE + +.sp +.SH NOTES +.sp +.LP + +The \fBepoll\fR(5) facility is implemented for purposes of offering +compatibility for Linux-borne applications; native +applications should continue to prefer using event ports via the +\fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C) +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), +\fBpselect\fR(3C), \fBepoll\fR(5) diff --git a/usr/src/man/man3c/flock.3c b/usr/src/man/man3c/flock.3c new file mode 100644 index 0000000000..a0953f67f9 --- /dev/null +++ b/usr/src/man/man3c/flock.3c @@ -0,0 +1,209 @@ +.\" +.\" 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 1989 AT&T +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Copyright 2015 Joyent, Inc. +.\" +.TH FLOCK 3C "Feb 16, 2015" +.SH NAME +flock \- OFD(open file description)-style file locking +.SH SYNOPSIS +.LP +.nf +#include <sys/file.h> + +\fBint\fR \fBflock\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIoperation\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBflock()\fR function allows advisory locks to be applied to and removed +from a file. Calls to \fBflock()\fR from callers that attempt to lock +the locked file section via a different open file handle will either return an +error value or be put to sleep until the resource becomes unlocked. +See \fBfcntl\fR(2) for more information about record locking. Locks created or +removed via this function will apply to the entire file, including any future +growth in the file's length. +.sp +.LP +The \fIfildes\fR argument is an open file descriptor. A lock can be established +without regard for the mode with which the file was opened. +.sp +.LP +The \fIoperation\fR argument is a control value that specifies the action to be +taken. The permissible values for \fIoperation\fR are defined in +<\fBsys/file.h\fR> as follows: +.sp +.in +2 +.nf +#define LOCK_SH 1 /* shared file lock */ +#define LOCK_EX 2 /* exclusive file lock */ +#define LOCK_NB 4 /* do not block when attempting to create lock */ +#define LOCK_UN 8 /* remove existing file lock */ +.fi +.in -2 + +.sp +.LP +To create a lock, either \fBLOCK_SH\fR or \fBLOCK_EX\fR should be specified, +optionally bitwise-ored with \fBLOCK_NB\fR. To remove a lock, \fBLOCK_UN\fR +should be specified. All other values of \fIoperation\fR are reserved for +future extensions and will result in an error if not implemented. +.sp +.LP +This function creates, upgrades, downgrades, or removes either shared or +exclusive OFD-style locks. Locks created by this function are owned by open +files, not file descriptors. That is, file descriptors duplicated through +\fBdup\fR(2), \fBfork\fR(2), or \fBfcntl\fR(2) do not result in multiple +instances of a lock, but rather multiple references to the same lock. If a +process holding a lock on a file forks and the child explicitly unlocks the +file, the parent will lose its lock. See \fBfcntl\fR(2) for more information +about file locking and the interaction between locks created by this function +and those created by other mechanisms. These locks are currently not supported +over remote file systems (e.g. \fBnfs\fR(4)) which use the Network Lock +Manager. +.sp +.LP +Sleeping on a resource is interrupted with any signal. The \fBalarm\fR(2) +function may be used to provide a timeout facility in applications that require +this facility. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBflock()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 20n +The \fIfildes\fR argument is not a valid open file descriptor; or +\fIoperation\fR contains \fBLOCK_SH\fR and \fIfiledes\fR is not open for +reading; or \fIoperation\fR contains \fBLOCK_EX\fR and \fIfiledes\fR is not +open for writing. +.RE + +.sp +.ne 2 +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 20n +The \fIoperation\fR argument contains \fBLOCK_NB\fR and a conflicting lock +exists. +.RE + +.sp +.ne 2 +.na +\fB\fBEINTR\fR\fR +.ad +.RS 20n +A signal was caught during execution of the function. +.RE + +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 20n +The \fIoperation\fR argument does not contain one of \fBLOCK_SH\fR, +\fBLOCK_EX\fR, or \fBLOCK_UN\fR; or the \fIoperation\fR argument contains +\fBLOCK_UN\fR and \fBLOCK_NB\fR; or the \fIoperation\fR argument contains +any bits other than those set by \fBLOCK_SH\fR, \fBLOCK_EX\fR, \fBLOCK_NB\fR, +and \fBLOCK_UN\fR. +.RE + +.sp +.LP +The \fBflock()\fR function may fail if: +.sp +.ne 2 +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 24n +The \fIoperation\fR argument contains \fBLOCK_SH\fR or \fBLOCK_EX\fR and the +file is mapped with \fBmmap\fR(2). +.RE + +.sp +.ne 2 +.na +\fB\fBENOLCK\fR\fR +.ad +.RS 20n +The number of locked file regions in the system would exceed a system-imposed +limit. +.RE + +.sp +.ne 2 +.na +\fB\fBEOPNOTSUPP\fR +.ad +.RS 24n +The locking of files of the type indicated by the \fIfildes\fR argument is not +supported. +.RE + +.SH USAGE +.sp +.LP +File-locking should not be used in combination with the \fBfopen\fR(3C), +\fBfread\fR(3C), \fBfwrite\fR(3C) and other \fBstdio\fR functions. Instead, +the more primitive, non-buffered functions (such as \fBopen\fR(2)) should be +used. Unexpected results may occur in processes that do buffering in the user +address space. The process may later read/write data which is/was locked. The +\fBstdio\fR functions are the most common source of unexpected buffering. +.sp +.LP +The \fBalarm\fR(2) function may be used to provide a timeout facility in +applications requiring it. +.sp +.LP +Locks created by this facility conflict with those created by the +\fBlockf\fR(3C) and \fBfcntl\fR(2) facilities. This facility creates and +removed OFD-style locks; see \fBfcntl\fR(2) for information about the +interaction between OFD-style and POSIX-style file locks. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Standard +_ +MT-Level MT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBalarm\fR(2), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2), +\fBfcntl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/inotify_add_watch.3c b/usr/src/man/man3c/inotify_add_watch.3c new file mode 100644 index 0000000000..4f79e03c82 --- /dev/null +++ b/usr/src/man/man3c/inotify_add_watch.3c @@ -0,0 +1,120 @@ +'\" 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 INOTIFY_ADD_WATCH 3C "Sep 17, 2014" +.SH NAME +inotify_add_watch \- add a watch to an inotify instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/inotify.h> + +\fBint\fR \fBinotify_add_watch\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIpathname\fR, \fBuint32_t\fR \fImask\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinotify_add_watch()\fR function adds a watch for the file or +directory specified by \fIpathname\fR to the inotify instance +specified by \fIfd\fR for the events specified by \fImask\fR. See +\fBinotify\fR(5) for details on the meaning of \fImask\fR, how +it affects the interpretation of \fIpathname\fR, and how +events for the watched file or directory are subsequently +retrieved via \fBread\fR(2). + +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, \fBinotify_add_watch()\fR returns the +watch descriptor associated with the new watch. +If an error occurs, -1 is returned and errno is set to indicate +the error. + +.SH ERRORS +.sp +.LP +\fBinotify_add_watch()\fR will fail if: +.sp +.ne 2 +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +\fIpathname\fR could not be opened for reading. +.RE + +.sp +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +The \fIfd\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +The memory associated with \fIpathname\fR was not mapped. +.RE + +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +The \fIfd\fR argument does not correspond to an +\fBinotify\fR(5) instance as initialized with +\fBinotify_init\fR(3C) or \fBinotify_init1\fR(3C). +.RE + +.sp +.ne 2 +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 10n +The number of watches on the specified instance would exceed the +maximum number of watches per \fBinotify\fR(5) instance. +.RE + +.sp +.ne 2 +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 10n +\fIpathname\fR does not correspond to a directory and +\fBIN_ONLYDIR\fR was specified in \fImask\fR. +.RE + +.sp +.SH NOTES +.sp +.LP + +While the \fBinotify\fR(5) facility is implemented for purposes of +offering compatibility for Linux-borne applications, native +applications may opt to use it instead of (or in addition to) the +\fBPORT_SOURCE_FILE\fR capability of event ports. See +\fBinotify\fR(5) for details and restrictions. + +.SH SEE ALSO +.sp +.LP +\fBinotify_init\fR(3C), \fBinotify_init1\fR(3C), +\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), +\fBinotify\fR(5) diff --git a/usr/src/man/man3c/inotify_init.3c b/usr/src/man/man3c/inotify_init.3c new file mode 100644 index 0000000000..551a2ca798 --- /dev/null +++ b/usr/src/man/man3c/inotify_init.3c @@ -0,0 +1,107 @@ +'\" 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 INOTIFY_INIT 3C "Sep 17, 2014" +.SH NAME +inotify_init, inotify_init1 \- initialize an inotify instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/inotify.h> + +\fBint\fR \fBinotify_init\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBinotify_init1\fR(\fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinotify_init()\fR and \fBinotify_init1()\fR functions both create an +\fBinotify\fR(5) instance that can be operated upon via +\fBinotify_add_watch\fR(3C), \fBinotify_rm_watch\fR(3C) and \fBread\fR(2). +\fBinotify\fR instances are +represented as file descriptors, and should be closed via \fBclose\fR(2). + +The only difference between the two functions is their signature; +\fBinotify_init()\fR takes no arguments, +while \fBinotify_init1()\fR takes a \fIflags\fR argument that can have +any of the following values: + +.sp +.ne 2 +.na +\fBIN_CLOEXEC\fR +.ad +.RS 12n +Instance should be closed upon an +\fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR. +.RE + +.sp +.ne 2 +.na +\fBIN_NONBLOCK\fR +.ad +.RS 12n +Instance will be set to be non-blocking. A \fBread\fR(2) on an +\fBinotify\fR instance that has been initialized with +\fBIN_NONBLOCK\fR will return \fBEAGAIN\fR if there are +no events enqueued in lieu of blocking. +.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 \fBinotify_init()\fR and \fBinotify_init1()\fR functions will fail if: +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +The \fIflags\fR are invalid (\fBinotify_init1()\fR). +.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, or the maximum number of \fBinotify\fR instances for the user +would be exceeded. +.RE + +.sp +.SH NOTES +.sp +.LP + +While the \fBinotify\fR(5) facility is implemented for purposes of +offering compatibility for Linux-borne applications, native +applications may opt to use it instead of (or in addition to) the +\fBPORT_SOURCE_FILE\fR capability of event ports. See +\fBinotify\fR(5) for details and restrictions. + +.SH SEE ALSO +.sp +.LP +\fBinotiy_add_watch\fR(3C), \fBinotify_rm_watch\fR(3C), \fBinotify\fR(5) diff --git a/usr/src/man/man3c/inotify_rm_watch.3c b/usr/src/man/man3c/inotify_rm_watch.3c new file mode 100644 index 0000000000..de568f8e24 --- /dev/null +++ b/usr/src/man/man3c/inotify_rm_watch.3c @@ -0,0 +1,81 @@ +'\" 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 INOTIFY_RM_WATCH 3C "Sep 17, 2014" +.SH NAME +inotify_rm_watch \- remove a watch from an inotify instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/inotify.h> + +\fBint\fR \fBinotify_rm_watch\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIwd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinotify_rm_watch()\fR function removes the watch specified +by \fIwd\fR from the inotify instance associated with \fIfd\fR. +Removing a watch will induce an \fBIN_IGNORED\fR event; see +\fBinotify\fR(5) for details. + +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, \fBinotify_add_watch()\fR returns the +watch descriptor associated with the new watch. +If an error occurs, -1 is returned and errno is set to indicate +the error. + +.SH ERRORS +.sp +.LP +\fBinotify_rm_watch()\fR will fail if: +.sp +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +The \fIfd\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +The \fIfd\fR argument does not correspond to an +\fBinotify\fR(5) instance as initialized with +\fBinotify_init\fR(3C) or \fBinotify_init1\fR(3C), or +\fIwd\fR is not a valid watch for the specified inotify +instance. +.RE + +.sp +.SH NOTES +.sp +.LP + +While the \fBinotify\fR(5) facility is implemented for purposes of +offering compatibility for Linux-borne applications, native +applications may opt to use it instead of (or in addition to) the +\fBPORT_SOURCE_FILE\fR capability of event ports. See +\fBinotify\fR(5) for details and restrictions. + +.SH SEE ALSO +.sp +.LP +\fBinotify_init\fR(3C), \fBinotify_init1\fR(3C), +\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), +\fBinotify\fR(5) diff --git a/usr/src/man/man3c/lockf.3c b/usr/src/man/man3c/lockf.3c index 3b698f60a7..818dab24a2 100644 --- a/usr/src/man/man3c/lockf.3c +++ b/usr/src/man/man3c/lockf.3c @@ -1,4 +1,5 @@ '\" te +.\" Copyright 2015 Joyent, Inc. .\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at .\" http://www.opengroup.org/bookstore/. @@ -7,9 +8,9 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH LOCKF 3C "May 27, 2014" +.TH LOCKF 3C "Feb 16, 2015" .SH NAME -lockf \- record locking on files +lockf \- POSIX-style record locking on files .SH SYNOPSIS .LP .nf @@ -22,7 +23,7 @@ lockf \- record locking on files .sp .LP The \fBlockf()\fR function allows sections of a file to be locked; advisory or -mandatory write locks depending on the mode bits of the file (see +mandatory write locks depending on the mode bits of the file (see \fBchmod\fR(2)). Calls to \fBlockf()\fR from other threads that attempt to lock the locked file section will either return an error value or be put to sleep until the resource becomes unlocked. All the locks for a process are removed @@ -54,10 +55,10 @@ All other values of \fIfunction\fR are reserved for future extensions and will result in an error if not implemented. .sp .LP -\fBF_TEST\fR is used to detect if a lock by another process is present on the -specified section. \fBF_LOCK\fR and \fBF_TLOCK\fR both lock a section of a file -if the section is available. \fBF_ULOCK\fR removes locks from a section of the -file. +\fBF_TEST\fR is used to detect if a lock by another process or open file handle +is present on the specified section. \fBF_LOCK\fR and \fBF_TLOCK\fR both lock +a section of a file if the section is available. \fBF_ULOCK\fR removes locks +from a section of the file. .sp .LP The \fIsize\fR argument is the number of contiguous bytes to be locked or diff --git a/usr/src/man/man3c/madvise.3c b/usr/src/man/man3c/madvise.3c index dd2a72823b..91305f6fe6 100644 --- a/usr/src/man/man3c/madvise.3c +++ b/usr/src/man/man3c/madvise.3c @@ -22,7 +22,10 @@ The \fBmadvise()\fR function advises the kernel that a region of user mapped memory in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) will be accessed following a type of pattern. The kernel uses this information to optimize the procedure for manipulating and maintaining the resources associated with the -specified mapping range. +specified mapping range. In general (and true to the name of the function), +the advice is merely advisory, and the only user-visible ramifications +are in terms of performance, not semantics. Note that +\fBMADV_PURGE\fR is an exception to this; see below for details. .sp .LP Values for \fIadvice\fR are defined in <\fBsys/mman.h\fR> as: @@ -38,6 +41,7 @@ Values for \fIadvice\fR are defined in <\fBsys/mman.h\fR> as: #define MADV_ACCESS_DEFAULT 0x6 /* default access */ #define MADV_ACCESS_LWP 0x7 /* next LWP to access heavily */ #define MADV_ACCESS_MANY 0x8 /* many processes to access heavily */ +#define MADV_PURGE 0x9 /* contents will be purged */ .fi .in -2 @@ -99,6 +103,12 @@ kernel would need to read in from the file. .RS 23n Tell the kernel that the specified address range is no longer needed, so the system starts to free the resources associated with the address range. +While the semantics of \fBMADV_DONTNEED\fR are similar to other systems, +they differ signifcantly from the semantics on Linux, where +\fBMADV_DONTNEED\fR will actually synchronously purge the address range, +and subsequent faults will load from either backing store or be +zero-filled on demand. If the peculiar Linux semantics are +desired, \fBMADV_PURGE\fR should be used in lieu of \fBMADV_DONTNEED\fR. .RE .sp @@ -122,6 +132,26 @@ This value cannot be used on mappings that have underlying file objects. .sp .ne 2 .na +\fB\fBMADV_PURGE\fR\fR +.ad +.RS 23n +Tell the kernel to purge the specified address range. The mapping will +be retained, but the pages themselves will be destroyed; subsequent +faults on the range will result in the page being read from backing +store (if file-backed) or being zero-filled on demand (if anonymous). Note +that these semantics are generally inferior to \fBMADV_FREE\fR, which gives the +system more flexibility and results in better performance +when pages are, in fact, reused by the caller. Indeed, \fBMADV_PURGE\fR only +exists to provide an equivalent to the unfortunate +\fBMADV_DONTNEED\fR semantics found in Linux, upon which some programs +have (regretably) come to depend. In de novo applications, +\fBMADV_PURGE\fR should be avoided; \fBMADV_FREE\fR should always be +preferred. +.RE + +.sp +.ne 2 +.na \fB\fBMADV_ACCESS_LWP\fR\fR .ad .RS 23n diff --git a/usr/src/man/man3c/priv_addset.3c b/usr/src/man/man3c/priv_addset.3c index 7537cacde6..a695b87bcc 100644 --- a/usr/src/man/man3c/priv_addset.3c +++ b/usr/src/man/man3c/priv_addset.3c @@ -6,8 +6,9 @@ .TH PRIV_ADDSET 3C "Jan 28, 2005" .SH NAME priv_addset, priv_allocset, priv_copyset, priv_delset, priv_emptyset, -priv_fillset, priv_freeset, priv_intersect, priv_inverse, priv_isemptyset, -priv_isequalset, priv_isfullset, priv_ismember, priv_issubset, priv_union \- +priv_basicset, priv_fillset, priv_freeset, priv_intersect, priv_inverse, +priv_isemptyset, priv_isequalset, priv_isfullset, priv_ismember, +priv_issubset, priv_union \- privilege set manipulation functions .SH SYNOPSIS .LP @@ -39,6 +40,11 @@ privilege set manipulation functions .LP .nf +\fBvoid\fR \fBpriv_basicset\fR(\fBpriv_set_t *\fR\fIsp\fR); +.fi + +.LP +.nf \fBvoid\fR \fBpriv_fillset\fR(\fBpriv_set_t *\fR\fIsp\fR); .fi @@ -114,6 +120,9 @@ The \fBpriv_delset()\fR function removes the named privilege \fIpriv\fR from The \fBpriv_emptyset()\fR function clears all privileges from \fIsp\fR. .sp .LP +The \fBpriv_basicset()\fR function copies the basic privilege set to \fIsp\fR. +.sp +.LP The \fBpriv_fillset()\fR function asserts all privileges in \fIsp\fR, including the privileges not currently defined in the system. .sp diff --git a/usr/src/man/man3c/psignal.3c b/usr/src/man/man3c/psignal.3c index 655dedb022..a977fb6df4 100644 --- a/usr/src/man/man3c/psignal.3c +++ b/usr/src/man/man3c/psignal.3c @@ -1,16 +1,17 @@ '\" te .\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. .\" Copyright 2015 Circonus, Inc. All rights reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PSIGNAL 3C "Mar 31, 2005" +.TH PSIGNAL 3C "Aug 14, 2014" .SH NAME psignal, psiginfo \- system signal messages .SH SYNOPSIS .LP .nf -#include <siginfo.h> +#include <signal.h> \fBvoid\fR \fBpsignal\fR(\fBint\fR \fIsig\fR, \fBconst char *\fR\fIs\fR); .fi @@ -28,7 +29,9 @@ that may have been passed as the first argument to a signal handler. The \fIpinfo\fR argument is a pointer to a \fBsiginfo\fR structure that may have been passed as the second argument to an enhanced signal handler. See \fBsigaction\fR(2). The argument string \fIs\fR is printed first, followed by a -colon and a blank, followed by the message and a \fBNEWLINE\fR character. +colon and a blank, followed by the message and a \fBNEWLINE\fR character. If +\fBs\fR is the value \fBNULL\fR or an empty string, then nothing is printed for +the user's string and the colon and blank are omitted. .SH USAGE .LP Messages printed from these functions are in the native language specified by diff --git a/usr/src/man/man3c/signalfd.3c b/usr/src/man/man3c/signalfd.3c new file mode 100644 index 0000000000..43699a50a5 --- /dev/null +++ b/usr/src/man/man3c/signalfd.3c @@ -0,0 +1,192 @@ +.\" +.\" 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 2015, Joyent, Inc. +.\" +.Dd "Jun 15, 2015" +.Dt SIGNALFD 3C +.Os +.Sh NAME +.Nm signalfd +.Nd create or modify a file descriptor for signal handling +.Sh SYNOPSIS +.In sys/signalfd.h +. +.Ft int +.Fo signalfd +.Fa "int fd" +.Fa "const sigset_t *mask" +.Fa "int flags" +.Fc +. +.Sh DESCRIPTION +The +.Fn signalfd +function returns a file descriptor that can be used +for synchronous consumption of signals. The file descriptor can be operated +upon via +.Xr read 2 +and the facilities that notify of file descriptor activity (e.g. +.Xr poll 2 , +.Xr port_get 3C , +.Xr epoll_wait 3C +). To dispose of the instance +.Xr close 2 +should be called on the file descriptor. +.Pp +If the +.Va fd +argument is -1, a new signalfd file descriptor will be +returned, otherwise the +.Va fd +argument should be an existing signalfd file descriptor whose signal mask will +be updated. +.Pp +The +.Va mask +argument specifies the set of signals that are relevant to the file descriptor. +It may be manipulated with the standard signal set manipulation functions +documented in +.Xr sigsetops 3C . +Signals in the mask which cannot be caught (e.g. +.Fa SIGKILL ) +are ignored. +.Pp +The +.Va flags +argument specifies additional parameters for the instance, and can have any of +the following values: +.Bl -tag -width Dv +.It Sy SFD_CLOEXEC +Instance will be closed upon an +.Xr exec 2 ; +see description for +.Fa O_CLOEXEC +in +.Xr open 2 . +.It Sy SFD_NONBLOCK +Instance will be set to be non-blocking. A +.Xr read 2 +on a signalfd instance that has been initialized with +.Fa SFD_NONBLOCK , +or made non-blocking in other ways, will return +.Er EAGAIN +in lieu of blocking if there are no signals from the +.Va mask +that are pending. +.El +.Pp +As with +.Xr sigwait 2 , +reading a signal from the file descriptor will consume the signal. The signals +used with signalfd file descriptors are normally first blocked so that their +handler does not run when a signal arrives. If the signal is not blocked the +behavior matches that of +.Xr sigwait 2 ; +if a +.Xr read 2 +is pending then the signal is consumed by the read, otherwise the signal is +consumed by the handler. +.Pp +The following operations can be performed upon a signalfd file descriptor: +.Bl -tag -width Dv +.It Sy read(2) +Reads and consumes one or more of the pending signals that match the file +descriptor's +.Va mask . +The read buffer must be large enough to hold one or more +.Vt signalfd_siginfo +structures, which is described below. +.Xr read 2 +will block if there are no matching signals pending, or return +.Er EAGAIN +if the instance was created with +.Fa SFD_NONBLOCK . +After a +.Xr fork 2 , +if the child reads from the descriptor it will only consume signals from itself. +.It Sy poll(2) +Provide notification when one of the signals from the +.Va mask +arrives. +.Fa POLLIN +and +.Fa POLLRDNORM +will be set. +.It Sy close(2) +Closes the desriptor. +.El +.Pp +The +.Vt signalfd_siginfo +structure returned from +.Xr read 2 +is a fixed size 128 byte structure defined as follows: +.Bd -literal +typedef struct signalfd_siginfo { + uint32_t ssi_signo; /* signal from signal.h */ + int32_t ssi_errno; /* error from errno.h */ + int32_t ssi_code; /* signal code */ + uint32_t ssi_pid; /* PID of sender */ + uint32_t ssi_uid; /* real UID of sender */ + int32_t ssi_fd; /* file descriptor (SIGIO) */ + uint32_t ssi_tid; /* unused */ + uint32_t ssi_band; /* band event (SIGIO) */ + uint32_t ssi_overrun; /* unused */ + uint32_t ssi_trapno; /* trap number that caused signal */ + int32_t ssi_status; /* exit status or signal (SIGCHLD) */ + int32_t ssi_int; /* unused */ + uint64_t ssi_ptr; /* unused */ + uint64_t ssi_utime; /* user CPU time consumed (SIGCHLD) */ + uint64_t ssi_stime; /* system CPU time consumed (SIGCHLD) */ + uint64_t ssi_addr; /* address that generated signal */ + uint8_t ssi_pad[48]; /* pad size to 128 bytes */ +} signalfd_siginfo_t; +.Ed +.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. +When +.Va fd +is not -1 and there is no error, the value of +.Va fd +is returned. +.Sh ERRORS +The +.Fn signalfd function +will fail if: +.Bl -tag -width Er +.It Er EBADF +The +.Va fd +descriptor is invalid. +.It Er EFAULT +The +.Va mask +address is invalid. +.It Er EINVAL +The +.Va fd +descriptor is not a signalfd descriptor or the +.Va flags +are invalid. +.It Er EMFILE +There are currently +.Va OPEN_MAX +file descriptors open in the calling process. +.It Er ENODEV +Unable to allocate state for the file descriptor. +.El +.Sh SEE ALSO +.Xr poll 2 , +.Xr sigwait 2 , +.Xr sigsetops 3C , +.Xr sigwaitinfo 3C , +.Xr signal.h 3HEAD diff --git a/usr/src/man/man3c/timerfd_create.3c b/usr/src/man/man3c/timerfd_create.3c new file mode 100644 index 0000000000..167b905d1e --- /dev/null +++ b/usr/src/man/man3c/timerfd_create.3c @@ -0,0 +1,181 @@ +'\" 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 +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 +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 +Atomically reads and clears the number of timer expirations since the +last successful \fBread\fR(2) or \fBtimerfd_settime()\fR. 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 +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 +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 +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 +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 +Sets or disarms the timer, with the +same functional signature and semantics as \fBtimer_settime\fR(3C). +.RE + +.SH RETURN VALUES +.sp +.LP +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) + |