freebsd-skq/lib/libc/sys/aio_suspend.2

.\" 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
.Dt AIO_SUSPEND 2
.Os
.Sh NAME
.Nm aio_suspend
.Nd suspend until asynchronous I/O operations or timeout complete (REALTIME)
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In aio.h
.Ft int
.Fn aio_suspend "const struct aiocb *const iocbs[]" "int niocb" "const struct timespec *timeout"
.Sh DESCRIPTION
The
.Fn aio_suspend
system call suspends the calling process until at least one of the
specified asynchronous I/O requests have completed, a signal is
delivered, or the
.Fa timeout
has passed.
.Pp
The
.Fa iocbs
argument
is an array of
.Fa niocb
pointers to asynchronous I/O requests.
Array members containing
null pointers will be silently ignored.
.Pp
If
.Fa timeout
is not a null pointer, it specifies a maximum interval to suspend.
If
.Fa timeout
is a null pointer, the suspend blocks indefinitely.
To effect a
poll, the
.Fa timeout
should point to a zero-value timespec structure.
.Sh RETURN VALUES
If one or more of the specified asynchronous I/O requests have
completed,
.Fn aio_suspend
returns 0.
Otherwise it returns -1 and sets
.Va errno
to indicate the error, as enumerated below.
.Sh ERRORS
The
.Fn aio_suspend
system call will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
the
.Fa timeout
expired before any I/O requests completed.
.It Bq Er EINVAL
The
.Fa iocbs
argument
contains more than
.Dv AIO_LISTIO_MAX
asynchronous 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 SEE ALSO
.Xr aio_cancel 2 ,
.Xr aio_error 2 ,
.Xr aio_return 2 ,
.Xr aio_waitcomplete 2 ,
.Xr aio_write 2 ,
.Xr aio 4
.Sh STANDARDS
The
.Fn aio_suspend
system call
is expected to conform to the
.St -p1003.1
standard.
.Sh HISTORY
The
.Fn aio_suspend
system call first appeared in
.Fx 3.0 .
.Sh AUTHORS
This
manual page was written by
.An Wes Peters Aq wes@softweyr.com .
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.\" 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$ -> $FreeBSD$ 1999-08-28 00:22:10 +00:00			`.\" $FreeBSD$`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.\"`
			`.Dd June 2, 1999`
			`.Dt AIO_SUSPEND 2`
			`.Os`
			`.Sh NAME`
			`.Nm aio_suspend`
Fix typos/spelling errors. 1999-07-01 21:09:57 +00:00			`.Nd suspend until asynchronous I/O operations or timeout complete (REALTIME)`
Introduce ".Lb" macro to libc manpages. More libraries manpages updates following. 2000-04-21 09:42:15 +00:00			`.Sh LIBRARY`
			`.Lb libc`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Sh SYNOPSIS`
mdoc(7) police: Use the new .In macro for #include statements. 2001-10-01 16:09:29 +00:00			`.In aio.h`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Ft int`
style(9) cleanup 2008-04-03 02:41:54 +00:00			`.Fn aio_suspend "const struct aiocb const iocbs[]" "int niocb" "const struct timespec timeout"`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Sh DESCRIPTION`
			`The`
			`.Fn aio_suspend`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call suspends the calling process until at least one of the`
Fixed the description of when and why aio_suspend returns. Also spelled out the return values and conditions a little better. Noticed by: John Polstra <jdp@polstra.com> 1999-09-20 18:30:55 +00:00			`specified asynchronous I/O requests have completed, a signal is`
			`delivered, or the`
Replace .Va, .Ar and .Nm with .Fa or .Va where necessary, examples: ``.Ar errno'' -> ``.Va errno'' ``.Nm ops'' -> ``.Fa ops'' ``.Va fd'' -> ``.Fa fd'' 2000-06-23 05:05:44 +00:00			`.Fa timeout`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`has passed.`
Fixed the description of when and why aio_suspend returns. Also spelled out the return values and conditions a little better. Noticed by: John Polstra <jdp@polstra.com> 1999-09-20 18:30:55 +00:00			`.Pp`
mdoc(7) police: "The .Fa argument.". 2002-12-19 09:40:28 +00:00			`The`
Replace .Va, .Ar and .Nm with .Fa or .Va where necessary, examples: ``.Ar errno'' -> ``.Va errno'' ``.Nm ops'' -> ``.Fa ops'' ``.Va fd'' -> ``.Fa fd'' 2000-06-23 05:05:44 +00:00			`.Fa iocbs`
mdoc(7) police: "The .Fa argument.". 2002-12-19 09:40:28 +00:00			`argument`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`is an array of`
Replace .Va, .Ar and .Nm with .Fa or .Va where necessary, examples: ``.Ar errno'' -> ``.Va errno'' ``.Nm ops'' -> ``.Fa ops'' ``.Va fd'' -> ``.Fa fd'' 2000-06-23 05:05:44 +00:00			`.Fa niocb`
Mechanically kill hard sentence breaks. 2004-07-02 23:52:20 +00:00			`pointers to asynchronous I/O requests.`
			`Array members containing`
``NULL is a specific instance of a null pointer constant; the generic is a "null pointer".'' Making good use of the excellent explanations sent to me by Ruslan Ermilov, Garrett Wollman and Bruce Evans, correct the descriptions of null pointers. They are just "null pointers", not nil, not NULL or ".Dv NULL". Suggested by: ru, wollman, bde Reviewed by: ru, wollman Pointy hat: keramida 2004-12-23 23:45:25 +00:00			`null pointers will be silently ignored.`
Correct the description of the timeout argument. I've examined the code, which seems to implement the POSIX requirements, and have described the behavior here. Basically, it behaves the same as select(2). Noticed by: John Polstra 1999-10-09 01:35:58 +00:00			`.Pp`
			`If`
Replace .Va, .Ar and .Nm with .Fa or .Va where necessary, examples: ``.Ar errno'' -> ``.Va errno'' ``.Nm ops'' -> ``.Fa ops'' ``.Va fd'' -> ``.Fa fd'' 2000-06-23 05:05:44 +00:00			`.Fa timeout`
``NULL is a specific instance of a null pointer constant; the generic is a "null pointer".'' Making good use of the excellent explanations sent to me by Ruslan Ermilov, Garrett Wollman and Bruce Evans, correct the descriptions of null pointers. They are just "null pointers", not nil, not NULL or ".Dv NULL". Suggested by: ru, wollman, bde Reviewed by: ru, wollman Pointy hat: keramida 2004-12-23 23:45:25 +00:00			`is not a null pointer, it specifies a maximum interval to suspend.`
Correct the description of the timeout argument. I've examined the code, which seems to implement the POSIX requirements, and have described the behavior here. Basically, it behaves the same as select(2). Noticed by: John Polstra 1999-10-09 01:35:58 +00:00			`If`
Replace .Va, .Ar and .Nm with .Fa or .Va where necessary, examples: ``.Ar errno'' -> ``.Va errno'' ``.Nm ops'' -> ``.Fa ops'' ``.Va fd'' -> ``.Fa fd'' 2000-06-23 05:05:44 +00:00			`.Fa timeout`
``NULL is a specific instance of a null pointer constant; the generic is a "null pointer".'' Making good use of the excellent explanations sent to me by Ruslan Ermilov, Garrett Wollman and Bruce Evans, correct the descriptions of null pointers. They are just "null pointers", not nil, not NULL or ".Dv NULL". Suggested by: ru, wollman, bde Reviewed by: ru, wollman Pointy hat: keramida 2004-12-23 23:45:25 +00:00			`is a null pointer, the suspend blocks indefinitely.`
Mechanically kill hard sentence breaks. 2004-07-02 23:52:20 +00:00			`To effect a`
Correct the description of the timeout argument. I've examined the code, which seems to implement the POSIX requirements, and have described the behavior here. Basically, it behaves the same as select(2). Noticed by: John Polstra 1999-10-09 01:35:58 +00:00			`poll, the`
Replace .Va, .Ar and .Nm with .Fa or .Va where necessary, examples: ``.Ar errno'' -> ``.Va errno'' ``.Nm ops'' -> ``.Fa ops'' ``.Va fd'' -> ``.Fa fd'' 2000-06-23 05:05:44 +00:00			`.Fa timeout`
Correct the description of the timeout argument. I've examined the code, which seems to implement the POSIX requirements, and have described the behavior here. Basically, it behaves the same as select(2). Noticed by: John Polstra 1999-10-09 01:35:58 +00:00			`should point to a zero-value timespec structure.`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Sh RETURN VALUES`
Fixed the description of when and why aio_suspend returns. Also spelled out the return values and conditions a little better. Noticed by: John Polstra <jdp@polstra.com> 1999-09-20 18:30:55 +00:00			`If one or more of the specified asynchronous I/O requests have`
			`completed,`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Fn aio_suspend`
Mechanically kill hard sentence breaks. 2004-07-02 23:52:20 +00:00			`returns 0.`
			`Otherwise it returns -1 and sets`
Fixed the description of when and why aio_suspend returns. Also spelled out the return values and conditions a little better. Noticed by: John Polstra <jdp@polstra.com> 1999-09-20 18:30:55 +00:00			`.Va errno`
			`to indicate the error, as enumerated below.`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Sh ERRORS`
			`The`
			`.Fn aio_suspend`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call will fail if:`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Bl -tag -width Er`
Fixed the description of when and why aio_suspend returns. Also spelled out the return values and conditions a little better. Noticed by: John Polstra <jdp@polstra.com> 1999-09-20 18:30:55 +00:00			`.It Bq Er EAGAIN`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`the`
Replace .Va, .Ar and .Nm with .Fa or .Va where necessary, examples: ``.Ar errno'' -> ``.Va errno'' ``.Nm ops'' -> ``.Fa ops'' ``.Va fd'' -> ``.Fa fd'' 2000-06-23 05:05:44 +00:00			`.Fa timeout`
Fixed the description of when and why aio_suspend returns. Also spelled out the return values and conditions a little better. Noticed by: John Polstra <jdp@polstra.com> 1999-09-20 18:30:55 +00:00			`expired before any I/O requests completed.`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.It Bq Er EINVAL`
mdoc(7) police: "The .Fa argument.". 2002-12-19 09:40:28 +00:00			`The`
Replace .Va, .Ar and .Nm with .Fa or .Va where necessary, examples: ``.Ar errno'' -> ``.Va errno'' ``.Nm ops'' -> ``.Fa ops'' ``.Va fd'' -> ``.Fa fd'' 2000-06-23 05:05:44 +00:00			`.Fa iocbs`
mdoc(7) police: "The .Fa argument.". 2002-12-19 09:40:28 +00:00			`argument`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`contains more than`
Fixed a typo (well, format-o) in yesterday's edits. Spotted by: John Polstra <jdp@polstra.com> (again) 1999-09-21 17:30:43 +00:00			`.Dv AIO_LISTIO_MAX`
			`asynchronous I/O requests, or at least one of the requests is not`
			`valid.`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.It Bq Er EINTR`
			`the suspend was interrupted by a signal.`
			`.El`
Explain to users that they may want to kldload aio. Move Xref sections. Submitted by: Craig Rodrigues <rodrigc@attbi.com> 2002-10-22 16:12:27 +00:00			`.Sh SEE ALSO`
			`.Xr aio_cancel 2 ,`
			`.Xr aio_error 2 ,`
			`.Xr aio_return 2 ,`
			`.Xr aio_waitcomplete 2 ,`
			`.Xr aio_write 2 ,`
* Modernize aio(4), providing instructions for static and dynamic kernel linking. * Fix disorder in the SEE ALSO sections of aio_(2). Remove unnecessary cross-references from the SEE ALSO sections of aio_(2); config(8), kldload(8) and kldunload(8) are cross-referenced from aio(4). Remove the KERNEL OPTIONS sections from aio_*(2), now that these pages cross-reference aio(4), which contains suitable kernel linking reference material. 2002-10-24 12:57:05 +00:00			`.Xr aio 4`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Sh STANDARDS`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`The`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Fn aio_suspend`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`is expected to conform to the`
Refer to 1003.1 instead of 1003.2 in the Standards section. 2003-01-13 10:37:11 +00:00			`.St -p1003.1`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`standard.`
			`.Sh HISTORY`
			`The`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`.Fn aio_suspend`
			`system call first appeared in`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`.Fx 3.0 .`
Various man page cleanup: - Sort xrefs - FreeBSD.ORG -> FreeBSD.org - Be consistent with section names as outlines in mdoc(7) - Other misc mdoc cleanup. PR: doc/13144 Submitted by: Alexy M. Zelkin <phantom@cris.net> 1999-08-15 09:51:25 +00:00			`.Sh AUTHORS`
Add mising aio_* man pages. Fixed a minor typo in aio_read.2, and "corrected" statement of Posix conformance. 1999-07-01 19:58:12 +00:00			`This`
			`manual page was written by`
			`.An Wes Peters Aq wes@softweyr.com .`