Debian Codegraph @

upstream/debian-unstable/man3/aio_suspend.3

raw
1 '\" t
2 .\" Copyright 2003, Andries E. Brouwer <[email protected]>
3 .\" Copyright 2010, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .\"
8 .TH aio_suspend 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 aio_suspend \- wait for asynchronous I/O operation or timeout
11 .SH LIBRARY
12 Real-time library
13 .RI ( librt ,\~ \-lrt )
14 .SH SYNOPSIS
15 .nf
16 .P
17 .B "#include <aio.h>"
18 .P
19 .BR "int aio_suspend(" "int n;"
20 .BI " const struct aiocb *const " aiocb_list [ n "], int " n ,
21 .BI " const struct timespec *restrict " timeout );
22 .fi
23 .SH DESCRIPTION
24 The
25 .BR aio_suspend ()
26 function suspends the calling thread until one of the following occurs:
27 .IP \[bu] 3
28 One or more of the asynchronous I/O requests in the list
29 .I aiocb_list
30 has completed.
31 .IP \[bu]
32 A signal is delivered.
33 .IP \[bu]
34 .I timeout
35 is not NULL and the specified time interval has passed.
36 (For details of the
37 .I timespec
38 structure, see
39 .BR nanosleep (2).)
40 .P
41 The
42 .I n
43 argument specifies the number of items in
44 .IR aiocb_list .
45 Each item in the list pointed to by
46 .I aiocb_list
47 must be either NULL (and then is ignored),
48 or a pointer to a control block on which I/O was initiated using
49 .BR aio_read (3),
50 .BR aio_write (3),
51 or
52 .BR lio_listio (3).
53 (See
54 .BR aio (7)
55 for a description of the
56 .I aiocb
57 structure.)
58 .P
59 If
60 .B CLOCK_MONOTONIC
61 is supported, this clock is used to measure
62 the timeout interval (see
63 .BR clock_gettime (2)).
64 .SH RETURN VALUE
65 If this function returns after completion of one of the I/O
66 requests specified in
67 .IR aiocb_list ,
68 0 is returned.
69 Otherwise, \-1 is returned, and
70 .I errno
71 is set to indicate the error.
72 .SH ERRORS
73 .TP
74 .B EAGAIN
75 The call timed out before any of the indicated operations
76 had completed.
77 .TP
78 .B EINTR
79 The call was ended by signal
80 (possibly the completion signal of
81 one of the operations we were waiting for);
82 see
83 .BR signal (7).
84 .TP
85 .B ENOSYS
86 .BR aio_suspend ()
87 is not implemented.
88 .SH ATTRIBUTES
89 For an explanation of the terms used in this section, see
90 .BR attributes (7).
91 .TS
92 allbox;
93 lbx lb lb
94 l l l.
95 Interface Attribute Value
96 T{
97 .na
98 .nh
99 .BR aio_suspend ()
100 T} Thread safety MT-Safe
101 .TE
102 .SH STANDARDS
103 POSIX.1-2008.
104 .SH HISTORY
105 glibc 2.1.
106 POSIX.1-2001.
107 .P
108 POSIX doesn't specify the parameters to be
109 .IR restrict ;
110 that is specific to glibc.
111 .SH NOTES
112 One can achieve polling by using a non-NULL
113 .I timeout
114 that specifies a zero time interval.
115 .P
116 If one or more of the asynchronous I/O operations specified in
117 .I aiocb_list
118 has already completed at the time of the call to
119 .BR aio_suspend (),
120 then the call returns immediately.
121 .P
122 To determine which I/O operations have completed
123 after a successful return from
124 .BR aio_suspend (),
125 use
126 .BR aio_error (3)
127 to scan the list of
128 .I aiocb
129 structures pointed to by
130 .IR aiocb_list .
131 .SH BUGS
132 The glibc implementation of
133 .BR aio_suspend ()
134 is not async-signal-safe,
135 .\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172
136 in violation of the requirements of POSIX.1.
137 .SH SEE ALSO
138 .BR aio_cancel (3),
139 .BR aio_error (3),
140 .BR aio_fsync (3),
141 .BR aio_read (3),
142 .BR aio_return (3),
143 .BR aio_write (3),
144 .BR lio_listio (3),
145 .BR aio (7),
146 .BR time (7)