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. Reviewed by: kib MFC after: 3 days Differential Revision: https://reviews.freebsd.org/D7122
This commit is contained in:
parent
bcc238eaed
commit
463970da7b
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=302899
@ -24,7 +24,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd December 27, 2013
|
.Dd July 15, 2016
|
||||||
.Dt AIO_FSYNC 2
|
.Dt AIO_FSYNC 2
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -71,6 +71,29 @@ while it is in progress.
|
|||||||
.Pp
|
.Pp
|
||||||
If the request could not be enqueued (generally due to invalid arguments),
|
If the request could not be enqueued (generally due to invalid arguments),
|
||||||
the call returns without having enqueued the request.
|
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
|
.Sh RETURN VALUES
|
||||||
.Rv -std aio_fsync
|
.Rv -std aio_fsync
|
||||||
.Sh ERRORS
|
.Sh ERRORS
|
||||||
@ -80,6 +103,10 @@ system call will fail if:
|
|||||||
.Bl -tag -width Er
|
.Bl -tag -width Er
|
||||||
.It Bq Er EAGAIN
|
.It Bq Er EAGAIN
|
||||||
The request was not queued because of system resource limitations.
|
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
|
.It Bq Er ENOSYS
|
||||||
The
|
The
|
||||||
.Fn aio_fsync
|
.Fn aio_fsync
|
||||||
@ -138,6 +165,7 @@ system calls.
|
|||||||
.Xr aio_waitcomplete 2 ,
|
.Xr aio_waitcomplete 2 ,
|
||||||
.Xr aio_write 2 ,
|
.Xr aio_write 2 ,
|
||||||
.Xr fsync 2 ,
|
.Xr fsync 2 ,
|
||||||
|
.Xr sigevent 3 ,
|
||||||
.Xr siginfo 3 ,
|
.Xr siginfo 3 ,
|
||||||
.Xr aio 4
|
.Xr aio 4
|
||||||
.Sh STANDARDS
|
.Sh STANDARDS
|
||||||
|
@ -24,7 +24,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd June 3, 2013
|
.Dd July 15, 2016
|
||||||
.Dt AIO_MLOCK 2
|
.Dt AIO_MLOCK 2
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -64,6 +64,12 @@ If the request could not be enqueued (generally due to
|
|||||||
.Xr aio 4
|
.Xr aio 4
|
||||||
limits),
|
limits),
|
||||||
then the call returns without having enqueued the request.
|
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
|
.Sh RESTRICTIONS
|
||||||
The Asynchronous I/O Control Block structure pointed to by
|
The Asynchronous I/O Control Block structure pointed to by
|
||||||
.Fa iocb
|
.Fa iocb
|
||||||
@ -92,6 +98,10 @@ system call will fail if:
|
|||||||
.Bl -tag -width Er
|
.Bl -tag -width Er
|
||||||
.It Bq Er EAGAIN
|
.It Bq Er EAGAIN
|
||||||
The request was not queued because of system resource limitations.
|
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
|
.It Bq Er ENOSYS
|
||||||
The
|
The
|
||||||
.Fn aio_mlock
|
.Fn aio_mlock
|
||||||
@ -116,6 +126,7 @@ if the request was explicitly cancelled via a call to
|
|||||||
.Xr aio_error 2 ,
|
.Xr aio_error 2 ,
|
||||||
.Xr aio_return 2 ,
|
.Xr aio_return 2 ,
|
||||||
.Xr mlock 2 ,
|
.Xr mlock 2 ,
|
||||||
|
.Xr sigevent 3 ,
|
||||||
.Xr aio 4
|
.Xr aio 4
|
||||||
.Sh PORTABILITY
|
.Sh PORTABILITY
|
||||||
The
|
The
|
||||||
|
@ -24,7 +24,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd November 17, 1998
|
.Dd July 15, 2016
|
||||||
.Dt AIO_READ 2
|
.Dt AIO_READ 2
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -79,6 +79,12 @@ If the request is successfully enqueued, the value of
|
|||||||
.Fa iocb->aio_offset
|
.Fa iocb->aio_offset
|
||||||
can be modified during the request as context, so this value must
|
can be modified during the request as context, so this value must
|
||||||
not be referenced after the request is enqueued.
|
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
|
.Sh RESTRICTIONS
|
||||||
The Asynchronous I/O Control Block structure pointed to by
|
The Asynchronous I/O Control Block structure pointed to by
|
||||||
.Fa iocb
|
.Fa iocb
|
||||||
@ -115,6 +121,10 @@ system call will fail if:
|
|||||||
.Bl -tag -width Er
|
.Bl -tag -width Er
|
||||||
.It Bq Er EAGAIN
|
.It Bq Er EAGAIN
|
||||||
The request was not queued because of system resource limitations.
|
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
|
.It Bq Er ENOSYS
|
||||||
The
|
The
|
||||||
.Fn aio_read
|
.Fn aio_read
|
||||||
@ -191,6 +201,7 @@ would be invalid.
|
|||||||
.Xr aio_suspend 2 ,
|
.Xr aio_suspend 2 ,
|
||||||
.Xr aio_waitcomplete 2 ,
|
.Xr aio_waitcomplete 2 ,
|
||||||
.Xr aio_write 2 ,
|
.Xr aio_write 2 ,
|
||||||
|
.Xr sigevent 3 ,
|
||||||
.Xr siginfo 3 ,
|
.Xr siginfo 3 ,
|
||||||
.Xr aio 4
|
.Xr aio 4
|
||||||
.Sh STANDARDS
|
.Sh STANDARDS
|
||||||
|
@ -24,7 +24,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd June 2, 1999
|
.Dd July 15, 2016
|
||||||
.Dt AIO_WRITE 2
|
.Dt AIO_WRITE 2
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -85,6 +85,12 @@ If the request is successfully enqueued, the value of
|
|||||||
.Fa iocb->aio_offset
|
.Fa iocb->aio_offset
|
||||||
can be modified during the request as context, so this value must not
|
can be modified during the request as context, so this value must not
|
||||||
be referenced after the request is enqueued.
|
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
|
.Sh RESTRICTIONS
|
||||||
The Asynchronous I/O Control Block structure pointed to by
|
The Asynchronous I/O Control Block structure pointed to by
|
||||||
.Fa iocb
|
.Fa iocb
|
||||||
@ -119,6 +125,10 @@ system call will fail if:
|
|||||||
.Bl -tag -width Er
|
.Bl -tag -width Er
|
||||||
.It Bq Er EAGAIN
|
.It Bq Er EAGAIN
|
||||||
The request was not queued because of system resource limitations.
|
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
|
.It Bq Er ENOSYS
|
||||||
The
|
The
|
||||||
.Fn aio_write
|
.Fn aio_write
|
||||||
@ -186,6 +196,7 @@ would be invalid.
|
|||||||
.Xr aio_return 2 ,
|
.Xr aio_return 2 ,
|
||||||
.Xr aio_suspend 2 ,
|
.Xr aio_suspend 2 ,
|
||||||
.Xr aio_waitcomplete 2 ,
|
.Xr aio_waitcomplete 2 ,
|
||||||
|
.Xr sigevent 3 ,
|
||||||
.Xr siginfo 3 ,
|
.Xr siginfo 3 ,
|
||||||
.Xr aio 4
|
.Xr aio 4
|
||||||
.Sh STANDARDS
|
.Sh STANDARDS
|
||||||
|
@ -24,7 +24,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd January 12, 2003
|
.Dd July 15, 2016
|
||||||
.Dt LIO_LISTIO 2
|
.Dt LIO_LISTIO 2
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -83,14 +83,52 @@ If
|
|||||||
.Fa mode
|
.Fa mode
|
||||||
is
|
is
|
||||||
.Dv LIO_NOWAIT ,
|
.Dv LIO_NOWAIT ,
|
||||||
the requests are processed asynchronously, and the signal specified by
|
|
||||||
.Fa sig
|
.Fa sig
|
||||||
is sent when all operations have completed.
|
can be used to request asynchronous notification when all operations have
|
||||||
|
completed.
|
||||||
If
|
If
|
||||||
.Fa sig
|
.Fa sig
|
||||||
is
|
is
|
||||||
.Dv NULL ,
|
.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
|
.Pp
|
||||||
The order in which the requests are carried out is not specified;
|
The order in which the requests are carried out is not specified;
|
||||||
in particular, there is no guarantee that they will be executed in
|
in particular, there is no guarantee that they will be executed in
|
||||||
@ -136,6 +174,10 @@ or
|
|||||||
.Fa nent
|
.Fa nent
|
||||||
is greater than
|
is greater than
|
||||||
.Dv AIO_LISTIO_MAX .
|
.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
|
.It Bq Er EINTR
|
||||||
A signal interrupted the system call before it could be completed.
|
A signal interrupted the system call before it could be completed.
|
||||||
.It Bq Er EIO
|
.It Bq Er EIO
|
||||||
@ -166,6 +208,7 @@ structure individually by calling
|
|||||||
.Xr aio_write 2 ,
|
.Xr aio_write 2 ,
|
||||||
.Xr read 2 ,
|
.Xr read 2 ,
|
||||||
.Xr write 2 ,
|
.Xr write 2 ,
|
||||||
|
.Xr sigevent 3 ,
|
||||||
.Xr siginfo 3 ,
|
.Xr siginfo 3 ,
|
||||||
.Xr aio 4
|
.Xr aio 4
|
||||||
.Sh STANDARDS
|
.Sh STANDARDS
|
||||||
|
@ -37,7 +37,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd November 29, 2005
|
.Dd July 15, 2016
|
||||||
.Dt MQ_NOTIFY 2
|
.Dt MQ_NOTIFY 2
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -77,18 +77,27 @@ is
|
|||||||
.Dv SIGEV_NONE ,
|
.Dv SIGEV_NONE ,
|
||||||
then no signal will be posted, but the error status and the return status
|
then no signal will be posted, but the error status and the return status
|
||||||
for the operation will be set appropriately.
|
for the operation will be set appropriately.
|
||||||
If
|
For
|
||||||
.Fa notification->sigev_notify
|
.Dv SIGEV_SIGNO
|
||||||
is
|
and
|
||||||
.Dv SIGEV_SIGNAL ,
|
.Dv SIGEV_THREAD_ID
|
||||||
then the signal specified in
|
notifications,
|
||||||
|
the signal specified in
|
||||||
.Fa notification->sigev_signo
|
.Fa notification->sigev_signo
|
||||||
will be sent to the process.
|
will be sent to the calling process
|
||||||
The signal will be queued to the process and the value specified in
|
.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
|
.Fa notification->sigev_value
|
||||||
will be the
|
.It Va si_mqd Ta Fa mqdes
|
||||||
.Va si_value
|
.El
|
||||||
component of the generated signal.
|
|
||||||
.Pp
|
.Pp
|
||||||
If
|
If
|
||||||
.Fa notification
|
.Fa notification
|
||||||
@ -123,11 +132,16 @@ The
|
|||||||
argument is not a valid message queue descriptor.
|
argument is not a valid message queue descriptor.
|
||||||
.It Bq Er EBUSY
|
.It Bq Er EBUSY
|
||||||
Process is already registered for notification by the message queue.
|
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
|
.El
|
||||||
.Sh SEE ALSO
|
.Sh SEE ALSO
|
||||||
.Xr mq_open 2 ,
|
.Xr mq_open 2 ,
|
||||||
.Xr mq_send 2 ,
|
.Xr mq_send 2 ,
|
||||||
.Xr mq_timedsend 2 ,
|
.Xr mq_timedsend 2 ,
|
||||||
|
.Xr sigevent 3 ,
|
||||||
.Xr siginfo 3
|
.Xr siginfo 3
|
||||||
.Sh STANDARDS
|
.Sh STANDARDS
|
||||||
The
|
The
|
||||||
|
@ -27,7 +27,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd January 12, 2009
|
.Dd July 15, 2016
|
||||||
.Dt TIMER_CREATE 2
|
.Dt TIMER_CREATE 2
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -74,6 +74,36 @@ structure.
|
|||||||
This structure,
|
This structure,
|
||||||
allocated by the application, defines the asynchronous notification to occur
|
allocated by the application, defines the asynchronous notification to occur
|
||||||
when the timer expires.
|
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
|
If the
|
||||||
.Fa evp
|
.Fa evp
|
||||||
argument is
|
argument is
|
||||||
@ -88,12 +118,14 @@ member having the value
|
|||||||
.Dv SIGEV_SIGNAL ,
|
.Dv SIGEV_SIGNAL ,
|
||||||
the
|
the
|
||||||
.Va sigev_signo
|
.Va sigev_signo
|
||||||
having a default signal number, and the
|
having a default signal number
|
||||||
|
.Pq Dv SIGALRM ,
|
||||||
|
and the
|
||||||
.Va sigev_value
|
.Va sigev_value
|
||||||
member having
|
member having
|
||||||
the value of the timer ID.
|
the value of the timer ID.
|
||||||
.Pp
|
.Pp
|
||||||
The implementations supports a
|
This implementation supports a
|
||||||
.Fa clock_id
|
.Fa clock_id
|
||||||
of
|
of
|
||||||
.Dv CLOCK_REALTIME
|
.Dv CLOCK_REALTIME
|
||||||
@ -144,6 +176,8 @@ The calling process has already created all of the timers it is allowed by
|
|||||||
this implementation.
|
this implementation.
|
||||||
.It Bq Er EINVAL
|
.It Bq Er EINVAL
|
||||||
The specified clock ID is not supported.
|
The specified clock ID is not supported.
|
||||||
|
.It Bq Er EINVAL
|
||||||
|
The specified asynchronous notification method is not supported.
|
||||||
.It Bq Er EFAULT
|
.It Bq Er EFAULT
|
||||||
Any arguments point outside the allocated address space or there is a
|
Any arguments point outside the allocated address space or there is a
|
||||||
memory protection fault.
|
memory protection fault.
|
||||||
@ -152,6 +186,7 @@ memory protection fault.
|
|||||||
.Xr clock_getres 2 ,
|
.Xr clock_getres 2 ,
|
||||||
.Xr timer_delete 2 ,
|
.Xr timer_delete 2 ,
|
||||||
.Xr timer_getoverrun 2 ,
|
.Xr timer_getoverrun 2 ,
|
||||||
|
.Xr sigevent 3 ,
|
||||||
.Xr siginfo 3
|
.Xr siginfo 3
|
||||||
.Sh STANDARDS
|
.Sh STANDARDS
|
||||||
The
|
The
|
||||||
|
@ -15,6 +15,7 @@ MAN= assert.3 \
|
|||||||
offsetof.3 \
|
offsetof.3 \
|
||||||
${PTHREAD_MAN} \
|
${PTHREAD_MAN} \
|
||||||
queue.3 \
|
queue.3 \
|
||||||
|
sigevent.3 \
|
||||||
siginfo.3 \
|
siginfo.3 \
|
||||||
stdarg.3 \
|
stdarg.3 \
|
||||||
sysexits.3 \
|
sysexits.3 \
|
||||||
|
127
share/man/man3/sigevent.3
Normal file
127
share/man/man3/sigevent.3
Normal file
@ -0,0 +1,127 @@
|
|||||||
|
.\" -*- nroff -*-
|
||||||
|
.\"
|
||||||
|
.\" Copyright (c) 2016 John H. Baldwin <jhb@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 .
|
@ -27,7 +27,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd March 1, 2016
|
.Dd July 15, 2016
|
||||||
.Dt AIO 4
|
.Dt AIO 4
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -137,6 +137,54 @@ The number of outstanding asynchronous I/O requests system-wide.
|
|||||||
The maximum number of outstanding asynchronous I/O requests permitted
|
The maximum number of outstanding asynchronous I/O requests permitted
|
||||||
system-wide.
|
system-wide.
|
||||||
.El
|
.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
|
.Sh SEE ALSO
|
||||||
.Xr aio_cancel 2 ,
|
.Xr aio_cancel 2 ,
|
||||||
.Xr aio_error 2 ,
|
.Xr aio_error 2 ,
|
||||||
@ -146,6 +194,7 @@ system-wide.
|
|||||||
.Xr aio_waitcomplete 2 ,
|
.Xr aio_waitcomplete 2 ,
|
||||||
.Xr aio_write 2 ,
|
.Xr aio_write 2 ,
|
||||||
.Xr lio_listio 2 ,
|
.Xr lio_listio 2 ,
|
||||||
|
.Xr sigevent 3 ,
|
||||||
.Xr sysctl 8
|
.Xr sysctl 8
|
||||||
.Sh HISTORY
|
.Sh HISTORY
|
||||||
The
|
The
|
||||||
|
Loading…
Reference in New Issue
Block a user