man3/aio_suspend.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\" and Copyright (C) 2010 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH AIO_SUSPEND 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
   7 .SH NAME
   8 aio_suspend \- wait for asynchronous I/O operation or timeout
   9 .SH LIBRARY
  10 Real-time library
  11 .RI ( librt ", " \-lrt )
  12 .SH SYNOPSIS
  13 .nf
  14 .PP
  15 .B "#include <aio.h>"
  16 .PP
  17 .BI "int aio_suspend(const struct aiocb *const " aiocb_list "[], int " nitems ,
  18 .BI "                const struct timespec *restrict " timeout );
  19 .fi
  20 .SH DESCRIPTION
  21 The
  22 .BR aio_suspend ()
  23 function suspends the calling thread until one of the following occurs:
  24 .IP * 3
  25 One or more of the asynchronous I/O requests in the list
  26 .I aiocb_list
  27 has completed.
  28 .IP *
  29 A signal is delivered.
  30 .IP *
  31 .I timeout
  32 is not NULL and the specified time interval has passed.
  33 (For details of the
  34 .I timespec
  35 structure, see
  36 .BR nanosleep (2).)
  37 .PP
  38 The
  39 .I nitems
  40 argument specifies the number of items in
  41 .IR aiocb_list .
  42 Each item in the list pointed to by
  43 .I aiocb_list
  44 must be either NULL (and then is ignored),
  45 or a pointer to a control block on which I/O was initiated using
  46 .BR aio_read (3),
  47 .BR aio_write (3),
  48 or
  49 .BR lio_listio (3).
  50 (See
  51 .BR aio (7)
  52 for a description of the
  53 .I aiocb
  54 structure.)
  55 .PP
  56 If
  57 .B CLOCK_MONOTONIC
  58 is supported, this clock is used to measure
  59 the timeout interval (see
  60 .BR clock_gettime (2)).
  61 .SH RETURN VALUE
  62 If this function returns after completion of one of the I/O
  63 requests specified in
  64 .IR aiocb_list ,
  65 0 is returned.
  66 Otherwise, \-1 is returned, and
  67 .I errno
  68 is set to indicate the error.
  69 .SH ERRORS
  70 .TP
  71 .B EAGAIN
  72 The call timed out before any of the indicated operations
  73 had completed.
  74 .TP
  75 .B EINTR
  76 The call was ended by signal
  77 (possibly the completion signal of one of the operations we were
  78 waiting for); see
  79 .BR signal (7).
  80 .TP
  81 .B ENOSYS
  82 .BR aio_suspend ()
  83 is not implemented.
  84 .SH VERSIONS
  85 The
  86 .BR aio_suspend ()
  87 function is available since glibc 2.1.
  88 .SH ATTRIBUTES
  89 For an explanation of the terms used in this section, see
  90 .BR attributes (7).
  91 .ad l
  92 .nh
  93 .TS
  94 allbox;
  95 lbx lb lb
  96 l l l.
  97 Interface       Attribute       Value
  98 T{
  99 .BR aio_suspend ()
 100 T}      Thread safety   MT-Safe
 101 .TE
 102 .hy
 103 .ad
 104 .sp 1
 105 .SH STANDARDS
 106 POSIX.1-2001, POSIX.1-2008.
 107 .PP
 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 .PP
 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 .PP
 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)