original/man2/io_cancel.2

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