gpfs_next_inode() subroutine

Retrieves the next inode from the inode scan.

Library

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

Synopsis

#include <gpfs.h>
int gpfs_next_inode(gpfs_iscan_t *iscan,
                    gpfs_ino_t termIno,
                    const gpfs_iattr_t **iattr);

Description

The gpfs_next_inode() subroutine obtains the next inode from the specified inode scan and sets the iattr pointer to the inode's attributes. The termIno parameter can be used to terminate the inode scan before the last inode in the file system or snapshot being scanned. A value of 0 may be provided to indicate the last inode in the file system or snapshot. If there are no more inodes to be returned before the termination inode, the gpfs_next_inode() subroutine returns a value of 0 and the inode's attribute pointer is set to NULL.

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

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

To generate an incremental backup, invoke gpfs_next_inode() 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 an incremental backup, only inodes of files that have changed since the specified previous snapshot will be returned. Any operation that changes the file's mtime or ctime is considered a change and will cause 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.

Incremental backups return deleted files, but full backups do not. A deleted file is indicated by the field ia_nlinks having a value of 0.

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 prev_fssnapId. Repeated invocations of gpfs_next_inode() then return the inodes copied to the snapshot, skipping holes.

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

iscan: Pointer to the inode scan handle.
termIno: The inode scan terminates before this inode number. The caller may specify maxIno from gpfs_open_inodescan() or zero to scan the entire inode file.
iattr: Pointer to the returned pointer to the inode's iattr.

Exit status

If the gpfs_next_inode() subroutine is successful, it returns a value of 0 and a pointer. The pointer points to NULL if there are no more inodes. Otherwise, the pointer points to the returned inode's attributes.

If the gpfs_next_inode() 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:

ENOMEM: Unable to allocate memory for the request.
ENOSYS: The gpfs_next_inode() subroutine is not available.
EPERM: The caller does not have superuser privileges.
ESTALE: Cached file system information was not valid.
GPFS_E_INVAL_FSSNAPID: The file system snapshot ID is not valid.
GPFS_E_INVAL_ISCAN: Incorrect parameters.

Examples

For an example using gpfs_next_inode(), see /usr/lpp/mmfs/samples/util/tstimes.c.

Location

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

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