[apple/xnu.git] / bsd / man / man2 / 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: src/lib/libc/sys/aio_suspend.2,v 1.19 2003/01/13 10:37:11 tjr Exp $
.\"
.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
.Fo aio_suspend
.Fa "const struct aiocb *const list[]"
.Fa "int nent"
.Fa "const struct timespec *timeout"
.Fc
.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 list
argument
is an array of
.Fa nent
pointers to asynchronous I/O requests.  Array members containing
NULL will be silently ignored.
.Pp
If
.Fa timeout
is a non-nil pointer, it specifies a maximum interval to suspend.
If
.Fa timeout
is a nil 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 of the listed I/O requests completed.
.\" ==========
.It Bq Er EINTR
The suspend was interrupted by a signal.
.\" ==========
.It Bq Er EINVAL
The
.Fa list
argument
contains more than
.Dv AIO_LISTIO_MAX
asynchronous I/O requests, or at least one of the requests is not
valid.
.El
.Sh SEE ALSO
.Xr aio_cancel 2 ,
.Xr aio_error 2 ,
.Xr aio_return 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 .
Commit	Line	Data
91447636 A	1	.\" Copyright (c) 1999 Softweyr LLC.
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE
	17	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	18	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	19	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	20	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	21	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	22	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	23	.\" SUCH DAMAGE.
	24	.\"
	25	.\" $FreeBSD: src/lib/libc/sys/aio_suspend.2,v 1.19 2003/01/13 10:37:11 tjr Exp $
	26	.\"
	27	.Dd June 2, 1999
	28	.Dt AIO_SUSPEND 2
	29	.Os
	30	.Sh NAME
	31	.Nm aio_suspend
	32	.Nd suspend until asynchronous I/O operations or timeout complete (REALTIME)
	33	.Sh LIBRARY
	34	.Lb libc
	35	.Sh SYNOPSIS
	36	.In aio.h
	37	.Ft int
2d21ac55 A	38	.Fo aio_suspend
	39	.Fa "const struct aiocb *const list[]"
	40	.Fa "int nent"
	41	.Fa "const struct timespec *timeout"
	42	.Fc
91447636 A	43	.Sh DESCRIPTION
	44	The
	45	.Fn aio_suspend
	46	system call suspends the calling process until at least one of the
	47	specified asynchronous I/O requests have completed, a signal is
	48	delivered, or the
	49	.Fa timeout
	50	has passed.
	51	.Pp
	52	The
2d21ac55	53	.Fa list
91447636 A	54	argument
91447636 A	55	is an array of
2d21ac55	56	.Fa nent
91447636 A	57	pointers to asynchronous I/O requests. Array members containing
	58	NULL will be silently ignored.
	59	.Pp
	60	If
	61	.Fa timeout
	62	is a non-nil pointer, it specifies a maximum interval to suspend.
	63	If
	64	.Fa timeout
	65	is a nil pointer, the suspend blocks indefinitely. To effect a
	66	poll, the
	67	.Fa timeout
	68	should point to a zero-value timespec structure.
	69	.Sh RETURN VALUES
2d21ac55	70	If one or more of the specified asynchronous I/O requests have completed,
91447636	71	.Fn aio_suspend
2d21ac55 A	72	returns 0.
2d21ac55 A	73	Otherwise, it returns -1 and sets
91447636 A	74	.Va errno
	75	to indicate the error, as enumerated below.
	76	.Sh ERRORS
	77	The
	78	.Fn aio_suspend
	79	system call will fail if:
	80	.Bl -tag -width Er
	81	.It Bq Er EAGAIN
2d21ac55	82	The
91447636	83	.Fa timeout
2d21ac55 A	84	expired before any of the listed I/O requests completed.
	85	.\" ==========
	86	.It Bq Er EINTR
	87	The suspend was interrupted by a signal.
	88	.\" ==========
91447636 A	89	.It Bq Er EINVAL
91447636 A	90	The
2d21ac55	91	.Fa list
91447636 A	92	argument
	93	contains more than
	94	.Dv AIO_LISTIO_MAX
	95	asynchronous I/O requests, or at least one of the requests is not
	96	valid.
91447636 A	97	.El
	98	.Sh SEE ALSO
	99	.Xr aio_cancel 2 ,
	100	.Xr aio_error 2 ,
	101	.Xr aio_return 2 ,
	102	.Xr aio_write 2 ,
	103	.Xr aio 4
	104	.Sh STANDARDS
	105	The
	106	.Fn aio_suspend
	107	system call
	108	is expected to conform to the
	109	.St -p1003.1
	110	standard.
	111	.Sh HISTORY
	112	The
	113	.Fn aio_suspend
	114	system call first appeared in
	115	.Fx 3.0 .
	116	.Sh AUTHORS
	117	This
	118	manual page was written by
	119	.An Wes Peters Aq wes@softweyr.com .