diff options
Diffstat (limited to 'usr/src/man/man3c')
| -rw-r--r-- | usr/src/man/man3c/Makefile | 13 | ||||
| -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/eventfd.3c | 161 | ||||
| -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/psignal.3c | 13 |
9 files changed, 1005 insertions, 7 deletions
diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile index 5ed555b26a..88e1741bc2 100644 --- a/usr/src/man/man3c/Makefile +++ b/usr/src/man/man3c/Makefile @@ -14,6 +14,7 @@ # Copyright 2013 Nexenta Systems, Inc. All rights reserved. # Copyright 2013, OmniTI Computer Consulting, Inc. All rights reserved. # Copyright 2014 Garrett D'Amore <garrett@damore.org> +# Copyright (c) 2014, Joyent, Inc. All rights reserved. # include $(SRC)/Makefile.master @@ -108,8 +109,12 @@ 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 \ exit.3c \ fattach.3c \ fclose.3c \ @@ -198,6 +203,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 \ @@ -727,6 +735,8 @@ MANLINKS= FD_CLR.3c \ endusershell.3c \ endutent.3c \ endutxent.3c \ + epoll_create1.3c \ + epoll_pwait.3c \ erand48.3c \ errno.3c \ errx.3c \ @@ -1570,6 +1580,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/eventfd.3c b/usr/src/man/man3c/eventfd.3c new file mode 100644 index 0000000000..6e7d1c6a5b --- /dev/null +++ b/usr/src/man/man3c/eventfd.3c @@ -0,0 +1,161 @@ +'\" 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 EVENTFD 3C "Dec 3, 2014" +.SH NAME +eventfd \- create a file descriptor for event notification +.SH SYNOPSIS + +.LP +.nf +#include <sys/eventfd.h> + +\fBint\fR \fBeventfd\fR(\fBunsigned int\fR \fIinitval\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBeventfd()\fR function creates an \fBeventfd\fR(5) instance that +has an associated 64-bit unsigned counter. It returns a file descriptor +that can be operated upon via \fBread\fR(2), \fBwrite\fR(2) and the facilities +that notify of file descriptor activity (e.g., \fBpoll\fR(2), +\fBport_get\fR(3C), \fBepoll_wait\fR(3C)). To dispose of the instance, +\fBclose\fR(2) should be called on the file descriptor. + +The \fIinitval\fR argument specifies the +initial value of the 64-bit counter associated with the instance. (Note +that this limits the initial value to be a 32-bit quantity despite the +fact that the underlying counter is 64-bit.) + +The \fIflags\fR argument specifies additional parameters for the +instance, and can have any of the following values: + +.sp +.ne 2 +.na +\fBEFD_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 +\fBEFD_NONBLOCK\fR +.ad +.RS 12n +Instance will be set to be non-blocking. A \fBread\fR(2) on an +\fBeventfd\fR instance that has been initialized with +\fBEFD_NONBLOCK\fR will return \fBEAGAIN\fR in lieu of blocking if the +count associated with the instance is zero. +.RE + +.sp +.ne 2 +.na +\fBEFD_SEMAPHORE\fR +.ad +.RS 12n +Provide counting semaphore semantics whereby a \fBread\fR(2) will +atomically decrement rather than atomically clear the count when it +becomes non-zero. See below for details on \fBread\fR(2) semantics. +.RE + +.sp +The following operations can be performed upon an \fBeventfd\fR instance: + +.sp +.ne 2 +.na +\fBread\fR(2) +.ad +.RS 12n +Atomically reads and modifies the value of the 64-bit counter associated +with the instance. The precise semantics +of \fBread\fR(2) depend on the disposition of \fBEFD_SEMAPHORE\fR with +respect to the instance: if \fBEFD_SEMAPHORE\fR was set when the instance +was created, \fBread\fR(2) will \fIatomically decrement\fR the counter if +(and when) +it is non-zero, copying the value 1 to the eight byte buffer passed to +the system call; if \fBEFD_SEMAPHORE\fR was not set, \fBread\fR(2) will +\fIatomically clear\fR the counter if (and when) it is non-zero, copying +the former value of the counter to the eight byte buffer passed to the +system call. In either case, \fBread\fR(2) will block if the counter is +zero (or return \fBEAGAIN\fR if the instance was created with +\fBEFD_NONBLOCK\fR). 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 +\fBwrite\fR(2) +.ad +.RS 12n +Atomically adds the 64-bit value pointed to by the buffer to the 64-bit +counter associated with the instance. If the resulting value would overflow, +the \fBwrite\fR(2) will block until the value would not overflow +(or return \fBEAGAIN\fR if the instance was created with +\fBEFD_NONBLOCK\fR). If the buffer specified to \fBwrite\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 64-bit counter associated +with the instance is ready for reading or writing, as specified. +If the 64-bit value associated with the instance is non-zero, \fBPOLLIN\fR +and \fBPOLLRDNORM\fR will be set; if the value 1 can be added the value +without blocking, \fBPOLLOUT\fR and \fBPOLLWRNORM\fR will be set. +.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 \fBeventfd()\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 + +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBport_get\fR(3C), \fBepoll_wait\fR(3C), \fBeventfd\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/psignal.3c b/usr/src/man/man3c/psignal.3c index 213c45f07f..81252ee0dd 100644 --- a/usr/src/man/man3c/psignal.3c +++ b/usr/src/man/man3c/psignal.3c @@ -1,15 +1,16 @@ '\" te .\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2014, Joyent, 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 @@ -20,7 +21,6 @@ psignal, psiginfo \- system signal messages .fi .SH DESCRIPTION -.sp .LP The \fBpsignal()\fR and \fBpsiginfo()\fR functions produce messages on the standard error output describing a signal. The \fIsig\fR argument is a signal @@ -28,14 +28,14 @@ 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 -.sp .LP Messages printed from these functions are in the native language specified by the \fBLC_MESSAGES\fR locale category. See \fBsetlocale\fR(3C). .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -51,7 +51,6 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBsigaction\fR(2), \fBgettext\fR(3C), \fBperror\fR(3C), \fBsetlocale\fR(3C), \fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5) |