gpfs_open_inodescan64() subroutine

Opens an inode scan of a file system or snapshot.

Library

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

Synopsis

#include <gpfs.h>
gpfs_iscan_t *gpfs_open_inodescan64(gpfs_fssnap_handle_t *fssnapHandle,
                                    const gpfs_fssnap_id_t *prev_fssnapId,
                                    gpfs_ino64_t *maxIno);

Description

The gpfs_open_inodescan64() subroutine opens a scan of the inodes in the file system or snapshot identified by the fssnapHandle parameter. The scan traverses all user files, directories and links in the file system or snapshot. The scan begins with the user file with the lowest inode number and returns the files in increasing order. The gpfs_seek_inode64() subroutine may be used to set the scan position to an arbitrary inode. System files, such as the block allocation maps, are omitted from the scan. The file system must be mounted to open an inode scan.

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

To generate a full backup, invoke gpfs_open_inodescan64() with NULL for the prev_fssnapId parameter. Repeated invocations of gpfs_next_inode64() then return inode information about all existing user files, directories, and links in inode number order.

To generate an incremental backup, invoke gpfs_open_inodescan64() with the fssnapId that was obtained from a fssnapHandle at the time the previous backup was created. The snapshot that was used for the previous backup does not need to exist at the time the incremental backup is generated. That is, the backup application needs to remember only the fssnapId of the previous backup; the snapshot itself can be deleted as soon as the backup is completed.

For the incremental backup, any operation that changes the file's mtime or ctime causes the file to be included. Files with no changes to the file's data or file attributes, other than a change to atime, are omitted from the scan.

A full inode scan (prev_fssnapId set to NULL) does not return any inodes of nonexistent or deleted files, but an incremental inode scan (prev_fssnapId not NULL) does return inodes for files that have been deleted since the previous snapshot. The inodes of deleted files have a link count of zero.

If the snapshot indicated by prev_fssnapId is available, the caller may benefit from the extended read subroutine, gpfs_ireadx(), which returns only the changed blocks within the files. Without the previous snapshot, all blocks within the changed files are returned.

Once a full or incremental backup completes, the new_fssnapId must be saved in order to reuse it on a subsequent incremental backup. This fssnapId must be provided to the gpfs_open_inodescan64() subroutine, as the prev_fssnapId input parameter.

To read only the inodes that have been copied to a snapshot, use gpfs_open_inodescan() with fssnapHandle of the snapshot and pass fssnapid of the fssnapHandle as the prev_fssnapId.

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

fssnapHandle: The file system snapshot handle.
prev_fssnapId: A pointer to file system snapshot ID or NULL. If prev_fssnapId is provided, the inode scan returns only the files that have changed since the previous backup. If the pointer is NULL, the inode scan returns all user files.
If it is same as the fssnapid of the fssnapHandle parameter, the scan only returns the inodes copied into the corresponding snapshot.
maxIno: A pointer to inode number or NULL. If provided, gpfs_open_inodescan64() returns the maximum inode number in the file system or snapshot being scanned.

Exit status

If the gpfs_open_inodescan64() subroutine is successful, it returns a pointer to an inode scan handle.

If the gpfs_open_inodescan64() subroutine is unsuccessful, it returns a NULL pointer and the global error variable errno is set 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 snapshot ID passed for prev_fssnapId is from a different file system.
EINVAL: Incorrect parameters.
ENOMEM: Unable to allocate memory for the request.
ENOSYS: The gpfs_open_inodescan64() subroutine is not available.
EPERM: The caller does not have superuser privileges.
ERANGE: The prev_fssnapId parameter is the same as or more recent than snapId being scanned.
ESTALE: The cached file system information was not valid.
GPFS_E_INVAL_FSSNAPHANDLE: The file system snapshot handle is not valid.
GPFS_E_INVAL_FSSNAPID: The file system snapshot ID passed for prev_fssnapId is not valid.

Note: gpfs_open_inodescan64() calls the standard library subroutines dup() and malloc(); if one of these called subroutines returns an error, gpfs_open_inodescan64() also returns that error.

Examples

See the gpfs_open_inodescan() example in /usr/lpp/mmfs/samples/util/tstimes.c.

Location

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

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