man2/io_cancel.2

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