man3/aio_cancel.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .TH AIO_CANCEL 3 2021-03-22  "" "Linux Programmer's Manual"
  25 .SH NAME
  26 aio_cancel \- cancel an outstanding asynchronous I/O request
  27 .SH SYNOPSIS
  28 .nf
  29 .B "#include <aio.h>"
  30 .PP
  31 .BI "int aio_cancel(int " fd ", struct aiocb *" aiocbp );
  32 .PP
  33 Link with \fI\-lrt\fP.
  34 .fi
  35 .SH DESCRIPTION
  36 The
  37 .BR aio_cancel ()
  38 function attempts to cancel outstanding asynchronous I/O requests
  39 for the file descriptor
  40 .IR fd .
  41 If
  42 .I aiocbp
  43 is NULL, all such requests are canceled.
  44 Otherwise, only the request
  45 described by the control block pointed to by
  46 .I aiocbp
  47 is canceled.
  48 (See
  49 .BR aio (7)
  50 for a description of the
  51 .I aiocb
  52 structure.)
  53 .PP
  54 Normal asynchronous notification occurs for canceled requests (see
  55 .BR aio (7)
  56 and
  57 .BR sigevent (7)).
  58 The request return status
  59 .RB ( aio_return (3))
  60 is set to \-1, and the request error status
  61 .RB ( aio_error (3))
  62 is set to
  63 .BR ECANCELED .
  64 The control block of requests that cannot be canceled is not changed.
  65 .PP
  66 If the request could not be canceled,
  67 then it will terminate in the usual way after performing the I/O operation.
  68 (In this case,
  69 .BR aio_error (3)
  70 will return the status
  71 .BR EINPROGRESSS .)
  72 .PP
  73 If
  74 .I aiocbp
  75 is not NULL, and
  76 .I fd
  77 differs from the file descriptor with which the asynchronous operation
  78 was initiated, unspecified results occur.
  79 .PP
  80 Which operations are cancelable is implementation-defined.
  81 .\" FreeBSD: not those on raw disk devices.
  82 .SH RETURN VALUE
  83 The
  84 .BR aio_cancel ()
  85 function returns one of the following values:
  86 .TP
  87 .B AIO_CANCELED
  88 All requests were successfully canceled.
  89 .TP
  90 .B AIO_NOTCANCELED
  91 At least one of the
  92 requests specified was not canceled because it was in progress.
  93 In this case, one may check the status of individual requests using
  94 .BR aio_error (3).
  95 .TP
  96 .B AIO_ALLDONE
  97 All requests had already been completed before the call.
  98 .TP
  99 \-1
 100 An error occurred.
 101 The cause of the error can be found by inspecting
 102 .IR errno .
 103 .SH ERRORS
 104 .TP
 105 .B EBADF
 106 .I fd
 107 is not a valid file descriptor.
 108 .TP
 109 .B ENOSYS
 110 .BR aio_cancel ()
 111 is not implemented.
 112 .SH VERSIONS
 113 The
 114 .BR aio_cancel ()
 115 function is available since glibc 2.1.
 116 .SH ATTRIBUTES
 117 For an explanation of the terms used in this section, see
 118 .BR attributes (7).
 119 .ad l
 120 .nh
 121 .TS
 122 allbox;
 123 lbx lb lb
 124 l l l.
 125 Interface       Attribute       Value
 126 T{
 127 .BR aio_cancel ()
 128 T}      Thread safety   MT-Safe
 129 .TE
 130 .hy
 131 .ad
 132 .sp 1
 133 .SH CONFORMING TO
 134 POSIX.1-2001, POSIX.1-2008.
 135 .SH EXAMPLES
 136 See
 137 .BR aio (7).
 138 .SH SEE ALSO
 139 .BR aio_error (3),
 140 .BR aio_fsync (3),
 141 .BR aio_read (3),
 142 .BR aio_return (3),
 143 .BR aio_suspend (3),
 144 .BR aio_write (3),
 145 .BR lio_listio (3),
 146 .BR aio (7)