fsync or fsync_range Subroutine

Purpose

Writes changes in a file to permanent storage.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

int fsync ( FileDescriptor)
int FileDescriptor;

int fsync_range (FileDescriptor, how, start, length)
int FileDescriptor;
int how;
off_t start;
off_t length;

Description

The fsync subroutine causes all modified data in the open file specified by the FileDescriptor parameter to be saved to permanent storage. On return from the fsync subroutine, all updates have been saved on permanent storage.

The fsync_range subroutine causes all modified data in the specified range of the open file specified by the FileDescriptor parameter to be saved to permanent storage. On return from the fsync_range subroutine, all updates in the specified range have been saved on permanent storage.

This paragraph refers to deprecated function available only in the JFS file system. Data written to a file that a process has opened for deferred update (with the O_DEFER flag) is not written to permanent storage until another process issues an fsync_range or fsync call against this file or runs a synchronous write subroutine (with the O_SYNC flag) on this file. See the fcntl.h file and the open subroutine for descriptions of the O_DEFER and O_SYNC flags respectively.

Note: The file identified by the FileDescriptor parameter must be open for writing when the fsync subroutine is issued or the call is unsuccessful. This restriction was not enforced in BSD systems. The fsync_range subroutine does not require write access.

Parameters

Item	Description
FileDescriptor	A valid, open file descriptor.
how	Specify the handling characteristics of the operation. O_SYNC The modified data in the range specified by the <start, length> parameters is written to storage. If any metadata is modified then all modified user data is written to storage. Any metadata changes and the file attributes including timestamps are also written to storage. O_DSYNC The modified data in the range specified by the <start, length> parameters is written to storage. If there is modified metadata for the file then the metadata is also written if it is required to read the data. Otherwise, no metadata updates occur. O_NOCACHE The modified data is written as with the O_DSYNC parameter. The full pages in the range specified by the <start, length> parameters are removed from the memory cache. The pages are removed from the cache even if they are not modified. The operation also works on files that are open only for reading.
start	Starting file offset.
length	Length, or zero for all cache data.

Return Values

Upon successful completion, the fsync subroutine returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Upon successful completion, the fsync_range subroutine returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The fsync or fsync_range subroutine is unsuccessful if one or more of the following are true:

Item	Description
EIO	An I/O error occurred while reading from or writing to the file system.
EBADF	The FileDescriptor parameter is not a valid file descriptor open for writing.
EINVAL	The file is not a regular file.
EINTR	The subroutine was interrupted by a signal.