manual/LDP_man-pages/original/man2/io_cancel.2

   1 .\" Copyright (C) 2003 Free Software Foundation, Inc.
   2 .\"
   3 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   4 .\" This file is distributed according to the GNU General Public License.
   5 .\" %%%LICENSE_END
   6 .\"
   7 .TH IO_CANCEL 2 2020-12-21 "Linux" "Linux Programmer's Manual"
   8 .SH NAME
   9 io_cancel \- cancel an outstanding asynchronous I/O operation
  10 .SH SYNOPSIS
  11 .nf
  12 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
  13 .PP
  14 .BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
  15 .BI "              struct io_event *" result );
  16 .fi
  17 .PP
  18 .IR Note :
  19 There is no glibc wrapper for this system call; see NOTES.
  20 .SH DESCRIPTION
  21 .IR Note :
  22 this page describes the raw Linux system call interface.
  23 The wrapper function provided by
  24 .I libaio
  25 uses a different type for the
  26 .I ctx_id
  27 argument.
  28 See NOTES.
  29 .PP
  30 The
  31 .BR io_cancel ()
  32 system call
  33 attempts to cancel an asynchronous I/O operation previously submitted with
  34 .BR io_submit (2).
  35 The
  36 .I iocb
  37 argument describes the operation to be canceled and the
  38 .I ctx_id
  39 argument is the AIO context to which the operation was submitted.
  40 If the operation is successfully canceled, the event will be copied into
  41 the memory pointed to by
  42 .I result
  43 without being placed into the
  44 completion queue.
  45 .SH RETURN VALUE
  46 On success,
  47 .BR io_cancel ()
  48 returns 0.
  49 For the failure return, see NOTES.
  50 .SH ERRORS
  51 .TP
  52 .B EAGAIN
  53 The \fIiocb\fP specified was not canceled.
  54 .TP
  55 .B EFAULT
  56 One of the data structures points to invalid data.
  57 .TP
  58 .B EINVAL
  59 The AIO context specified by \fIctx_id\fP is invalid.
  60 .TP
  61 .B ENOSYS
  62 .BR io_cancel ()
  63 is not implemented on this architecture.
  64 .SH VERSIONS
  65 The asynchronous I/O system calls first appeared in Linux 2.5.
  66 .SH CONFORMING TO
  67 .BR io_cancel ()
  68 is Linux-specific and should not be used
  69 in programs that are intended to be portable.
  70 .SH NOTES
  71 Glibc does not provide a wrapper function for this system call.
  72 You could invoke it using
  73 .BR syscall (2).
  74 But instead, you probably want to use the
  75 .BR io_cancel ()
  76 wrapper function provided by
  77 .\" http://git.fedorahosted.org/git/?p=libaio.git
  78 .IR libaio .
  79 .PP
  80 Note that the
  81 .I libaio
  82 wrapper function uses a different type
  83 .RI ( io_context_t )
  84 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
  85 .\" the system call.
  86 for the
  87 .I ctx_id
  88 argument.
  89 Note also that the
  90 .I libaio
  91 wrapper does not follow the usual C library conventions for indicating errors:
  92 on error it returns a negated error number
  93 (the negative of one of the values listed in ERRORS).
  94 If the system call is invoked via
  95 .BR syscall (2),
  96 then the return value follows the usual conventions for
  97 indicating an error: \-1, with
  98 .I errno
  99 set to a (positive) value that indicates the error.
 100 .SH SEE ALSO
 101 .BR io_destroy (2),
 102 .BR io_getevents (2),
 103 .BR io_setup (2),
 104 .BR io_submit (2),
 105 .BR aio (7)
 106 .\" .SH AUTHOR
 107 .\" Kent Yoder.
 108 .SH COLOPHON
 109 This page is part of release 5.10 of the Linux
 110 .I man-pages
 111 project.
 112 A description of the project,
 113 information about reporting bugs,
 114 and the latest version of this page,
 115 can be found at
 116 \%https://www.kernel.org/doc/man\-pages/.