lib/libc/sys/aio_waitcomplete.2

   1 .\" Copyright (c) 1999 Christopher M Sedore.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libc/sys/aio_waitcomplete.2,v 1.1.2.6 2001/12/14 18:34:00 ru Exp $
  26 .\" $DragonFly: src/lib/libc/sys/aio_waitcomplete.2,v 1.3 2004/03/11 12:28:51 hmp Exp $
  27 .\"
  28 .Dd January 19, 2000
  29 .Dt AIO_WAITCOMPLETE 2
  30 .Os
  31 .Sh NAME
  32 .Nm aio_waitcomplete
  33 .Nd wait for the next completion of an aio request
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In aio.h
  38 .Ft int
  39 .Fn aio_waitcomplete "struct aiocb **iocbp" "struct timespec *timeout"
  40 .Sh DESCRIPTION
  41 The
  42 .Fn aio_waitcomplete
  43 function waits for completion of an asynchronous I/O request.
  44 Upon completion,
  45 .Fn aio_waitcomplete
  46 returns the result of the function and sets
  47 .Fa iocbp
  48 to point to the structure associated with the original request.
  49 If an asynchronous I/O request is completed before
  50 .Fn aio_waitcomplete
  51 is called, it returns immediately with the completed request.
  52 .Pp
  53 If
  54 .Fa timeout
  55 is a non-NULL pointer, it specifies a maximum interval to wait for a
  56 asynchronous I/O request to complete.
  57 If
  58 .Fa timeout
  59 is a NULL pointer,
  60 .Fn aio_waitcomplete
  61 waits indefinitely.
  62 To effect a poll, the
  63 .Fa timeout
  64 argument should be non-NULL, pointing to a zero-valued timeval structure.
  65 .Pp
  66 The
  67 .Fn aio_waitcomplete
  68 function also serves the function of
  69 .Fn aio_return ,
  70 thus
  71 .Fn aio_return
  72 should not be called for the control block returned in
  73 .Fa iocbp .
  74 .Sh RETURN VALUES
  75 If an asynchronous I/O request has completed,
  76 .Fa iocbp
  77 is set to point to the control block passed with the original request,
  78 and the status is returned as described in
  79 .Xr read 2 ,
  80 .Xr write 2 ,
  81 or
  82 .Xr fsync 2 .
  83 On failure,
  84 .Fn aio_waitcomplete
  85 returns
  86 .Dv -1 ,
  87 sets iocbp to
  88 .Dv NULL
  89 and sets
  90 .Va errno
  91 to indicate the error condition.
  92 .Sh ERRORS
  93 The
  94 .Fn aio_waitcomplete
  95 function fails if:
  96 .Bl -tag -width Er
  97 .It Bq Er EINVAL
  98 The specified time limit is invalid.
  99 .It Bq Er EAGAIN
 100 The process has not yet called
 101 .Fn aio_read
 102 or
 103 .Fn aio_write .
 104 .It Bq Er EINTR
 105 A signal was delivered before the timeout expired and before any
 106 asynchronous I/O requests completed.
 107 .It Bq Er EWOULDBLOCK
 108 .It Bq Er EINPROGRESS
 109 The specified time limit expired before any asynchronous I/O requests
 110 completed.
 111 .El
 112 .Sh SEE ALSO
 113 .Xr aio_cancel 2 ,
 114 .Xr aio_error 2 ,
 115 .Xr aio_read 2 ,
 116 .Xr aio_return 2 ,
 117 .Xr aio_suspend 2 ,
 118 .Xr aio_write 2 ,
 119 .Xr fsync 2 ,
 120 .Xr read 2 ,
 121 .Xr write 2
 122 .Sh STANDARDS
 123 The
 124 .Fn aio_waitcomplete
 125 function is specific to
 126 .Fx
 127 and
 128 .Dx .
 129 .Sh HISTORY
 130 The
 131 .Fn aio_waitcomplete
 132 function first appeared in
 133 .Fx 4.0 .
 134 .Sh AUTHORS
 135 The
 136 .Fn aio_waitcomplete
 137 function and this manual page were written by
 138 .An Christopher M Sedore Aq cmsedore@maxwell.syr.edu .