Index: head/lib/libc/sys/aio_fsync.2 =================================================================== --- head/lib/libc/sys/aio_fsync.2 (revision 302898) +++ head/lib/libc/sys/aio_fsync.2 (revision 302899) @@ -1,153 +1,181 @@ .\" Copyright (c) 2013 Sergey Kandaurov .\" 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 December 27, 2013 +.Dd July 15, 2016 .Dt AIO_FSYNC 2 .Os .Sh NAME .Nm aio_fsync .Nd asynchronous file synchronization (REALTIME) .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In aio.h .Ft int .Fn aio_fsync "int op" "struct aiocb *iocb" .Sh DESCRIPTION The .Fn aio_fsync system call allows the calling process to move all modified data associated with the descriptor .Fa iocb->aio_fildes to a permanent storage device. The call returns immediately after the synchronization request has been enqueued to the descriptor; the synchronization may or may not have completed at the time the call returns. .Pp The .Fa op argument can only be set to .Dv O_SYNC to cause all currently queued I/O operations to be completed as if by a call to .Xr fsync 2 . .Pp If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, then the enqueued operation is submitted at a priority equal to that of the calling process minus .Fa iocb->aio_reqprio . .Pp The .Fa iocb pointer may be subsequently used as an argument to .Fn aio_return and .Fn aio_error in order to determine return or error status for the enqueued operation 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 The .Fn aio_fsync 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 system call is not supported. .It Bq Er EINVAL A value of the .Fa op argument is not set to .Dv O_SYNC . .El .Pp The following conditions may be synchronously detected when the .Fn aio_fsync system call is made, or asynchronously, at any time thereafter. If they are detected at call time, .Fn aio_fsync returns -1 and sets .Va errno appropriately; otherwise the .Fn aio_return system call must be called, and will return -1, and .Fn aio_error must be called to determine the actual value that would have been returned in .Va errno . .Bl -tag -width Er .It Bq Er EBADF The .Fa iocb->aio_fildes argument is not a valid descriptor. .It Bq Er EINVAL This implementation does not support synchronized I/O for this file. .El .Pp If the request is successfully enqueued, but subsequently cancelled or an error occurs, the value returned by the .Fn aio_return system call is per the .Xr read 2 and .Xr write 2 system calls, and the value returned by the .Fn aio_error system call is one of the error returns from the .Xr read 2 or .Xr write 2 system calls. .Sh SEE ALSO .Xr aio_cancel 2 , .Xr aio_error 2 , .Xr aio_read 2 , .Xr aio_return 2 , .Xr aio_suspend 2 , .Xr aio_waitcomplete 2 , .Xr aio_write 2 , .Xr fsync 2 , +.Xr sigevent 3 , .Xr siginfo 3 , .Xr aio 4 .Sh STANDARDS The .Fn aio_fsync system call is expected to conform to the .St -p1003.1 standard. .Sh HISTORY The .Fn aio_fsync system call first appeared in .Fx 7.0 . Index: head/lib/libc/sys/aio_mlock.2 =================================================================== --- head/lib/libc/sys/aio_mlock.2 (revision 302898) +++ head/lib/libc/sys/aio_mlock.2 (revision 302899) @@ -1,133 +1,144 @@ .\" Copyright (c) 2013 Gleb Smirnoff .\" 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 June 3, 2013 +.Dd July 15, 2016 .Dt AIO_MLOCK 2 .Os .Sh NAME .Nm aio_mlock .Nd asynchronous .Xr mlock 2 operation .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In aio.h .Ft int .Fn aio_mlock "struct aiocb *iocb" .Sh DESCRIPTION The .Fn aio_mlock system call allows the calling process to lock into memory the physical pages associated with the virtual address range starting at .Fa iocb->aio_buf for .Fa iocb->aio_nbytes bytes. The call returns immediately after the locking request has been enqueued; the operation may or may not have completed at the time the call returns. .Pp The .Fa iocb pointer may be subsequently used as an argument to .Fn aio_return and .Fn aio_error in order to determine return or error status for the enqueued operation while it is in progress. .Pp 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 and the buffer that the .Fa iocb->aio_buf member of that structure references 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_mlock 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_mlock .Sh ERRORS The .Fn aio_mlock 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 system call is not supported. .El .Pp If the request is successfully enqueued, but subsequently cancelled or an error occurs, the value returned by the .Fn aio_return system call is per the .Xr mlock 2 system call, and the value returned by the .Fn aio_error system call is one of the error returns from the .Xr mlock 2 system call, or .Er ECANCELED if the request was explicitly cancelled via a call to .Fn aio_cancel . .Sh SEE ALSO .Xr aio_cancel 2 , .Xr aio_error 2 , .Xr aio_return 2 , .Xr mlock 2 , +.Xr sigevent 3 , .Xr aio 4 .Sh PORTABILITY The .Fn aio_mlock system call is a .Fx extension, and should not be used in portable code. .Sh HISTORY The .Fn aio_mlock system call first appeared in .Fx 10.0 . .Sh AUTHORS The system call was introduced by .An Gleb Smirnoff Aq Mt glebius@FreeBSD.org . Index: head/lib/libc/sys/aio_read.2 =================================================================== --- head/lib/libc/sys/aio_read.2 (revision 302898) +++ head/lib/libc/sys/aio_read.2 (revision 302899) @@ -1,214 +1,225 @@ .\" Copyright (c) 1998 Terry Lambert .\" 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 November 17, 1998 +.Dd July 15, 2016 .Dt AIO_READ 2 .Os .Sh NAME .Nm aio_read .Nd asynchronous read from a file (REALTIME) .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In aio.h .Ft int .Fn aio_read "struct aiocb *iocb" .Sh DESCRIPTION The .Fn aio_read system call allows the calling process to read .Fa iocb->aio_nbytes from the descriptor .Fa iocb->aio_fildes beginning at the offset .Fa iocb->aio_offset into the buffer pointed to by .Fa iocb->aio_buf . The call returns immediately after the read request has been enqueued to the descriptor; the read may or may not have completed at the time the call returns. .Pp If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, then the enqueued operation is submitted at a priority equal to that of the calling process minus .Fa iocb->aio_reqprio . .Pp The .Fa iocb->aio_lio_opcode argument is ignored by the .Fn aio_read system call. .Pp The .Fa iocb pointer may be subsequently used as an argument to .Fn aio_return and .Fn aio_error in order to determine return or error status for the enqueued operation while it is in progress. .Pp If the request could not be enqueued (generally due to invalid arguments), then the call returns without having enqueued the request. .Pp 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 and the buffer that the .Fa iocb->aio_buf member of that structure references 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_read 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. .Pp If the file offset in .Fa iocb->aio_offset is past the offset maximum for .Fa iocb->aio_fildes , no I/O will occur. .Sh RETURN VALUES .Rv -std aio_read .Sh DIAGNOSTICS None. .Sh ERRORS The .Fn aio_read 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 system call is not supported. .El .Pp The following conditions may be synchronously detected when the .Fn aio_read system call is made, or asynchronously, at any time thereafter. If they are detected at call time, .Fn aio_read returns -1 and sets .Va errno appropriately; otherwise the .Fn aio_return system call must be called, and will return -1, and .Fn aio_error must be called to determine the actual value that would have been returned in .Va errno . .Bl -tag -width Er .It Bq Er EBADF The .Fa iocb->aio_fildes argument is invalid. .It Bq Er EINVAL The offset .Fa iocb->aio_offset is not valid, the priority specified by .Fa iocb->aio_reqprio is not a valid priority, or the number of bytes specified by .Fa iocb->aio_nbytes is not valid. .It Bq Er EOVERFLOW The file is a regular file, .Fa iocb->aio_nbytes is greater than zero, the starting offset in .Fa iocb->aio_offset is before the end of the file, but is at or beyond the .Fa iocb->aio_fildes offset maximum. .El .Pp If the request is successfully enqueued, but subsequently cancelled or an error occurs, the value returned by the .Fn aio_return system call is per the .Xr read 2 system call, and the value returned by the .Fn aio_error system call is either one of the error returns from the .Xr read 2 system call, or one of: .Bl -tag -width Er .It Bq Er EBADF The .Fa iocb->aio_fildes argument is invalid for reading. .It Bq Er ECANCELED The request was explicitly cancelled via a call to .Fn aio_cancel . .It Bq Er EINVAL The offset .Fa iocb->aio_offset would be invalid. .El .Sh SEE ALSO .Xr aio_cancel 2 , .Xr aio_error 2 , .Xr aio_return 2 , .Xr aio_suspend 2 , .Xr aio_waitcomplete 2 , .Xr aio_write 2 , +.Xr sigevent 3 , .Xr siginfo 3 , .Xr aio 4 .Sh STANDARDS The .Fn aio_read system call is expected to conform to the .St -p1003.1 standard. .Sh HISTORY The .Fn aio_read system call first appeared in .Fx 3.0 . .Sh AUTHORS This manual page was written by .An Terry Lambert Aq Mt terry@whistle.com . .Sh BUGS Invalid information in .Fa iocb->_aiocb_private may confuse the kernel. Index: head/lib/libc/sys/aio_write.2 =================================================================== --- head/lib/libc/sys/aio_write.2 (revision 302898) +++ head/lib/libc/sys/aio_write.2 (revision 302899) @@ -1,209 +1,220 @@ .\" Copyright (c) 1999 Softweyr LLC. .\" 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 Softweyr LLC 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 Softweyr LLC 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 June 2, 1999 +.Dd July 15, 2016 .Dt AIO_WRITE 2 .Os .Sh NAME .Nm aio_write .Nd asynchronous write to a file (REALTIME) .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In aio.h .Ft int .Fn aio_write "struct aiocb *iocb" .Sh DESCRIPTION The .Fn aio_write system call allows the calling process to write .Fa iocb->aio_nbytes from the buffer pointed to by .Fa iocb->aio_buf to the descriptor .Fa iocb->aio_fildes . The call returns immediately after the write request has been enqueued to the descriptor; the write may or may not have completed at the time the call returns. If the request could not be enqueued, generally due to invalid arguments, the call returns without having enqueued the request. .Pp If .Dv O_APPEND is set for .Fa iocb->aio_fildes , .Fn aio_write operations append to the file in the same order as the calls were made. If .Dv O_APPEND is not set for the file descriptor, the write operation will occur at the absolute position from the beginning of the file plus .Fa iocb->aio_offset . .Pp If .Dv _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, then the enqueued operation is submitted at a priority equal to that of the calling process minus .Fa iocb->aio_reqprio . .Pp The .Fa iocb pointer may be subsequently used as an argument to .Fn aio_return and .Fn aio_error in order to determine return or error status for the enqueued operation while it is in progress. .Pp 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 and the buffer that the .Fa iocb->aio_buf member of that structure references 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_write system 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. .Pp If the file offset in .Fa iocb->aio_offset is past the offset maximum for .Fa iocb->aio_fildes , no I/O will occur. .Sh RETURN VALUES .Rv -std aio_write .Sh ERRORS The .Fn aio_write 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 system call is not supported. .El .Pp The following conditions may be synchronously detected when the .Fn aio_write system call is made, or asynchronously, at any time thereafter. If they are detected at call time, .Fn aio_write returns -1 and sets .Va errno appropriately; otherwise the .Fn aio_return system call must be called, and will return -1, and .Fn aio_error must be called to determine the actual value that would have been returned in .Va errno . .Bl -tag -width Er .It Bq Er EBADF The .Fa iocb->aio_fildes argument is invalid, or is not opened for writing. .It Bq Er EINVAL The offset .Fa iocb->aio_offset is not valid, the priority specified by .Fa iocb->aio_reqprio is not a valid priority, or the number of bytes specified by .Fa iocb->aio_nbytes is not valid. .El .Pp If the request is successfully enqueued, but subsequently canceled or an error occurs, the value returned by the .Fn aio_return system call is per the .Xr write 2 system call, and the value returned by the .Fn aio_error system call is either one of the error returns from the .Xr write 2 system call, or one of: .Bl -tag -width Er .It Bq Er EBADF The .Fa iocb->aio_fildes argument is invalid for writing. .It Bq Er ECANCELED The request was explicitly canceled via a call to .Fn aio_cancel . .It Bq Er EINVAL The offset .Fa iocb->aio_offset would be invalid. .El .Sh SEE ALSO .Xr aio_cancel 2 , .Xr aio_error 2 , .Xr aio_return 2 , .Xr aio_suspend 2 , .Xr aio_waitcomplete 2 , +.Xr sigevent 3 , .Xr siginfo 3 , .Xr aio 4 .Sh STANDARDS The .Fn aio_write system call is expected to conform to the .St -p1003.1 standard. .Sh HISTORY The .Fn aio_write system call first appeared in .Fx 3.0 . .Sh AUTHORS This manual page was written by .An Wes Peters Aq Mt wes@softweyr.com . .Sh BUGS Invalid information in .Fa iocb->_aiocb_private may confuse the kernel. Index: head/lib/libc/sys/lio_listio.2 =================================================================== --- head/lib/libc/sys/lio_listio.2 (revision 302898) +++ head/lib/libc/sys/lio_listio.2 (revision 302899) @@ -1,175 +1,218 @@ .\" Copyright (c) 2003 Tim J. Robbins .\" 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 January 12, 2003 +.Dd July 15, 2016 .Dt LIO_LISTIO 2 .Os .Sh NAME .Nm lio_listio .Nd "list directed I/O (REALTIME)" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In aio.h .Ft int .Fo lio_listio .Fa "int mode" .Fa "struct aiocb * const list[]" .Fa "int nent" .Fa "struct sigevent *sig" .Fc .Sh DESCRIPTION The .Fn lio_listio function initiates a list of I/O requests with a single function call. The .Fa list argument is an array of pointers to .Vt aiocb structures describing each operation to perform, with .Fa nent elements. .Dv NULL elements are ignored. .Pp The .Va aio_lio_opcode field of each .Vt aiocb specifies the operation to be performed. The following operations are supported: .Bl -tag -width ".Dv LIO_WRITE" .It Dv LIO_READ Read data as if by a call to .Xr aio_read 2 . .It Dv LIO_NOP No operation. .It Dv LIO_WRITE Write data as if by a call to .Xr aio_write 2 . .El .Pp If the .Fa mode argument is .Dv LIO_WAIT , .Fn lio_listio does not return until all the requested operations have been completed. 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 the order 0, 1, ..., .Fa nent Ns \-1 . .Sh RETURN VALUES If .Fa mode is .Dv LIO_WAIT , the .Fn lio_listio function returns 0 if the operations completed successfully, otherwise \-1. .Pp If .Fa mode is .Dv LIO_NOWAIT , the .Fn lio_listio function returns 0 if the operations are successfully queued, otherwise \-1. .Sh ERRORS The .Fn lio_listio function will fail if: .Bl -tag -width Er .It Bq Er EAGAIN There are not enough resources to enqueue the requests. .It Bq Er EAGAIN The request would cause the system-wide limit .Dv AIO_MAX to be exceeded. .It Bq Er EINVAL The .Fa mode argument is neither .Dv LIO_WAIT nor .Dv LIO_NOWAIT , 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 One or more requests failed. .El .Pp In addition, the .Fn lio_listio function may fail for any of the reasons listed for .Xr aio_read 2 and .Xr aio_write 2 . .Pp If .Fn lio_listio succeeds, or fails with an error code of .Er EAGAIN , EINTR , or .Er EIO , some of the requests may have been initiated. The caller should check the error status of each .Vt aiocb structure individually by calling .Xr aio_error 2 . .Sh SEE ALSO .Xr aio_error 2 , .Xr aio_read 2 , .Xr aio_write 2 , .Xr read 2 , .Xr write 2 , +.Xr sigevent 3 , .Xr siginfo 3 , .Xr aio 4 .Sh STANDARDS The .Fn lio_listio function is expected to conform to .St -p1003.1-2001 . Index: head/lib/libc/sys/mq_notify.2 =================================================================== --- head/lib/libc/sys/mq_notify.2 (revision 302898) +++ head/lib/libc/sys/mq_notify.2 (revision 302899) @@ -1,151 +1,165 @@ .\" Copyright (c) 2005 David Xu .\" 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(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. .\" .\" Portions of this text are reprinted and reproduced in electronic form .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- .\" Portable Operating System Interface (POSIX), The Open Group Base .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of .\" Electrical and Electronics Engineers, Inc and The Open Group. In the .\" event of any discrepancy between this version and the original IEEE and .\" The Open Group Standard, the original IEEE and The Open Group Standard is .\" the referee document. The original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" .\" $FreeBSD$ .\" -.Dd November 29, 2005 +.Dd July 15, 2016 .Dt MQ_NOTIFY 2 .Os .Sh NAME .Nm mq_notify .Nd "notify process that a message is available (REALTIME)" .Sh LIBRARY .Lb librt .Sh SYNOPSIS .In mqueue.h .Ft int .Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification" .Sh DESCRIPTION If the argument notification is not .Dv NULL , this system call will register the calling process to be notified of message arrival at an empty message queue associated with the specified message queue descriptor, .Fa mqdes . The notification specified by the .Fa notification argument will be sent to the process when the message queue transitions from empty to non-empty. At any time, only one process may be registered for notification by a message queue. If the calling process or any other process has already registered for notification of message arrival at the specified message queue, subsequent attempts to register for that message queue will fail. .Pp The .Fa notification argument points to a .Vt sigevent structure that defines how the calling process will be notified. If .Fa notification->sigev_notify 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 is .Dv NULL and the process is currently registered for notification by the specified message queue, the existing registration will be removed. .Pp When the notification is sent to the registered process, its registration is removed. The message queue then is available for registration. .Pp If a process has registered for notification of message arrival at a message queue and some thread is blocked in .Fn mq_receive waiting to receive a message when a message arrives at the queue, the arriving message will satisfy the appropriate .Fn mq_receive . The resulting behavior is as if the message queue remains empty, and no notification will be sent. .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn mq_notify system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa mqdes 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 .Fn mq_notify system call conforms to .St -p1003.1-2004 . .Sh HISTORY Support for .Tn POSIX message queues first appeared in .Fx 7.0 . .Sh COPYRIGHT Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. Index: head/lib/libc/sys/timer_create.2 =================================================================== --- head/lib/libc/sys/timer_create.2 (revision 302898) +++ head/lib/libc/sys/timer_create.2 (revision 302899) @@ -1,165 +1,200 @@ .\" Copyright (c) 2005 David Xu .\" 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(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 January 12, 2009 +.Dd July 15, 2016 .Dt TIMER_CREATE 2 .Os .Sh NAME .Nm timer_create .Nd "create a per-process timer (REALTIME)" .Sh LIBRARY .Lb librt .Sh SYNOPSIS .In time.h .In signal.h .Ft int .Fo timer_create .Fa "clockid_t clockid" "struct sigevent *restrict evp" .Fa "timer_t *restrict timerid" .Fc .Sh DESCRIPTION The .Fn timer_create system call creates a per-process timer using the specified clock, .Fa clock_id , as the timing base. The .Fn timer_create system call returns, in the location referenced by .Fa timerid , a timer ID of type .Vt timer_t used to identify the timer in timer requests. This timer ID is unique within the calling process until the timer is deleted. The particular clock, .Fa clock_id , is defined in .In time.h . The timer whose ID is returned is in a disarmed state upon return from .Fn timer_create . .Pp The .Fa evp argument, if .Pf non- Dv NULL , points to a .Vt sigevent 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 .Dv NULL , the effect is as if the .Fa evp argument pointed to a .Vt sigevent structure with the .Va sigev_notify 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 or .Dv CLOCK_MONOTONIC . .Pp If .Fa evp->sigev_notify is .Dv SIGEV_THREAD and .Fa sev->sigev_notify_attributes is not .Dv NULL , if the attribute pointed to by .Fa sev->sigev_notify_attributes has a thread stack address specified by a call to .Fn pthread_attr_setstack or .Fn pthread_attr_setstackaddr , the results are unspecified if the signal is generated more than once. .Sh RETURN VALUES If the call succeeds, .Fn timer_create returns zero and updates the location referenced by .Fa timerid to a .Vt timer_t , which can be passed to the per-process timer calls. If an error occurs, the system call returns a value of \-1 and the global variable .Va errno is set to indicate the error. The value of .Fa timerid is undefined if an error occurs. .Sh ERRORS The .Fn timer_create system call will fail if: .Bl -tag -width Er .It Bq Er EAGAIN 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. .El .Sh SEE ALSO .Xr clock_getres 2 , .Xr timer_delete 2 , .Xr timer_getoverrun 2 , +.Xr sigevent 3 , .Xr siginfo 3 .Sh STANDARDS The .Fn timer_create system call conforms to .St -p1003.1-2004 . .Sh HISTORY Support for .Tn POSIX per-process timer first appeared in .Fx 7.0 . Index: head/share/man/man3/Makefile =================================================================== --- head/share/man/man3/Makefile (revision 302898) +++ head/share/man/man3/Makefile (revision 302899) @@ -1,337 +1,338 @@ # @(#)Makefile 8.2 (Berkeley) 12/13/93 # $FreeBSD$ .include PACKAGE=runtime-manuals MAN= assert.3 \ ATOMIC_VAR_INIT.3 \ bitstring.3 \ end.3 \ fpgetround.3 \ intro.3 \ makedev.3 \ offsetof.3 \ ${PTHREAD_MAN} \ queue.3 \ + sigevent.3 \ siginfo.3 \ stdarg.3 \ sysexits.3 \ tgmath.3 \ timeradd.3 \ tree.3 MLINKS= ATOMIC_VAR_INIT.3 atomic_compare_exchange_strong.3 \ ATOMIC_VAR_INIT.3 atomic_compare_exchange_strong_explicit.3 \ ATOMIC_VAR_INIT.3 atomic_compare_exchange_weak.3 \ ATOMIC_VAR_INIT.3 atomic_compare_exchange_weak_explicit.3 \ ATOMIC_VAR_INIT.3 atomic_exchange.3 \ ATOMIC_VAR_INIT.3 atomic_exchange_explicit.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_add.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_add_explicit.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_and.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_and_explicit.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_or.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_or_explicit.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_sub.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_sub_explicit.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_xor.3 \ ATOMIC_VAR_INIT.3 atomic_fetch_xor_explicit.3 \ ATOMIC_VAR_INIT.3 atomic_init.3 \ ATOMIC_VAR_INIT.3 atomic_is_lock_free.3 \ ATOMIC_VAR_INIT.3 atomic_load.3 \ ATOMIC_VAR_INIT.3 atomic_load_explicit.3 \ ATOMIC_VAR_INIT.3 atomic_store.3 \ ATOMIC_VAR_INIT.3 atomic_store_explicit.3 MLINKS+= bitstring.3 bit_alloc.3 \ bitstring.3 bit_clear.3 \ bitstring.3 bit_decl.3 \ bitstring.3 bit_ffc.3 \ bitstring.3 bit_ffs.3 \ bitstring.3 bit_nclear.3 \ bitstring.3 bit_nset.3 \ bitstring.3 bit_set.3 \ bitstring.3 bitstr_size.3 \ bitstring.3 bit_test.3 MLINKS+= end.3 edata.3 \ end.3 etext.3 MLINKS+= fpgetround.3 fpgetmask.3 \ fpgetround.3 fpgetprec.3 \ fpgetround.3 fpgetsticky.3 \ fpgetround.3 fpresetsticky.3 \ fpgetround.3 fpsetmask.3 \ fpgetround.3 fpsetprec.3 \ fpgetround.3 fpsetround.3 MLINKS+= makedev.3 major.3 \ makedev.3 minor.3 MLINKS+= ${PTHREAD_MLINKS} MLINKS+= queue.3 LIST_CLASS_ENTRY.3 \ queue.3 LIST_CLASS_HEAD.3 \ queue.3 LIST_EMPTY.3 \ queue.3 LIST_ENTRY.3 \ queue.3 LIST_FIRST.3 \ queue.3 LIST_FOREACH.3 \ queue.3 LIST_FOREACH_FROM.3 \ queue.3 LIST_FOREACH_FROM_SAFE.3 \ queue.3 LIST_FOREACH_SAFE.3 \ queue.3 LIST_HEAD.3 \ queue.3 LIST_HEAD_INITIALIZER.3 \ queue.3 LIST_INIT.3 \ queue.3 LIST_INSERT_AFTER.3 \ queue.3 LIST_INSERT_BEFORE.3 \ queue.3 LIST_INSERT_HEAD.3 \ queue.3 LIST_NEXT.3 \ queue.3 LIST_PREV.3 \ queue.3 LIST_REMOVE.3 \ queue.3 LIST_SWAP.3 \ queue.3 SLIST_CLASS_ENTRY.3 \ queue.3 SLIST_CLASS_HEAD.3 \ queue.3 SLIST_EMPTY.3 \ queue.3 SLIST_ENTRY.3 \ queue.3 SLIST_FIRST.3 \ queue.3 SLIST_FOREACH.3 \ queue.3 SLIST_FOREACH_FROM.3 \ queue.3 SLIST_FOREACH_FROM_SAFE.3 \ queue.3 SLIST_FOREACH_SAFE.3 \ queue.3 SLIST_HEAD.3 \ queue.3 SLIST_HEAD_INITIALIZER.3 \ queue.3 SLIST_INIT.3 \ queue.3 SLIST_INSERT_AFTER.3 \ queue.3 SLIST_INSERT_HEAD.3 \ queue.3 SLIST_NEXT.3 \ queue.3 SLIST_REMOVE.3 \ queue.3 SLIST_REMOVE_AFTER.3 \ queue.3 SLIST_REMOVE_HEAD.3 \ queue.3 SLIST_SWAP.3 \ queue.3 STAILQ_CLASS_ENTRY.3 \ queue.3 STAILQ_CLASS_HEAD.3 \ queue.3 STAILQ_CONCAT.3 \ queue.3 STAILQ_EMPTY.3 \ queue.3 STAILQ_ENTRY.3 \ queue.3 STAILQ_FIRST.3 \ queue.3 STAILQ_FOREACH.3 \ queue.3 STAILQ_FOREACH_FROM.3 \ queue.3 STAILQ_FOREACH_FROM_SAFE.3 \ queue.3 STAILQ_FOREACH_SAFE.3 \ queue.3 STAILQ_HEAD.3 \ queue.3 STAILQ_HEAD_INITIALIZER.3 \ queue.3 STAILQ_INIT.3 \ queue.3 STAILQ_INSERT_AFTER.3 \ queue.3 STAILQ_INSERT_HEAD.3 \ queue.3 STAILQ_INSERT_TAIL.3 \ queue.3 STAILQ_LAST.3 \ queue.3 STAILQ_NEXT.3 \ queue.3 STAILQ_REMOVE.3 \ queue.3 STAILQ_REMOVE_AFTER.3 \ queue.3 STAILQ_REMOVE_HEAD.3 \ queue.3 STAILQ_SWAP.3 \ queue.3 TAILQ_CLASS_ENTRY.3 \ queue.3 TAILQ_CLASS_HEAD.3 \ queue.3 TAILQ_CONCAT.3 \ queue.3 TAILQ_EMPTY.3 \ queue.3 TAILQ_ENTRY.3 \ queue.3 TAILQ_FIRST.3 \ queue.3 TAILQ_FOREACH.3 \ queue.3 TAILQ_FOREACH_FROM.3 \ queue.3 TAILQ_FOREACH_FROM_SAFE.3 \ queue.3 TAILQ_FOREACH_REVERSE.3 \ queue.3 TAILQ_FOREACH_REVERSE_FROM.3 \ queue.3 TAILQ_FOREACH_REVERSE_FROM_SAFE.3 \ queue.3 TAILQ_FOREACH_REVERSE_SAFE.3 \ queue.3 TAILQ_FOREACH_SAFE.3 \ queue.3 TAILQ_HEAD.3 \ queue.3 TAILQ_HEAD_INITIALIZER.3 \ queue.3 TAILQ_INIT.3 \ queue.3 TAILQ_INSERT_AFTER.3 \ queue.3 TAILQ_INSERT_BEFORE.3 \ queue.3 TAILQ_INSERT_HEAD.3 \ queue.3 TAILQ_INSERT_TAIL.3 \ queue.3 TAILQ_LAST.3 \ queue.3 TAILQ_NEXT.3 \ queue.3 TAILQ_PREV.3 \ queue.3 TAILQ_REMOVE.3 \ queue.3 TAILQ_SWAP.3 MLINKS+= stdarg.3 va_arg.3 \ stdarg.3 va_copy.3 \ stdarg.3 va_end.3 \ stdarg.3 varargs.3 \ stdarg.3 va_start.3 MLINKS+= timeradd.3 timerclear.3 \ timeradd.3 timercmp.3 \ timeradd.3 timerisset.3 \ timeradd.3 timersub.3 MLINKS+= tree.3 RB_EMPTY.3 \ tree.3 RB_ENTRY.3 \ tree.3 RB_FIND.3 \ tree.3 RB_FOREACH.3 \ tree.3 RB_FOREACH_REVERSE.3 \ tree.3 RB_GENERATE.3 \ tree.3 RB_GENERATE_STATIC.3 \ tree.3 RB_HEAD.3 \ tree.3 RB_INIT.3 \ tree.3 RB_INITIALIZER.3 \ tree.3 RB_INSERT.3 \ tree.3 RB_LEFT.3 \ tree.3 RB_MAX.3 \ tree.3 RB_MIN.3 \ tree.3 RB_NEXT.3 \ tree.3 RB_NFIND.3 \ tree.3 RB_PARENT.3 \ tree.3 RB_PREV.3 \ tree.3 RB_PROTOTYPE.3 \ tree.3 RB_PROTOTYPE_STATIC.3 \ tree.3 RB_REMOVE.3 \ tree.3 RB_RIGHT.3 \ tree.3 RB_ROOT.3 \ tree.3 SPLAY_EMPTY.3 \ tree.3 SPLAY_ENTRY.3 \ tree.3 SPLAY_FIND.3 \ tree.3 SPLAY_FOREACH.3 \ tree.3 SPLAY_GENERATE.3 \ tree.3 SPLAY_HEAD.3 \ tree.3 SPLAY_INIT.3 \ tree.3 SPLAY_INITIALIZER.3 \ tree.3 SPLAY_INSERT.3 \ tree.3 SPLAY_LEFT.3 \ tree.3 SPLAY_MAX.3 \ tree.3 SPLAY_MIN.3 \ tree.3 SPLAY_NEXT.3 \ tree.3 SPLAY_PROTOTYPE.3 \ tree.3 SPLAY_REMOVE.3 \ tree.3 SPLAY_RIGHT.3 \ tree.3 SPLAY_ROOT.3 .if ${MK_LIBTHR} != "no" PTHREAD_MAN= pthread.3 \ pthread_affinity_np.3 \ pthread_atfork.3 \ pthread_attr.3 \ pthread_attr_affinity_np.3 \ pthread_attr_get_np.3 \ pthread_attr_setcreatesuspend_np.3 \ pthread_barrierattr.3 \ pthread_barrier_destroy.3 \ pthread_cancel.3 \ pthread_cleanup_pop.3 \ pthread_cleanup_push.3 \ pthread_condattr.3 \ pthread_cond_broadcast.3 \ pthread_cond_destroy.3 \ pthread_cond_init.3 \ pthread_cond_signal.3 \ pthread_cond_timedwait.3 \ pthread_cond_wait.3 \ pthread_create.3 \ pthread_detach.3 \ pthread_equal.3 \ pthread_exit.3 \ pthread_getconcurrency.3 \ pthread_getcpuclockid.3 \ pthread_getspecific.3 \ pthread_getthreadid_np.3 \ pthread_join.3 \ pthread_key_create.3 \ pthread_key_delete.3 \ pthread_kill.3 \ pthread_main_np.3 \ pthread_multi_np.3 \ pthread_mutexattr.3 \ pthread_mutexattr_getkind_np.3 \ pthread_mutex_consistent.3 \ pthread_mutex_destroy.3 \ pthread_mutex_init.3 \ pthread_mutex_lock.3 \ pthread_mutex_timedlock.3 \ pthread_mutex_trylock.3 \ pthread_mutex_unlock.3 \ pthread_once.3 \ pthread_resume_all_np.3 \ pthread_resume_np.3 \ pthread_rwlockattr_destroy.3 \ pthread_rwlockattr_getpshared.3 \ pthread_rwlockattr_init.3 \ pthread_rwlockattr_setpshared.3 \ pthread_rwlock_destroy.3 \ pthread_rwlock_init.3 \ pthread_rwlock_rdlock.3 \ pthread_rwlock_timedrdlock.3 \ pthread_rwlock_timedwrlock.3 \ pthread_rwlock_unlock.3 \ pthread_rwlock_wrlock.3 \ pthread_schedparam.3 \ pthread_self.3 \ pthread_set_name_np.3 \ pthread_setspecific.3 \ pthread_sigmask.3 \ pthread_spin_init.3 \ pthread_spin_lock.3 \ pthread_suspend_all_np.3 \ pthread_suspend_np.3 \ pthread_switch_add_np.3 \ pthread_testcancel.3 \ pthread_yield.3 PTHREAD_MLINKS= pthread_affinity_np.3 pthread_getaffinity_np.3 \ pthread_affinity_np.3 pthread_setaffinity_np.3 PTHREAD_MLINKS+=pthread_attr.3 pthread_attr_destroy.3 \ pthread_attr.3 pthread_attr_getdetachstate.3 \ pthread_attr.3 pthread_attr_getguardsize.3 \ pthread_attr.3 pthread_attr_getinheritsched.3 \ pthread_attr.3 pthread_attr_getschedparam.3 \ pthread_attr.3 pthread_attr_getschedpolicy.3 \ pthread_attr.3 pthread_attr_getscope.3 \ pthread_attr.3 pthread_attr_getstack.3 \ pthread_attr.3 pthread_attr_getstackaddr.3 \ pthread_attr.3 pthread_attr_getstacksize.3 \ pthread_attr.3 pthread_attr_init.3 \ pthread_attr.3 pthread_attr_setdetachstate.3 \ pthread_attr.3 pthread_attr_setguardsize.3 \ pthread_attr.3 pthread_attr_setinheritsched.3 \ pthread_attr.3 pthread_attr_setschedparam.3 \ pthread_attr.3 pthread_attr_setschedpolicy.3 \ pthread_attr.3 pthread_attr_setscope.3 \ pthread_attr.3 pthread_attr_setstack.3 \ pthread_attr.3 pthread_attr_setstackaddr.3 \ pthread_attr.3 pthread_attr_setstacksize.3 PTHREAD_MLINKS+=pthread_attr_affinity_np.3 pthread_attr_getaffinity_np.3 \ pthread_attr_affinity_np.3 pthread_attr_setaffinity_np.3 PTHREAD_MLINKS+=pthread_barrierattr.3 pthread_barrierattr_destroy.3 \ pthread_barrierattr.3 pthread_barrierattr_getpshared.3 \ pthread_barrierattr.3 pthread_barrierattr_init.3 \ pthread_barrierattr.3 pthread_barrierattr_setpshared.3 PTHREAD_MLINKS+=pthread_barrier_destroy.3 pthread_barrier_init.3 \ pthread_barrier_destroy.3 pthread_barrier_wait.3 PTHREAD_MLINKS+=pthread_condattr.3 pthread_condattr_destroy.3 \ pthread_condattr.3 pthread_condattr_init.3 \ pthread_condattr.3 pthread_condattr_getclock.3 \ pthread_condattr.3 pthread_condattr_setclock.3 \ pthread_condattr.3 pthread_condattr_getpshared.3 \ pthread_condattr.3 pthread_condattr_setpshared.3 PTHREAD_MLINKS+=pthread_getconcurrency.3 pthread_setconcurrency.3 PTHREAD_MLINKS+=pthread_multi_np.3 pthread_single_np.3 PTHREAD_MLINKS+=pthread_mutexattr.3 pthread_mutexattr_destroy.3 \ pthread_mutexattr.3 pthread_mutexattr_getprioceiling.3 \ pthread_mutexattr.3 pthread_mutexattr_getprotocol.3 \ pthread_mutexattr.3 pthread_mutexattr_getrobust.3 \ pthread_mutexattr.3 pthread_mutexattr_gettype.3 \ pthread_mutexattr.3 pthread_mutexattr_init.3 \ pthread_mutexattr.3 pthread_mutexattr_setprioceiling.3 \ pthread_mutexattr.3 pthread_mutexattr_setprotocol.3 \ pthread_mutexattr.3 pthread_mutexattr_setrobust.3 \ pthread_mutexattr.3 pthread_mutexattr_settype.3 PTHREAD_MLINKS+=pthread_mutexattr_getkind_np.3 pthread_mutexattr_setkind_np.3 PTHREAD_MLINKS+=pthread_rwlock_rdlock.3 pthread_rwlock_tryrdlock.3 PTHREAD_MLINKS+=pthread_rwlock_wrlock.3 pthread_rwlock_trywrlock.3 PTHREAD_MLINKS+=pthread_schedparam.3 pthread_getschedparam.3 \ pthread_schedparam.3 pthread_setschedparam.3 PTHREAD_MLINKS+=pthread_spin_init.3 pthread_spin_destroy.3 \ pthread_spin_lock.3 pthread_spin_trylock.3 \ pthread_spin_lock.3 pthread_spin_unlock.3 PTHREAD_MLINKS+=pthread_switch_add_np.3 pthread_switch_delete_np.3 PTHREAD_MLINKS+=pthread_testcancel.3 pthread_setcancelstate.3 \ pthread_testcancel.3 pthread_setcanceltype.3 PTHREAD_MLINKS+=pthread_join.3 pthread_timedjoin_np.3 .endif .include Index: head/share/man/man3/sigevent.3 =================================================================== --- head/share/man/man3/sigevent.3 (nonexistent) +++ head/share/man/man3/sigevent.3 (revision 302899) @@ -0,0 +1,127 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2016 John H. Baldwin +.\" 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 . Property changes on: head/share/man/man3/sigevent.3 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: head/share/man/man4/aio.4 =================================================================== --- head/share/man/man4/aio.4 (revision 302898) +++ head/share/man/man4/aio.4 (revision 302899) @@ -1,162 +1,211 @@ .\"- .\" Copyright (c) 2002 Dag-Erling Coïdan Smørgrav .\" 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. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" 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 March 1, 2016 +.Dd July 15, 2016 .Dt AIO 4 .Os .Sh NAME .Nm aio .Nd asynchronous I/O .Sh DESCRIPTION The .Nm facility provides system calls for asynchronous I/O. However, asynchronous I/O operations are only enabled for certain file types by default. Asynchronous I/O operations for other file types may block an AIO daemon indefinitely resulting in process and/or system hangs. Asynchronous I/O operations can be enabled for all file types by setting the .Va vfs.aio.enable_unsafe sysctl node to a non-zero value. .Pp Asynchronous I/O operations on sockets and raw disk devices do not block indefinitely and are enabled by default. .Pp The .Nm facility uses kernel processes (also known as AIO daemons) to service most asynchronous I/O requests. These processes are grouped into pools containing a variable number of processes. Each pool will add or remove processes to the pool based on load. Pools can be configured by sysctl nodes that define the minimum and maximum number of processes as well as the amount of time an idle process will wait before exiting. .Pp One pool of AIO daemons is used to service asynchronous I/O requests for sockets. These processes are named .Dq soaiod . The following sysctl nodes are used with this pool: .Bl -tag -width indent .It Va kern.ipc.aio.num_procs The current number of processes in the pool. .It Va kern.ipc.aio.target_procs The minimum number of processes that should be present in the pool. .It Va kern.ipc.aio.max_procs The maximum number of processes permitted in the pool. .It Va kern.ipc.aio.lifetime The amount of time a process is permitted to idle in clock ticks. If a process is idle for this amount of time and there are more processes in the pool than the target minimum, the process will exit. .El .Pp A second pool of AIO daemons is used to service all other asynchronous I/O requests except for I/O requests to raw disks. These processes are named .Dq aiod . The following sysctl nodes are used with this pool: .Bl -tag -width indent .It Va vfs.aio.num_aio_procs The current number of processes in the pool. .It Va vfs.aio.target_aio_procs The minimum number of processes that should be present in the pool. .It Va vfs.aio.max_aio_procs The maximum number of processes permitted in the pool. .It Va vfs.aio.aiod_lifetime The amount of time a process is permitted to idle in clock ticks. If a process is idle for this amount of time and there are more processes in the pool than the target minimum, the process will exit. .El .Pp Asynchronous I/O requests for raw disks are queued directly to the disk device layer after temporarily wiring the user pages associated with the request. These requests are not serviced by any of the AIO daemon pools. .Pp Several limits on the number of asynchronous I/O requests are imposed both system-wide and per-process. These limits are configured via the following sysctls: .Bl -tag -width indent .It Va vfs.aio.max_buf_aio The maximum number of queued asynchronous I/O requests for raw disks permitted for a single process. Asynchronous I/O requests that have completed but whose status has not been retrieved via .Xr aio_return 2 or .Xr aio_waitcomplete 2 are not counted against this limit. .It Va vfs.aio.num_buf_aio The number of queued asynchronous I/O requests for raw disks system-wide. .It Va vfs.aio.max_aio_queue_per_proc The maximum number of asynchronous I/O requests for a single process serviced concurrently by the default AIO daemon pool. .It Va vfs.aio.max_aio_per_proc The maximum number of outstanding asynchronous I/O requests permitted for a single process. This includes requests that have not been serviced, requests currently being serviced, and requests that have completed but whose status has not been retrieved via .Xr aio_return 2 or .Xr aio_waitcomplete 2 . .It Va vfs.aio.num_queue_count The number of outstanding asynchronous I/O requests system-wide. .It Va vfs.aio.max_aio_queue 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 , .Xr aio_read 2 , .Xr aio_return 2 , .Xr aio_suspend 2 , .Xr aio_waitcomplete 2 , .Xr aio_write 2 , .Xr lio_listio 2 , +.Xr sigevent 3 , .Xr sysctl 8 .Sh HISTORY The .Nm facility appeared as a kernel option in .Fx 3.0 . The .Nm kernel module appeared in .Fx 5.0 . The .Nm facility was integrated into all kernels in .Fx 11.0 .