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