Debian Codegraph @

upstream/debian-trixie/man3/aio_suspend.3

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