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$
  26 .\"
  27 .Dd January 19, 2000
  28 .Dt AIO_WAITCOMPLETE 2
  29 .Os
  30 .Sh NAME
  31 .Nm aio_waitcomplete
  32 .Nd wait for the next completion of an aio request
  33 .Sh SYNOPSIS
  34 .Fd #include <aio.h>
  35 .Ft int
  36 .Fn aio_waitcomplete "struct aiocb **iocbp, struct timespec *timeout"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn aio_waitcomplete
  40 function waits for completion of an asynchronous I/O request.  Upon completion,
  41 .Fn aio_waitcomplete
  42 returns the result of the function and sets
  43 .Ar iocbp
  44 to point to the structure associated with the original request. If an
  45 asynchronous I/O request is completed before
  46 .Fn aio_waitcomplete
  47 is called, it returns immediately with the completed request.
  48 .Pp
  49 If
  50 .Ar timeout
  51 is a non-NULL pointer, it specifies a maximum interval to wait for a
  52 asynchronous I/O request to complete.  If
  53 .Ar timeout
  54 is a NULL pointer,
  55 .Fn aio_waitcomplete
  56 waits indefinitely.  To effect a poll, the
  57 .Ar timeout
  58 argument should be non-NULL, pointing to a zero-valued timeval structure.
  59 .Pp
  60 The
  61 .Fn aio_waitcomplete
  62 function also serves the function of
  63 .Fn aio_return ,
  64 thus
  65 .Fn aio_return
  66 should not be called for the control block returned in
  67 .Ar iocbp .
  68 .Sh RETURN VALUES
  69 If an asynchronous I/O request has completed,
  70 .Ar iocbp
  71 is set to point to the control block passed with the original request, and
  72 the status is returned as described in
  73 .Xr read 2 ,
  74 .Xr write 2 ,
  75 or
  76 .Xr fsync 2 .
  77 On failure,
  78 .Fn aio_waitcomplete
  79 returns
  80 .Dv -1 ,
  81 sets iocbp to
  82 .Dv NULL
  83 and
  84 .Dv errno
  85 to indicate the error condition.
  86 .Sh ERRORS
  87 The
  88 .Fn aio_waitcomplete
  89 function fails if:
  90 .Bl -tag -width Er
  91 .It Bq Er EINVAL
  92 The specified time limit is invalid.
  93 .It Bq Er EAGAIN
  94 The process has not yet called
  95 .Fn aio_read
  96 or
  97 .Fn aio_write .
  98 .It Bq Er EINTR
  99 A signal was delivered before the timeout expired and before any
 100 asynchronous I/O requests completed.
 101 .It Bq Er EWOULDBLOCK
 102 .It Bq Er EINPROGRESS
 103 The specified time limit expired before any asynchronous I/O requests
 104 completed.
 105 .El
 106 .Sh SEE ALSO
 107 .Xr aio_cancel 2 ,
 108 .Xr aio_error 2 ,
 109 .Xr aio_read 2 ,
 110 .Xr aio_return 2 ,
 111 .Xr aio_suspend 2 ,
 112 .Xr aio_write 2 ,
 113 .Xr fsync 2 ,
 114 .Xr read 2 ,
 115 .Xr write 2 .
 116 .Sh STANDARDS
 117 The
 118 .Fn aio_waitcomplete
 119 function is a FreeBSD-specific extension.
 120 .Sh HISTORY
 121 The
 122 .Fn aio_waitcomplete
 123 function first appeared in
 124 .Fx 4.0 .
 125 .Sh AUTHORS
 126 The
 127 .Fn aio_waitcomplete
 128 function and this manual page were written by
 129 .An Christopher M Sedore Aq cmsedore@maxwell.syr.edu .