From 4a9c6f5d1b372ec787c385c50a0cbcb632aeec30 Mon Sep 17 00:00:00 2001 From: wes Date: Thu, 1 Jul 1999 19:58:12 +0000 Subject: [PATCH] Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. --- lib/libc/sys/aio_cancel.2 | 80 ++++++++++++++++ lib/libc/sys/aio_error.2 | 95 ++++++++++++++++++ lib/libc/sys/aio_read.2 | 28 ++++-- lib/libc/sys/aio_return.2 | 97 +++++++++++++++++++ lib/libc/sys/aio_suspend.2 | 92 ++++++++++++++++++ lib/libc/sys/aio_write.2 | 192 +++++++++++++++++++++++++++++++++++++ 6 files changed, 575 insertions(+), 9 deletions(-) create mode 100644 lib/libc/sys/aio_cancel.2 create mode 100644 lib/libc/sys/aio_error.2 create mode 100644 lib/libc/sys/aio_return.2 create mode 100644 lib/libc/sys/aio_suspend.2 create mode 100644 lib/libc/sys/aio_write.2 diff --git a/lib/libc/sys/aio_cancel.2 b/lib/libc/sys/aio_cancel.2 new file mode 100644 index 000000000000..2923a63ed158 --- /dev/null +++ b/lib/libc/sys/aio_cancel.2 @@ -0,0 +1,80 @@ +.\" 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. +.\" +.\" $Id$ +.\" +.Dd June 2, 1999 +.Dt AIO_CANCEL 2 +.Os +.Sh NAME +.Nm aio_cancel +.Nd cancel an outstanding asynchronus I/O operation (REALTIME) +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn aio_cancel "int something" "struct aiocb * iocb" +.Sh DESCRIPTION +The +.Fn aio_cancel +function is supposed to cancel the specified outstanding asynchronous +I/O request. +.Fn aio_cancel +is not implemented at this time, and always fails returning +.Dv ENOSYS . +.Sh RETURN VALUES +When +.Fn aio_cancel +inevitably fails, it returns +.Dv ENOSYS +to signify it is not supported. +.Sh SEE ALSO +.Xr aio_read 2 , +.Xr aio_write 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 . +.Sh ERRORS +The +.Fn aio_cancel +function currently always fails, due to: +.Bl -tag -width Er +.It Bq Er ENOSYS +this operation is not implemented at this time. +.El +.Sh STANDARDS +.Nm +fails to conform to the +.St -p1003.2 +standard. +.Sh HISTORY +The +.Nm +function first appeared in +.Fx 3.0 . +.Sh AUTHOR +This +manual page was written by +.An Wes Peters Aq wes@softweyr.com . +.Sh BUGS +Are now movie stars. diff --git a/lib/libc/sys/aio_error.2 b/lib/libc/sys/aio_error.2 new file mode 100644 index 000000000000..c0a7551c7c2e --- /dev/null +++ b/lib/libc/sys/aio_error.2 @@ -0,0 +1,95 @@ +.\" 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. +.\" +.\" $Id$ +.\" +.Dd June 2, 1999 +.Dt AIO_ERROR 2 +.Os +.Sh NAME +.Nm aio_error +.Nd retrieve error status of asynchronus I/O operation (REALTIME) +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn aio_error "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_error +function returns the error status of the asynchronous I/O request +associated with the structure pointed to by +.Ar iocb . +.Sh RETURN VALUES +If the asynchronous I/O request has completed successfully, +.Fn aio_error +returns 0. If the request has not yet completed, +.Dv EINPROGRESS +is returned. If the request has completed unsuccessfully the error +status is returned as described in +.Xr read 2 , +.Xr write 2 , +or +.Xr fsync 2 +is returned. +On failure, +.Fn aio_error +returns +.Dv -1 +and sets +.Dv errno +to indicate the error condition. +.Sh ERRORS +The +.Fn aio_error +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Ar iocb +does not reference an outstanding asynchronous I/O request. +.El +.Sh SEE ALSO +.Xr aio_return 2 , +.Xr aio_read 2 , +.Xr aio_write 2 , +.Xr aio_cancel 2 , +.Xr aio_suspend 2 , +.Xr read 2 , +.Xr write 2 , +.Xr fsync 2 . +.Sh STANDARDS +.Fn aio_error +is expected to conform to the +.St -p1003.2 +standard. +.Sh HISTORY +The +.Nm +function first appeared in +.Fx 3.0 . +.Sh AUTHOR +This +manual page was written by +.An Wes Peters Aq wes@softweyr.com . +.Sh BUGS +Taste icky. diff --git a/lib/libc/sys/aio_read.2 b/lib/libc/sys/aio_read.2 index 9e6b532c6469..524daaf37720 100644 --- a/lib/libc/sys/aio_read.2 +++ b/lib/libc/sys/aio_read.2 @@ -85,6 +85,12 @@ 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 +.Ar 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. @@ -96,12 +102,6 @@ is past the offset maximum for no I/O will occur. .Sh RETURN VALUES .Rv -std aio_read -.Sh STANDARDS -The -.Fn aio_read -call conforms to the -.St -p1003.2 -standard. .Sh DIAGNOSTICS None. .Sh ERRORS @@ -127,7 +127,7 @@ returns -1 and sets appropriately; otherwise the .Fn aio_return function must be called, and will return -1, and -Fn aio_error +.Fn aio_error must be called to determine the actual calue that would have been returned in .Ar errno . @@ -176,14 +176,24 @@ The offset .Ar iocb->aio_offset would be invalid. .El +.Sh STANDARDS +The +.Fn aio_read +call is expected to conform to the +.St -p1003.2 +standard. .Sh HISTORY The .Nm -Function first appeared in +function first appeared in .Fx 3.0 . .Sh AUTHOR This manual page was written by .An Terry Lambert Aq terry@whistle.com . .Sh BUGS -The value of iocb->aio_offset is ignored. +The value of +.Ar iocb->aio_offset +is ignored. Invalid information in +.Ar iocb->_aiocb_private +may confuse the kernel. diff --git a/lib/libc/sys/aio_return.2 b/lib/libc/sys/aio_return.2 new file mode 100644 index 000000000000..82baae2da5a6 --- /dev/null +++ b/lib/libc/sys/aio_return.2 @@ -0,0 +1,97 @@ +.\" 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. +.\" +.\" $Id$ +.\" +.Dd June 2, 1999 +.Dt AIO_RETURN 2 +.Os +.Sh NAME +.Nm aio_return +.Nd retrieve return status of asynchronus I/O operation (REALTIME) +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn aio_return "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_return +function returns the final status of the asynchronous I/O request +associated with the structure pointed to by +.Ar iocb . +.Pp +.Fn aio_return +should only be called once, to obtain the final status of an asynchronous +I/O operation once +.Xr aio_error 2 +returns something other than +.Dv EINPROGRESS . +.Sh RETURN VALUES +If the asynchronous I/O request has completed, the status is returned +as described in +.Xr read 2 , +.Xr write 2 , +or +.Xr fsync 2 . +On failure, +.Fn aio_return +returns +.Dv -1 +and sets +.Dv errno +to indicate the error condition. +.Sh SEE ALSO +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_write 2 , +.Xr aio_cancel 2 , +.Xr aio_suspend 2 , +.Xr read 2 , +.Xr write 2 , +.Xr fsync 2 . +.Sh ERRORS +The +.Fn aio_return +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Ar iocb +does not reference an outstanding asynchronous I/O request. +.El +.Sh STANDARDS +.Fn aio_return +is expected to conform to the +.St -p1003.2 +standard. +.Sh HISTORY +The +.Nm +function first appeared in +.Fx 3.0 . +.Sh AUTHOR +This +manual page was written by +.An Wes Peters Aq wes@softweyr.com . +.Sh BUGS +Taste great! diff --git a/lib/libc/sys/aio_suspend.2 b/lib/libc/sys/aio_suspend.2 new file mode 100644 index 000000000000..01c635cefb54 --- /dev/null +++ b/lib/libc/sys/aio_suspend.2 @@ -0,0 +1,92 @@ +.\" 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. +.\" +.\" $Id$ +.\" +.Dd June 2, 1999 +.Dt AIO_SUSPEND 2 +.Os +.Sh NAME +.Nm aio_suspend +.Nd suspend until asynchronus I/O operations or timeout complete (REALTIME) +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn aio_suspend "const struct aiocb * const iocbs[]" "int niocb" "const struct timespec * timeout" +.Sh DESCRIPTION +The +.Fn aio_suspend +function suspends the calling process until all of the specified +asynchronous I/O requests have completed or the +.Ar timeout +has passed. +.Ar iocbs +is an array of +.Ar niocb +pointers to asynchronous I/O requests. Array members containing NULL +will be silently ignored. +.Sh RETURN VALUES +If all of the specified asynchronous I/O requests have completed, +.Fn aio_suspend +returns 0. If the +.Ar timeout +expired, +.Dv EAGAIN +is returned. Other return values indicate an error condition as +detailed below. +.Sh SEE ALSO +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_write 2 , +.Xr aio_cancel 2 , +.Xr aio_suspend 2. +.Sh ERRORS +The +.Fn aio_suspend +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Ar iocbs +contains more than +.Dv AIO_LISTIO_MAX aysynchronous I/O requests, or at least one +of the requests is not valid. +.It Bq Er EINTR +the suspend was interrupted by a signal. +.El +.Sh STANDARDS +.Fn aio_suspend +is expected to conform to the +.St -p1003.2 +standard. +.Sh HISTORY +The +.Nm +function first appeared in +.Fx 3.0 . +.Sh AUTHOR +This +manual page was written by +.An Wes Peters Aq wes@softweyr.com . +.Sh BUGS +Have six legs. diff --git a/lib/libc/sys/aio_write.2 b/lib/libc/sys/aio_write.2 new file mode 100644 index 000000000000..231ea73c2dc6 --- /dev/null +++ b/lib/libc/sys/aio_write.2 @@ -0,0 +1,192 @@ +.\" 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. +.\" +.\" $Id$ +.\" +.Dd June 2, 1999 +.Dt AIO_WRITE 2 +.Os +.Sh NAME +.Nm aio_write +.Nd asynchronus write to a file (REALTIME) +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn aio_write "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_write +function allows the calling process to write +.Ar iocb->aio_nbytes +from the buffer pointed to by +.Ar iocb->aio_buf +to the descriptor +.Ar 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 +.Ar 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 +.Ar 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 +.Ar iocb->aio_reqprio . +.Pp +The +.Ar 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 +.Ar iocb->aio_offset +can be modified during the request as context, so this value must not +be referenced after the request is enqueued. +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Ar iocb +and the buffer that the +.Ar 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 +.Ar 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 +.Ar iocb->aio_offset +is past the offset maximum for +.Ar iocb->aio_fildes , +no I/O will occur. +.Sh RETURN VALUES +.Rv -std aio_write +.Sh ERRORS +The +.Fn aio_write +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er ENOSYS +The +.Fn aio_write +call is not supported. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_write +call is made, or asynchronously, at any time thereafter. If they +are detected at call time, +.Fn aio_write +returns -1 and sets +.Ar errno +appropriately; otherwise the +.Fn aio_return +function must be called, and will return -1, and +.Fn aio_error +must be called to determine the actual calue that would have been +returned in +.Ar errno . +.Pp +.Bl -tag -width Er +.It Bq Er EBADF +.Ar iocb->aio_fildes +is invalid, or is not opened for writing. +.It Bq Er EINVAL +The offset +.Ar iocb->aio_offset +is not valid, the priority specified by +.Ar iocb->aio_reqprio +is not a valid priority, or the number of bytes specified by +.Ar iocb->aio_nbytes +is not valid. +.El +.Pp +If the request is successfully enqueued, but subsequently cancelled +or an error occurs, the value returned by the +.Fn aio_return +function is per the +.Xr write 2 +call, and the value returned by the +.Fn aio_error +function is either one of the error returns from the +.Xr write 2 +call, or one of: +.Bl -tag -width Er +.It Bq Er EBADF +.Ar iocb->aio_fildes +is invalid for writing. +.It Bq Er ECANCELED +The request was explicitly cancelled via a call to +.Fn aio_cancel . +.It Bq Er EINVAL +The offset +.Ar iocb->aio_offset +would be invalid. +.El +.Sh STANDARDS +.Fn aio_write +is expected to conform to the +.St -p1003.2 +standard. +.Sh HISTORY +The +.Nm +Function first appeared in +.Fx 3.0 . +.Sh AUTHOR +This manual page was written by +.An Wes Peters Aq wes@softweyr.com . +.Sh BUGS +Asynchronous I/O operations cannot be cancelled in this implementation. +Invalid information in +.Ar iocb->_aiocb_private +may confuse the kernel. +