NetBSD-5.0.2/lib/librt/aio_fsync.3

.\" $NetBSD: aio_fsync.3,v 1.3 2008/04/30 13:10:52 martin Exp $
.\"
.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 17, 2007
.Dt AIO_FSYNC 3
.Os
.Sh NAME
.Nm aio_fsync
.Nd asynchronous data synchronization of file (REALTIME)
.Sh LIBRARY
.Lb librt
.Sh SYNOPSIS
.In aio.h
.Ft int
.Fn aio_fsync "int op" "struct aiocb *aiocbp"
.Sh DESCRIPTION
The
.Fn aio_fsync
system call allows the calling process to force all modified data
associated with the file descriptor
.Fa aiocbp-\*[Gt]aio_fildes
to be flushed to the stable storage device.
The call returns immediately after the synchronization request has been
enqueued to the descriptor; the synchronization may or may not have
completed at the time the call returns.
If the request could not be enqueued, generally due to invalid arguments,
the call returns without having enqueued the request.
.Pp
The
.Fa op
argument could be set only to
.Dv O_DSYNC
or
.Dv O_SYNC .
If
.Fa op
is
.Dv O_DSYNC ,
then
.Fn aio_fsync
does the same as a
.Fn fdatasync
call, if
.Dv O_SYNC ,
then the same as
.Fn fsync .
.Pp
If
.Dv _POSIX_PRIORITIZED_IO
is defined, and the descriptor supports it, then the enqueued
operation is submitted at a priority equal to that of the calling
process minus
.Fa aiocbp-\*[Gt]aio_reqprio .
.Pp
The
.Fa aiocbp
pointer may be subsequently used as an argument to
.Fn aio_return
and
.Fn aio_error
in order to determine return or error status for the enqueued operation
while it is in progress.
.Sh RESTRICTIONS
The asynchronous I/O control buffer
.Fa aiocbp
should be zeroed before the
.Fn aio_fsync
system call to avoid passing bogus context information to the kernel.
.Pp
Modifications of the Asynchronous I/O Control Block structure after
the request has been enqueued, but before the request has completed,
are not allowed.
.Sh RETURN VALUES
.Rv -std aio_fsync
.Sh ERRORS
.Bl -tag -width Er
The
.Fn aio_fsync
system call will fail if:
.It Bq Er EAGAIN
The request was not queued because of system resource limitations.
.El
.Pp
The following conditions may be synchronously detected when the
.Fn aio_fsync
system call is made, or asynchronously, at any time thereafter.
If they are detected at call time,
.Fn aio_fsync
returns \-1 and sets
.Va errno
appropriately; otherwise the
.Fn aio_return
system call must be called, and will return \-1, and
.Fn aio_error
must be called to determine the actual value that would have been
returned in
.Va errno .
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa aiocbp-\*[Gt]aio_fildes
is invalid for writing.
.It Bq Er EINVAL
This implementation does not support synchronized I/O for this file.
.It Bq Er EINVAL
The
.Fa op
argument is neither set to
.Dv O_DSYNC
nor
.Dv O_SYNC .
.El
.Sh SEE ALSO
.Xr fcntl 2 ,
.Xr fdatasync 2 ,
.Xr fsync 2 ,
.Xr aio_error 3 ,
.Xr aio_read 3 ,
.Xr aio_write 3
.Sh STANDARDS
The
.Fn aio_fsync
system call is expected to conform to the
.St -p1003.1-2001
standard.
.Sh HISTORY
The
.Fn aio_fsync
system call first appeared in
.Nx 5.0 .