aio_fsync Subroutine

Purpose

Synchronizes asynchronous files.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

int aio_fsync (op, aiocbp)
int op;
struct aiocb *aiocbp;

Description

The aio_fsync subroutine asynchronously forces all I/O operations to the synchronized I/O completion state. The function call returns when the synchronization request has been initiated or queued to the file or device (even when the data cannot be synchronized immediately).

If the op parameter is set to O_DSYNC, all currently queued I/O operations are completed as if by a call to the fdatasync subroutine. If the op parameter is set to O_SYNC, all currently queued I/O operations are completed as if by a call to the fsync subroutine. If the aio_fsync subroutine fails, or if the operation queued by aio_fsync fails, outstanding I/O operations are not guaranteed to be completed.

If aio_fsync succeeds, it is only the I/O that was queued at the time of the call to aio_fsync that is guaranteed to be forced to the relevant completion state. The completion of subsequent I/O on the file descriptor is not guaranteed to be completed in a synchronized fashion.

The aiocbp parameter refers to an asynchronous I/O control block. The aiocbp value can be used as an argument to the aio_error and aio_return subroutines in order to determine the error status and return status, respectively, of the asynchronous operation while it is proceeding. When the request is queued, the error status for the operation is EINPROGRESS. When all data has been successfully transferred, the error status is reset to reflect the success or failure of the operation. If the operation does not complete successfully, the error status for the operation is set to indicate the error. The aio_sigevent member determines the asynchronous notification to occur when all operations have achieved synchronized I/O completion. All other members of the structure referenced by the aiocbp parameter are ignored. If the control block referenced by aiocbp becomes an illegal address prior to asynchronous I/O completion, the behavior is undefined.

If the aio_fsync subroutine fails or aiocbp indicates an error condition, data is not guaranteed to have been successfully transferred.

Parameters

Item Description
op Determines the way all currently queued I/O operations are completed.
aiocbp Points to the aiocb structure associated with the I/O operation.

aiocb Structure

The aiocb structure is defined in the /usr/include/aio.h file and contains the following members:
int               aio_fildes
off_t             aio_offset
char             *aio_buf
size_t            aio_nbytes
int               aio_reqprio
struct sigevent   aio_sigevent
int               aio_lio_opcode

Execution Environment

The aio_error and aio_error64 subroutines can be called from the process environment only.

Return Values

The aio_fsync subroutine returns a 0 to the calling process if the I/O operation is successfully queued. Otherwise, it returns a -1, and sets the errno global variable to indicate the error.

Error Codes

Item Description
EAGAIN The requested asynchronous operation was not queued due to temporary resource limitations.
EBADF The aio_fildes member of the aiocb structure referenced by the aiocbp parameter is not a valid file descriptor open for writing.

In the event that any of the queued I/O operations fail, the aio_fsync subroutine returns the error condition defined for the read and write subroutines. The error is returned in the error status for the asynchronous fsync subroutine, which can be retrieved using the aio_error subroutine.