1.\" Copyright (c) 2013 Sergey Kandaurov 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 BY THE AUTHOR AND CONTRIBUTORS ``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 6, 2021 28.Dt AIO_FSYNC 2 29.Os 30.Sh NAME 31.Nm aio_fsync 32.Nd asynchronous file synchronization (REALTIME) 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In aio.h 37.Ft int 38.Fn aio_fsync "int op" "struct aiocb *iocb" 39.Sh DESCRIPTION 40The 41.Fn aio_fsync 42system call allows the calling process to move all modified data 43associated with the descriptor 44.Fa iocb->aio_fildes 45to a permanent storage device. 46The call returns immediately after the synchronization request has been 47enqueued to the descriptor; the synchronization may or may not have 48completed at the time the call returns. 49.Pp 50The 51.Fa op 52argument can be set to 53.Dv O_SYNC 54to cause all currently queued I/O operations to be completed 55as if by a call to 56.Xr fsync 2 , 57or 58.Dv O_DSYNC 59for the behavior of 60.Xr fdatasync 2 . 61.Pp 62If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, 63then the enqueued operation is submitted at a priority equal to that 64of the calling process minus 65.Fa iocb->aio_reqprio . 66.Pp 67The 68.Fa iocb 69pointer may be subsequently used as an argument to 70.Fn aio_return 71and 72.Fn aio_error 73in order to determine return or error status for the enqueued operation 74while it is in progress. 75.Pp 76If the request could not be enqueued (generally due to invalid arguments), 77the call returns without having enqueued the request. 78.Pp 79The 80.Fa iocb->aio_sigevent 81structure can be used to request notification of the operation's 82completion as described in 83.Xr aio 4 . 84.Sh RESTRICTIONS 85The Asynchronous I/O Control Block structure pointed to by 86.Fa iocb 87must remain valid until the 88operation has completed. 89.Pp 90The asynchronous I/O control buffer 91.Fa iocb 92should be zeroed before the 93.Fn aio_fsync 94call to avoid passing bogus context information to the kernel. 95.Pp 96Modification of the Asynchronous I/O Control Block structure is not allowed 97while the request is queued. 98.Sh RETURN VALUES 99.Rv -std aio_fsync 100.Sh ERRORS 101The 102.Fn aio_fsync 103system call will fail if: 104.Bl -tag -width Er 105.It Bq Er EAGAIN 106The request was not queued because of system resource limitations. 107.It Bq Er EINVAL 108The asynchronous notification method in 109.Fa iocb->aio_sigevent.sigev_notify 110is invalid or not supported. 111.It Bq Er EOPNOTSUPP 112Asynchronous file synchronization operations on the file descriptor 113.Fa iocb->aio_fildes 114are unsafe and unsafe asynchronous I/O operations are disabled. 115.It Bq Er EINVAL 116A value of the 117.Fa op 118argument is not set to 119.Dv O_SYNC 120or 121.Dv O_DSYNC . 122.El 123.Pp 124The following conditions may be synchronously detected when the 125.Fn aio_fsync 126system call is made, or asynchronously, at any time thereafter. 127If they are detected at call time, 128.Fn aio_fsync 129returns -1 and sets 130.Va errno 131appropriately; otherwise the 132.Fn aio_return 133system call must be called, and will return -1, and 134.Fn aio_error 135must be called to determine the actual value that would have been 136returned in 137.Va errno . 138.Bl -tag -width Er 139.It Bq Er EBADF 140The 141.Fa iocb->aio_fildes 142argument 143is not a valid descriptor. 144.It Bq Er EINVAL 145This implementation does not support synchronized I/O for this file. 146.El 147.Pp 148If the request is successfully enqueued, but subsequently cancelled 149or an error occurs, the value returned by the 150.Fn aio_return 151system call is per the 152.Xr read 2 153and 154.Xr write 2 155system calls, and the value returned by the 156.Fn aio_error 157system call is one of the error returns from the 158.Xr read 2 159or 160.Xr write 2 161system calls. 162.Sh SEE ALSO 163.Xr aio_cancel 2 , 164.Xr aio_error 2 , 165.Xr aio_read 2 , 166.Xr aio_return 2 , 167.Xr aio_suspend 2 , 168.Xr aio_waitcomplete 2 , 169.Xr aio_write 2 , 170.Xr fsync 2 , 171.Xr sigevent 3 , 172.Xr siginfo 3 , 173.Xr aio 4 174.Sh STANDARDS 175The 176.Fn aio_fsync 177system call is expected to conform to the 178.St -p1003.1 179standard. 180.Sh HISTORY 181The 182.Fn aio_fsync 183system call first appeared in 184.Fx 7.0 . 185The 186.Dv O_DSYNC 187option appeared in 188.Fx 13.0 . 189