gpfs_ireadx() subroutine

Performs block level incremental read of a file within an incremental inode scan.

Library

GPFS Library (libgpfs.a for AIX®, libgpfs.so for Linux®)

Synopsis

#include <gpfs.h>
gpfs_off64_t gpfs_ireadx(gpfs_ifile_t *ifile,
                         gpfs_iscan_t *iscan,
                         void *buffer,
                         int bufferSize,
                         gpfs_off64_t *offset,
                         gpfs_off64_t termOffset,
                         int *hole);

Description

The gpfs_ireadx() subroutine performs a block level incremental read on a file opened by gpfs_iopen() within a given incremental scan opened using gpfs_open_inodescan().

For an overview of using gpfs_ireadx() in a backup application, see Using APIs to develop backup applications.

The gpfs_ireadx() subroutine returns the data that has changed since the prev_fssnapId specified for the inode scan. The file is scanned starting at offset and terminating at termOffset, looking for changed data. Once changed data is located, the offset parameter is set to its location, the new data is returned in the buffer provided, and the amount of data returned is the subroutine's value.

If the change to the data is that it has been deleted (that is, the file has been truncated), no data is returned, but the hole parameter is returned with a value of 1, and the size of the hole is returned as the subroutine's value. The returned size of the hole may exceed the bufferSize provided. If no changed data was found before reaching the termOffset or the end-of-file, then the gpfs_ireadx() subroutine return value is 0.

Block level incremental backups are not available on small files (a file size smaller than the file system block size), directories, or if the file has been deleted. The gpfs_ireadx() subroutine can still be used, but it returns all of the file's data, operating like the standard gpfs_iread() subroutine. However, the gpfs_ireadx() subroutine will still identify sparse files and explicitly return information on holes in the files, rather than returning the NULL data.

Note: Compile any program that uses this subroutine with the -lgpfs flag from the following library:

libgpfs.a for AIX
libgpfs.so for Linux

Parameters

ifile: Pointer to gpfs_ifile_t returned from gpfs_iopen().
iscan: Pointer to gpfs_iscan_t from gpfs_open_inodescan().
buffer: Pointer to buffer for returned data, or NULL to query the next increment to be read.
bufferSize: Size of buffer for returned data.
offset: On input, the offset to start the scan for changes. On output, the offset of the changed data, if any was detected.
termOffset: Read terminates before reading this offset. The caller may specify ia_size from the file's gpfs_iattr_t or 0 to scan the entire file.
hole: Pointer to a flag returned to indicate a hole in the file. A value of 0 indicates that the gpfs_ireadx() subroutine returned data in the buffer. A value of 1 indicates that gpfs_ireadx() encountered a hole at the returned offset.

Exit status

If the gpfs_ireadx() subroutine is successful, it returns the number of bytes read and returned in bufP, or the size of the hole encountered in the file.

If the gpfs_ireadx() subroutine is unsuccessful, it returns a value of -1 and sets the global error variable errno to indicate the nature of the error.

Exceptions

None.

Error status

Error codes include but are not limited to the following:

EDOM: The file system stripe ID from the iscanId does not match the ifile's.
EINVAL: Missing or incorrect parameter.
EISDIR: The specified file is a directory.
ENOMEM: Unable to allocate memory for the request.
ENOSYS: The gpfs_ireadx() subroutine is not available.
EPERM: The caller does not have superuser privileges.
ERANGE: The file system snapshot ID from the iscanId is more recent than the ifile's.
ESTALE: Cached file system information was not valid.
GPFS_E_INVAL_IFILE: Incorrect ifile parameter.
GPFS_E_INVAL_ISCAN: Incorrect iscan parameter.

Location

/usr/lpp/mmfs/lib/libgpfs.a for AIX

/usr/lpp/mmfs/lib/libgpfs.so for Linux