aio_fsync

Date:: 10-20-2011

NAME

aio_fsync - Asynchronously synchronizes a file’s in-memory state with that on the physical medium

SYNOPSIS

#include <aio.h>

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

DESCRIPTION

The aio_fsync function asynchronously forces all I/O operations associated with the file indicated by the file descriptor aio_fildes member of the aiocb structure referenced by the aiocbp argument and queued at the time of the call to aio_fsync 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 imediately).

If op is O_DSYNC, all currently queued I/O operations will be completed as if by a call to fdatasync; that is, as defined for synchronized I/O data integrity completion.

If op is O_SYNC, all currently queued I/O operations will be completed as if by a call to fsync; that is, as defined for synchronized I/O file integrity completion.

If the aio_fsync function fails, or if the operation queued by aio_fsync fails, then, as for fsync and fdatasync, outstanding I/O operations are not guaranteed to have been completed.

If aio_fsync succeeds, then 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 argument refers to an asynchronous I/O control block. The aiocbp value may be used as an argument to aio_error and aio_return 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 as specified below when all operations have achieved synchronized I/O completion. All other members of the structure referenced by aiocbp are ignored. If the control block referenced by aiocbp becomes an illegal address prior to asynchronous I/O completion, then the behavior is undefined.

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

The aiocb->aio_sigevent defines how the calling process will be notified upon I/O completion.

If sigev_notify is SIGEV_NONE, then no notification will be posted to the calling application.

If sigev_notify is SIGEV_SIGNAL, then the signal specified in sigev_signo will be sent to the calling process. If SA_SIGINFO is set for the signal (see sigaction), then the signal will be queued to the process and the value in sigev_value will be the si_value in the generated signal.

(Deferred implementation) If sigev_notify is SIGEV_CALLBACK, then the function sigev_func will be called with sigev_value as the argument. Only one callback will be called at a time, however. Programs should be careful to note that a callback may be run in parallel with the calling process.

(Deferred implementation) If sigev_notify is SIGEV_THREAD then the function sigev_notify_function will be called by a new thread (see pthreads) with sigev_value as the argument. This thread is created when the event arrives with the attributes specified in sigev_notify_attributes except that it is automatically detached. The calling process should ensure there are sufficient resources to create the thread.

All aio_fsync calls must supply a complete aiocb->aio_sigevent structure.

RETURN VALUES

A value of 0 is returned to the calling process if the operation is successfully queued; otherwise the function returns -1 and errno is set to indicate the error.

MESSAGES

EAGAIN: The operation was not queued due to temporary resource limitations.
EBADF: The aio_fildes was not a valid file descriptor open for writing .
EINVAL: A value other then O_DSYNC or O_SYNC was specified for op.