lib/librt/aio_fsync.3

   1 .\" $NetBSD: aio_fsync.3,v 1.4 2009/03/10 13:23:39 joerg Exp $
   2 .\"
   3 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  16 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  19 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\" POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd June 17, 2007
  28 .Dt AIO_FSYNC 3
  29 .Os
  30 .Sh NAME
  31 .Nm aio_fsync
  32 .Nd asynchronous data synchronization of file (REALTIME)
  33 .Sh LIBRARY
  34 .Lb librt
  35 .Sh SYNOPSIS
  36 .In aio.h
  37 .Ft int
  38 .Fn aio_fsync "int op" "struct aiocb *aiocbp"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn aio_fsync
  42 system call allows the calling process to force all modified data
  43 associated with the file descriptor
  44 .Fa aiocbp-\*[Gt]aio_fildes
  45 to be flushed to the stable storage device.
  46 The call returns immediately after the synchronization request has been
  47 enqueued to the descriptor; the synchronization may or may not have
  48 completed at the time the call returns.
  49 If the request could not be enqueued, generally due to invalid arguments,
  50 the call returns without having enqueued the request.
  51 .Pp
  52 The
  53 .Fa op
  54 argument could be set only to
  55 .Dv O_DSYNC
  56 or
  57 .Dv O_SYNC .
  58 If
  59 .Fa op
  60 is
  61 .Dv O_DSYNC ,
  62 then
  63 .Fn aio_fsync
  64 does the same as a
  65 .Fn fdatasync
  66 call, if
  67 .Dv O_SYNC ,
  68 then the same as
  69 .Fn fsync .
  70 .Pp
  71 If
  72 .Dv _POSIX_PRIORITIZED_IO
  73 is defined, and the descriptor supports it, then the enqueued
  74 operation is submitted at a priority equal to that of the calling
  75 process minus
  76 .Fa aiocbp-\*[Gt]aio_reqprio .
  77 .Pp
  78 The
  79 .Fa aiocbp
  80 pointer may be subsequently used as an argument to
  81 .Fn aio_return
  82 and
  83 .Fn aio_error
  84 in order to determine return or error status for the enqueued operation
  85 while it is in progress.
  86 .Sh RESTRICTIONS
  87 The asynchronous I/O control buffer
  88 .Fa aiocbp
  89 should be zeroed before the
  90 .Fn aio_fsync
  91 system call to avoid passing bogus context information to the kernel.
  92 .Pp
  93 Modifications of the Asynchronous I/O Control Block structure after
  94 the request has been enqueued, but before the request has completed,
  95 are not allowed.
  96 .Sh RETURN VALUES
  97 .Rv -std aio_fsync
  98 .Sh ERRORS
  99 The
 100 .Fn aio_fsync
 101 system call will fail if:
 102 .Bl -tag -width Er
 103 .It Bq Er EAGAIN
 104 The request was not queued because of system resource limitations.
 105 .El
 106 .Pp
 107 The following conditions may be synchronously detected when the
 108 .Fn aio_fsync
 109 system call is made, or asynchronously, at any time thereafter.
 110 If they are detected at call time,
 111 .Fn aio_fsync
 112 returns \-1 and sets
 113 .Va errno
 114 appropriately; otherwise the
 115 .Fn aio_return
 116 system call must be called, and will return \-1, and
 117 .Fn aio_error
 118 must be called to determine the actual value that would have been
 119 returned in
 120 .Va errno .
 121 .Bl -tag -width Er
 122 .It Bq Er EBADF
 123 The
 124 .Fa aiocbp-\*[Gt]aio_fildes
 125 is invalid for writing.
 126 .It Bq Er EINVAL
 127 This implementation does not support synchronized I/O for this file,
 128 or the
 129 .Fa op
 130 argument is neither set to
 131 .Dv O_DSYNC
 132 nor
 133 .Dv O_SYNC .
 134 .El
 135 .Sh SEE ALSO
 136 .Xr fcntl 2 ,
 137 .Xr fdatasync 2 ,
 138 .Xr fsync 2 ,
 139 .Xr aio_error 3 ,
 140 .Xr aio_read 3 ,
 141 .Xr aio_write 3
 142 .Sh STANDARDS
 143 The
 144 .Fn aio_fsync
 145 system call is expected to conform to the
 146 .St -p1003.1-2001
 147 standard.
 148 .Sh HISTORY
 149 The
 150 .Fn aio_fsync
 151 system call first appeared in
 152 .Nx 5.0 .