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)

7 files changed, 175 insertions, 22 deletions

diff --git a/lib/libc/sys/aio_fsync.2 b/lib/libc/sys/aio_fsync.2
index e05bff4..7eb1a3b 100644
--- a/lib/libc/sys/aio_fsync.2
+++ b/lib/libc/sys/aio_fsync.2
@@ -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
diff --git a/lib/libc/sys/aio_mlock.2 b/lib/libc/sys/aio_mlock.2
index 95055e8..c798a37 100644
--- a/lib/libc/sys/aio_mlock.2
+++ b/lib/libc/sys/aio_mlock.2
@@ -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 (generally due to
 .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 via a call to
 .Xr aio_error 2 ,
 .Xr aio_return 2 ,
 .Xr mlock 2 ,
+.Xr sigevent 3 ,
 .Xr aio 4
 .Sh PORTABILITY
 The
diff --git a/lib/libc/sys/aio_read.2 b/lib/libc/sys/aio_read.2
index 65b5e10..cc0133b 100644
--- a/lib/libc/sys/aio_read.2
+++ b/lib/libc/sys/aio_read.2
@@ -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, the value of
 .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
diff --git a/lib/libc/sys/aio_write.2 b/lib/libc/sys/aio_write.2
index 080a6b8..6cbc2ab 100644
--- a/lib/libc/sys/aio_write.2
+++ b/lib/libc/sys/aio_write.2
@@ -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, the value of
 .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
diff --git a/lib/libc/sys/lio_listio.2 b/lib/libc/sys/lio_listio.2
index 0ffbcdd..ae228f7 100644
--- a/lib/libc/sys/lio_listio.2
+++ b/lib/libc/sys/lio_listio.2
@@ -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
diff --git a/lib/libc/sys/mq_notify.2 b/lib/libc/sys/mq_notify.2
index 1e3a5ad..4418c60 100644
--- a/lib/libc/sys/mq_notify.2
+++ b/lib/libc/sys/mq_notify.2
@@ -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
diff --git a/lib/libc/sys/timer_create.2 b/lib/libc/sys/timer_create.2
index 3355159..1dd0cd5 100644
--- a/lib/libc/sys/timer_create.2
+++ b/lib/libc/sys/timer_create.2
@@ -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 all of the timers it is allowed by
 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