svn commit: r303324 - in stable/11: lib/libc/sys share/man/man3 share/man/man4
John Baldwin
jhb at FreeBSD.org
Mon Jul 25 23:37:49 UTC 2016
Author: jhb
Date: Mon Jul 25 23:37:47 2016
New Revision: 303324
URL: https://svnweb.freebsd.org/changeset/base/303324
Log:
MFC 302899: Add documentation for the sigevent structure.
- Add a sigevent(3) manpage to give a general overview of the sigevent
structure and the available notification mechanisms.
- Document that AIO requests contain a nested sigevent structure that can
be used to request completion notification.
- Expand the sigevent details in other manuals to note details such as
the extra values stored in a queued signal's information or in a posted
kevent.
Approved by: re (gjb)
Added:
stable/11/share/man/man3/sigevent.3
- copied unchanged from r302899, head/share/man/man3/sigevent.3
Modified:
stable/11/lib/libc/sys/aio_fsync.2
stable/11/lib/libc/sys/aio_mlock.2
stable/11/lib/libc/sys/aio_read.2
stable/11/lib/libc/sys/aio_write.2
stable/11/lib/libc/sys/lio_listio.2
stable/11/lib/libc/sys/mq_notify.2
stable/11/lib/libc/sys/timer_create.2
stable/11/share/man/man3/Makefile
stable/11/share/man/man4/aio.4
Directory Properties:
stable/11/ (props changed)
Modified: stable/11/lib/libc/sys/aio_fsync.2
==============================================================================
--- stable/11/lib/libc/sys/aio_fsync.2 Mon Jul 25 23:06:37 2016 (r303323)
+++ stable/11/lib/libc/sys/aio_fsync.2 Mon Jul 25 23:37:47 2016 (r303324)
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd December 27, 2013
+.Dd July 15, 2016
.Dt AIO_FSYNC 2
.Os
.Sh NAME
@@ -71,6 +71,29 @@ while it is in progress.
.Pp
If the request could not be enqueued (generally due to invalid arguments),
the call returns without having enqueued the request.
+.Pp
+The
+.Fa iocb->aio_sigevent
+structure can be used to request notification of the request's
+completion as described in
+.Xr aio 4 .
+.Sh RESTRICTIONS
+The asynchronous I/O Control Block structure pointed to by
+.Fa iocb
+must remain valid until the
+operation has completed.
+For this reason, use of auto (stack) variables
+for these objects is discouraged.
+.Pp
+The asynchronous I/O control buffer
+.Fa iocb
+should be zeroed before the
+.Fn aio_fsync
+call to avoid passing bogus context information to the kernel.
+.Pp
+Modifications of the Asynchronous I/O Control Block structure or the
+buffer contents after the request has been enqueued, but before the
+request has completed, are not allowed.
.Sh RETURN VALUES
.Rv -std aio_fsync
.Sh ERRORS
@@ -80,6 +103,10 @@ system call will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
The request was not queued because of system resource limitations.
+.It Bq Er EINVAL
+The asynchronous notification method in
+.Fa iocb->aio_sigevent.sigev_notify
+is invalid or not supported.
.It Bq Er ENOSYS
The
.Fn aio_fsync
@@ -138,6 +165,7 @@ system calls.
.Xr aio_waitcomplete 2 ,
.Xr aio_write 2 ,
.Xr fsync 2 ,
+.Xr sigevent 3 ,
.Xr siginfo 3 ,
.Xr aio 4
.Sh STANDARDS
Modified: stable/11/lib/libc/sys/aio_mlock.2
==============================================================================
--- stable/11/lib/libc/sys/aio_mlock.2 Mon Jul 25 23:06:37 2016 (r303323)
+++ stable/11/lib/libc/sys/aio_mlock.2 Mon Jul 25 23:37:47 2016 (r303324)
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd June 3, 2013
+.Dd July 15, 2016
.Dt AIO_MLOCK 2
.Os
.Sh NAME
@@ -64,6 +64,12 @@ If the request could not be enqueued (ge
.Xr aio 4
limits),
then the call returns without having enqueued the request.
+.Pp
+The
+.Fa iocb->aio_sigevent
+structure can be used to request notification of the request's
+completion as described in
+.Xr aio 4 .
.Sh RESTRICTIONS
The Asynchronous I/O Control Block structure pointed to by
.Fa iocb
@@ -92,6 +98,10 @@ system call will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
The request was not queued because of system resource limitations.
+.It Bq Er EINVAL
+The asynchronous notification method in
+.Fa iocb->aio_sigevent.sigev_notify
+is invalid or not supported.
.It Bq Er ENOSYS
The
.Fn aio_mlock
@@ -116,6 +126,7 @@ if the request was explicitly cancelled
.Xr aio_error 2 ,
.Xr aio_return 2 ,
.Xr mlock 2 ,
+.Xr sigevent 3 ,
.Xr aio 4
.Sh PORTABILITY
The
Modified: stable/11/lib/libc/sys/aio_read.2
==============================================================================
--- stable/11/lib/libc/sys/aio_read.2 Mon Jul 25 23:06:37 2016 (r303323)
+++ stable/11/lib/libc/sys/aio_read.2 Mon Jul 25 23:37:47 2016 (r303324)
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd November 17, 1998
+.Dd July 15, 2016
.Dt AIO_READ 2
.Os
.Sh NAME
@@ -79,6 +79,12 @@ If the request is successfully enqueued,
.Fa iocb->aio_offset
can be modified during the request as context, so this value must
not be referenced after the request is enqueued.
+.Pp
+The
+.Fa iocb->aio_sigevent
+structure can be used to request notification of the request's
+completion as described in
+.Xr aio 4 .
.Sh RESTRICTIONS
The Asynchronous I/O Control Block structure pointed to by
.Fa iocb
@@ -115,6 +121,10 @@ system call will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
The request was not queued because of system resource limitations.
+.It Bq Er EINVAL
+The asynchronous notification method in
+.Fa iocb->aio_sigevent.sigev_notify
+is invalid or not supported.
.It Bq Er ENOSYS
The
.Fn aio_read
@@ -191,6 +201,7 @@ would be invalid.
.Xr aio_suspend 2 ,
.Xr aio_waitcomplete 2 ,
.Xr aio_write 2 ,
+.Xr sigevent 3 ,
.Xr siginfo 3 ,
.Xr aio 4
.Sh STANDARDS
Modified: stable/11/lib/libc/sys/aio_write.2
==============================================================================
--- stable/11/lib/libc/sys/aio_write.2 Mon Jul 25 23:06:37 2016 (r303323)
+++ stable/11/lib/libc/sys/aio_write.2 Mon Jul 25 23:37:47 2016 (r303324)
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd June 2, 1999
+.Dd July 15, 2016
.Dt AIO_WRITE 2
.Os
.Sh NAME
@@ -85,6 +85,12 @@ If the request is successfully enqueued,
.Fa iocb->aio_offset
can be modified during the request as context, so this value must not
be referenced after the request is enqueued.
+.Pp
+The
+.Fa iocb->aio_sigevent
+structure can be used to request notification of the request's
+completion as described in
+.Xr aio 4 .
.Sh RESTRICTIONS
The Asynchronous I/O Control Block structure pointed to by
.Fa iocb
@@ -119,6 +125,10 @@ system call will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
The request was not queued because of system resource limitations.
+.It Bq Er EINVAL
+The asynchronous notification method in
+.Fa iocb->aio_sigevent.sigev_notify
+is invalid or not supported.
.It Bq Er ENOSYS
The
.Fn aio_write
@@ -186,6 +196,7 @@ would be invalid.
.Xr aio_return 2 ,
.Xr aio_suspend 2 ,
.Xr aio_waitcomplete 2 ,
+.Xr sigevent 3 ,
.Xr siginfo 3 ,
.Xr aio 4
.Sh STANDARDS
Modified: stable/11/lib/libc/sys/lio_listio.2
==============================================================================
--- stable/11/lib/libc/sys/lio_listio.2 Mon Jul 25 23:06:37 2016 (r303323)
+++ stable/11/lib/libc/sys/lio_listio.2 Mon Jul 25 23:37:47 2016 (r303324)
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd January 12, 2003
+.Dd July 15, 2016
.Dt LIO_LISTIO 2
.Os
.Sh NAME
@@ -83,14 +83,52 @@ If
.Fa mode
is
.Dv LIO_NOWAIT ,
-the requests are processed asynchronously, and the signal specified by
.Fa sig
-is sent when all operations have completed.
+can be used to request asynchronous notification when all operations have
+completed.
If
.Fa sig
is
.Dv NULL ,
-the calling process is not notified of I/O completion.
+no notification is sent.
+.Pp
+For
+.Dv SIGEV_KEVENT
+notifications,
+the posted kevent will contain:
+.Bl -column ".Va filter"
+.It Sy Member Ta Sy Value
+.It Va ident Ta Fa list
+.It Va filter Ta Dv EVFILT_LIO
+.It Va udata Ta
+value stored in
+.Fa sig->sigev_value
+.El
+.Pp
+For
+.Dv SIGEV_SIGNO
+and
+.Dv SIGEV_THREAD_ID
+notifications,
+the information for the queued signal will include
+.Dv SI_ASYNCIO
+in the
+.Va si_code
+field and the value stored in
+.Fa sig->sigev_value
+in the
+.Va si_value
+field.
+.Pp
+For
+.Dv SIGEV_THREAD
+notifications,
+the value stored in
+.Fa sig->sigev_value
+is passed to the
+.Fa sig->sigev_notify_function
+as described in
+.Xr sigevent 3 .
.Pp
The order in which the requests are carried out is not specified;
in particular, there is no guarantee that they will be executed in
@@ -136,6 +174,10 @@ or
.Fa nent
is greater than
.Dv AIO_LISTIO_MAX .
+.It Bq Er EINVAL
+The asynchronous notification method in
+.Fa sig->sigev_notify
+is invalid or not supported.
.It Bq Er EINTR
A signal interrupted the system call before it could be completed.
.It Bq Er EIO
@@ -166,6 +208,7 @@ structure individually by calling
.Xr aio_write 2 ,
.Xr read 2 ,
.Xr write 2 ,
+.Xr sigevent 3 ,
.Xr siginfo 3 ,
.Xr aio 4
.Sh STANDARDS
Modified: stable/11/lib/libc/sys/mq_notify.2
==============================================================================
--- stable/11/lib/libc/sys/mq_notify.2 Mon Jul 25 23:06:37 2016 (r303323)
+++ stable/11/lib/libc/sys/mq_notify.2 Mon Jul 25 23:37:47 2016 (r303324)
@@ -37,7 +37,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd November 29, 2005
+.Dd July 15, 2016
.Dt MQ_NOTIFY 2
.Os
.Sh NAME
@@ -77,18 +77,27 @@ is
.Dv SIGEV_NONE ,
then no signal will be posted, but the error status and the return status
for the operation will be set appropriately.
-If
-.Fa notification->sigev_notify
-is
-.Dv SIGEV_SIGNAL ,
-then the signal specified in
+For
+.Dv SIGEV_SIGNO
+and
+.Dv SIGEV_THREAD_ID
+notifications,
+the signal specified in
.Fa notification->sigev_signo
-will be sent to the process.
-The signal will be queued to the process and the value specified in
+will be sent to the calling process
+.Pq Dv SIGEV_SIGNO
+or to the thread whose LWP ID is
+.Fa notification->sigev_notify_thread_id
+.Pq Dv SIGEV_THREAD_ID .
+The information for the queued signal will include:
+.Bl -column ".Va si_value"
+.It Sy Member Ta Sy Value
+.It Va si_code Ta Dv SI_MESGQ
+.It Va si_value Ta
+the value stored in
.Fa notification->sigev_value
-will be the
-.Va si_value
-component of the generated signal.
+.It Va si_mqd Ta Fa mqdes
+.El
.Pp
If
.Fa notification
@@ -123,11 +132,16 @@ The
argument is not a valid message queue descriptor.
.It Bq Er EBUSY
Process is already registered for notification by the message queue.
+.It Bq Er EINVAL
+The asynchronous notification method in
+.Fa notification->sigev_notify
+is invalid or not supported.
.El
.Sh SEE ALSO
.Xr mq_open 2 ,
.Xr mq_send 2 ,
.Xr mq_timedsend 2 ,
+.Xr sigevent 3 ,
.Xr siginfo 3
.Sh STANDARDS
The
Modified: stable/11/lib/libc/sys/timer_create.2
==============================================================================
--- stable/11/lib/libc/sys/timer_create.2 Mon Jul 25 23:06:37 2016 (r303323)
+++ stable/11/lib/libc/sys/timer_create.2 Mon Jul 25 23:37:47 2016 (r303324)
@@ -27,7 +27,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd January 12, 2009
+.Dd July 15, 2016
.Dt TIMER_CREATE 2
.Os
.Sh NAME
@@ -74,6 +74,36 @@ structure.
This structure,
allocated by the application, defines the asynchronous notification to occur
when the timer expires.
+.Pp
+If
+.Fa evp->sigev_notify
+is
+.Dv SIGEV_SIGNO
+or
+.Dv SIGEV_THREAD_ID ,
+the signal specified in
+.Fa evp->sigev_signo
+will be sent to the calling process
+.Pq Dv SIGEV_SIGNO
+or to the thread whose LWP ID is
+.Fa evp->sigev_notify_thread_id
+.Pq Dv SIGEV_THREAD_ID .
+The information for the queued signal will include:
+.Bl -column ".Va si_value"
+.It Sy Member Ta Sy Value
+.It Va si_code Ta Dv SI_TIMER
+.It Va si_value Ta
+the value stored in
+.Fa evp->sigev_value
+.It Va si_timerid Ta timer ID
+.It Va si_overrun Ta timer overrun count
+.It Va si_errno Ta
+If timer overrun is
+.Brq Dv DELAYTIMER_MAX ,
+an error code defined in
+.In errno.h
+.El
+.Pp
If the
.Fa evp
argument is
@@ -88,12 +118,14 @@ member having the value
.Dv SIGEV_SIGNAL ,
the
.Va sigev_signo
-having a default signal number, and the
+having a default signal number
+.Pq Dv SIGALRM ,
+and the
.Va sigev_value
member having
the value of the timer ID.
.Pp
-The implementations supports a
+This implementation supports a
.Fa clock_id
of
.Dv CLOCK_REALTIME
@@ -144,6 +176,8 @@ The calling process has already created
this implementation.
.It Bq Er EINVAL
The specified clock ID is not supported.
+.It Bq Er EINVAL
+The specified asynchronous notification method is not supported.
.It Bq Er EFAULT
Any arguments point outside the allocated address space or there is a
memory protection fault.
@@ -152,6 +186,7 @@ memory protection fault.
.Xr clock_getres 2 ,
.Xr timer_delete 2 ,
.Xr timer_getoverrun 2 ,
+.Xr sigevent 3 ,
.Xr siginfo 3
.Sh STANDARDS
The
Modified: stable/11/share/man/man3/Makefile
==============================================================================
--- stable/11/share/man/man3/Makefile Mon Jul 25 23:06:37 2016 (r303323)
+++ stable/11/share/man/man3/Makefile Mon Jul 25 23:37:47 2016 (r303324)
@@ -15,6 +15,7 @@ MAN= assert.3 \
offsetof.3 \
${PTHREAD_MAN} \
queue.3 \
+ sigevent.3 \
siginfo.3 \
stdarg.3 \
sysexits.3 \
Copied: stable/11/share/man/man3/sigevent.3 (from r302899, head/share/man/man3/sigevent.3)
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ stable/11/share/man/man3/sigevent.3 Mon Jul 25 23:37:47 2016 (r303324, copy of r302899, head/share/man/man3/sigevent.3)
@@ -0,0 +1,127 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2016 John H. Baldwin <jhb at FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 15, 2016
+.Dt SIGEVENT 3
+.Os
+.Sh NAME
+.Nm sigevent
+.Nd "asynchronous event notification"
+.Sh SYNOPSIS
+.In signal.h
+.Sh DESCRIPTION
+Some operations permit threads to request asychronous notification of events
+via a
+.Vt struct sigevent
+structure.
+This structure contains several fields that describe the requested notification:
+.Bl -column ".Vt void (*)(union sigval)" ".Va sigev_notify_kevent_flags"
+.It Sy Type Ta Sy Member Ta Sy Description
+.It Vt int Ta sigev_notify Ta notification method
+.It Vt int Ta sigev_signo Ta signal number
+.It Vt union sigval Ta sigev_value Ta signal value
+.It Vt int Ta sigev_notify_kqueue Ta
+.Xr kqueue 2
+file descriptor
+.It Vt unsigned short Ta sigev_notify_kevent_flags Ta kevent flags
+.It Vt lwpid_t Ta sigev_notify_thread_id Ta LWP ID
+.It Vt void (*)(union sigval) Ta sigev_notify_function Ta
+callback function pointer
+.It Vt pthread_attr_t * Ta sigev_notify_attributes Ta
+callback thread attributes
+.El
+.Pp
+The
+.Va sigev_notify
+field specifies the notification method used when the event triggers:
+.Bl -tag -width ".Dv SIGEV_THREAD_ID"
+.It Dv SIGEV_NONE
+No notification is sent.
+.It Dv SIGEV_SIGNAL
+The signal
+.Va sigev_signo
+is queued as a real-time signal to the calling process.
+The value stored in
+.Va sigev_value
+will be present in the
+.Va si_value
+of the
+.Vt siginfo_t
+structure of the queued signal.
+.It Dv SIGEV_THREAD
+The notification function in
+.Va sigev_notify_function
+is called in a separate thread context.
+The thread is created with the attributes specified in
+.Va *sigev_notify_attributes .
+The value stored in
+.Va sigev_value
+is passed as the sole argument to
+.Va sigev_notify_function .
+If
+.Va sigev_notify_attributes
+is
+.Dv NULL ,
+the thread is created with default attributes.
+.It Dv SIGEV_KEVENT
+A new kevent is posted to the kqueue
+.Va sigev_notify_kqueue .
+The
+.Va udata
+member of the kevent structure contains the value stored in
+.Va sigev_value .
+The meaning of other fields in the kevent are specific to the type of triggered
+event.
+.It Dv SIGEV_THREAD_ID
+The signal
+.Va sigev_signo
+is queued to the thread whose LWP ID is
+.Va sigev_notify_thread_id .
+The value stored in
+.Va sigev_value
+will be present in the
+.Va si_value
+of the
+.Vt siginfo_t
+structure of the queued signal.
+.El
+.Sh NOTES
+Note that programs wishing to use
+.Dv SIGEV_THREAD
+notifications must link against the
+.Lb librt .
+.Sh SEE ALSO
+.Xr aio_read 2 ,
+.Xr mq_notify 2 ,
+.Xr timer_create 2 ,
+.Xr siginfo 3
+.Sh STANDARDS
+The
+.Vt struct sigevent
+type conforms to
+.St -p1003.1-2004 .
Modified: stable/11/share/man/man4/aio.4
==============================================================================
--- stable/11/share/man/man4/aio.4 Mon Jul 25 23:06:37 2016 (r303323)
+++ stable/11/share/man/man4/aio.4 Mon Jul 25 23:37:47 2016 (r303324)
@@ -27,7 +27,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd March 1, 2016
+.Dd July 15, 2016
.Dt AIO 4
.Os
.Sh NAME
@@ -137,6 +137,54 @@ The number of outstanding asynchronous I
The maximum number of outstanding asynchronous I/O requests permitted
system-wide.
.El
+.Pp
+Asynchronous I/O control buffers should be zeroed before initializing
+individual fields.
+This ensures all fields are initialized.
+.Pp
+All asynchronous I/O control buffers contain a
+.Vt sigevent
+structure in the
+.Va aio_sigevent
+field which can be used to request notification when an operation completes.
+.Pp
+For
+.Dv SIGEV_KEVENT
+notifications,
+the posted kevent will contain:
+.Bl -column ".Va filter"
+.It Sy Member Ta Sy Value
+.It Va ident Ta asynchronous I/O control buffer pointer
+.It Va filter Ta Dv EVFILT_AIO
+.It Va udata Ta
+value stored in
+.Va aio_sigevent.sigev_value
+.El
+.Pp
+For
+.Dv SIGEV_SIGNO
+and
+.Dv SIGEV_THREAD_ID
+notifications,
+the information for the queued signal will include
+.Dv SI_ASYNCIO
+in the
+.Va si_code
+field and the value stored in
+.Va sigevent.sigev_value
+in the
+.Va si_value
+field.
+.Pp
+For
+.Dv SIGEV_THREAD
+notifications,
+the value stored in
+.Va aio_sigevent.sigev_value
+is passed to the
+.Va aio_sigevent.sigev_notify_function
+as described in
+.Xr sigevent 3 .
.Sh SEE ALSO
.Xr aio_cancel 2 ,
.Xr aio_error 2 ,
@@ -146,6 +194,7 @@ system-wide.
.Xr aio_waitcomplete 2 ,
.Xr aio_write 2 ,
.Xr lio_listio 2 ,
+.Xr sigevent 3 ,
.Xr sysctl 8
.Sh HISTORY
The
More information about the svn-src-all
mailing list