Date: Mon, 25 Jul 2016 23:38:14 +0000 (UTC) From: John Baldwin <jhb@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-10@freebsd.org Subject: svn commit: r303325 - in stable: 10/lib/libc/sys 10/share/man/man3 10/share/man/man4 9/lib/libc/sys 9/share/man/man3 9/share/man/man4 Message-ID: <201607252338.u6PNcErg055622@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: jhb Date: Mon Jul 25 23:38:14 2016 New Revision: 303325 URL: https://svnweb.freebsd.org/changeset/base/303325 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. Added: stable/10/share/man/man3/sigevent.3 - copied unchanged from r302899, head/share/man/man3/sigevent.3 Modified: stable/10/lib/libc/sys/aio_fsync.2 stable/10/lib/libc/sys/aio_mlock.2 stable/10/lib/libc/sys/aio_read.2 stable/10/lib/libc/sys/aio_write.2 stable/10/lib/libc/sys/lio_listio.2 stable/10/lib/libc/sys/mq_notify.2 stable/10/lib/libc/sys/timer_create.2 stable/10/share/man/man3/Makefile stable/10/share/man/man4/aio.4 Directory Properties: stable/10/ (props changed) Changes in other areas also in this revision: Added: stable/9/share/man/man3/sigevent.3 - copied unchanged from r302899, head/share/man/man3/sigevent.3 Modified: stable/9/lib/libc/sys/aio_fsync.2 stable/9/lib/libc/sys/aio_read.2 stable/9/lib/libc/sys/aio_write.2 stable/9/lib/libc/sys/lio_listio.2 stable/9/lib/libc/sys/mq_notify.2 stable/9/lib/libc/sys/timer_create.2 stable/9/share/man/man3/Makefile stable/9/share/man/man4/aio.4 Directory Properties: stable/9/lib/libc/ (props changed) stable/9/lib/libc/sys/ (props changed) stable/9/share/man/man3/ (props changed) stable/9/share/man/man4/ (props changed) Modified: stable/10/lib/libc/sys/aio_fsync.2 ============================================================================== --- stable/10/lib/libc/sys/aio_fsync.2 Mon Jul 25 23:37:47 2016 (r303324) +++ stable/10/lib/libc/sys/aio_fsync.2 Mon Jul 25 23:38:14 2016 (r303325) @@ -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/10/lib/libc/sys/aio_mlock.2 ============================================================================== --- stable/10/lib/libc/sys/aio_mlock.2 Mon Jul 25 23:37:47 2016 (r303324) +++ stable/10/lib/libc/sys/aio_mlock.2 Mon Jul 25 23:38:14 2016 (r303325) @@ -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/10/lib/libc/sys/aio_read.2 ============================================================================== --- stable/10/lib/libc/sys/aio_read.2 Mon Jul 25 23:37:47 2016 (r303324) +++ stable/10/lib/libc/sys/aio_read.2 Mon Jul 25 23:38:14 2016 (r303325) @@ -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/10/lib/libc/sys/aio_write.2 ============================================================================== --- stable/10/lib/libc/sys/aio_write.2 Mon Jul 25 23:37:47 2016 (r303324) +++ stable/10/lib/libc/sys/aio_write.2 Mon Jul 25 23:38:14 2016 (r303325) @@ -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/10/lib/libc/sys/lio_listio.2 ============================================================================== --- stable/10/lib/libc/sys/lio_listio.2 Mon Jul 25 23:37:47 2016 (r303324) +++ stable/10/lib/libc/sys/lio_listio.2 Mon Jul 25 23:38:14 2016 (r303325) @@ -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/10/lib/libc/sys/mq_notify.2 ============================================================================== --- stable/10/lib/libc/sys/mq_notify.2 Mon Jul 25 23:37:47 2016 (r303324) +++ stable/10/lib/libc/sys/mq_notify.2 Mon Jul 25 23:38:14 2016 (r303325) @@ -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/10/lib/libc/sys/timer_create.2 ============================================================================== --- stable/10/lib/libc/sys/timer_create.2 Mon Jul 25 23:37:47 2016 (r303324) +++ stable/10/lib/libc/sys/timer_create.2 Mon Jul 25 23:38:14 2016 (r303325) @@ -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/10/share/man/man3/Makefile ============================================================================== --- stable/10/share/man/man3/Makefile Mon Jul 25 23:37:47 2016 (r303324) +++ stable/10/share/man/man3/Makefile Mon Jul 25 23:38:14 2016 (r303325) @@ -13,6 +13,7 @@ MAN= assert.3 \ offsetof.3 \ ${PTHREAD_MAN} \ queue.3 \ + sigevent.3 \ siginfo.3 \ stdarg.3 \ sysexits.3 \ Copied: stable/10/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/10/share/man/man3/sigevent.3 Mon Jul 25 23:38:14 2016 (r303325, copy of r302899, head/share/man/man3/sigevent.3) @@ -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 . Modified: stable/10/share/man/man4/aio.4 ============================================================================== --- stable/10/share/man/man4/aio.4 Mon Jul 25 23:37:47 2016 (r303324) +++ stable/10/share/man/man4/aio.4 Mon Jul 25 23:38:14 2016 (r303325) @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 24, 2002 +.Dd July 15, 2016 .Dt AIO 4 .Os .Sh NAME @@ -45,6 +45,54 @@ The facility provides system calls for asynchronous I/O. It is available both as a kernel option for static inclusion and as a dynamic kernel module. +.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 , @@ -54,6 +102,7 @@ dynamic kernel module. .Xr aio_waitcomplete 2 , .Xr aio_write 2 , .Xr lio_listio 2 , +.Xr sigevent 3 , .Xr config 8 , .Xr kldload 8 , .Xr kldunload 8
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201607252338.u6PNcErg055622>