gpfs_open_inodescan_with_xattrs() subroutine

Opens an inode file and extended attributes for an inode scan.

Library

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

Synopsis

#include <gpfs.h>
gpfs_iscan_t *gpfs_open_inodescan_with_xattrs(gpfs_fssnap_handle_t *fssnapHandle,
                                              const gpfs_fssnap_id_t *prev_fssnapId,
                                              int nxAttrs,
                                              const char *xattrsList[],
                                              gpfs_ino_t *maxIno);

Description

The gpfs_open_inodescan_with_xattrs() subroutine opens an inode file and extended attributes for an inode scan 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_inode() subroutine can 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_inodescan_with_xattrs() in a backup application, see Using APIs to develop backup applications.

To generate a full backup, invoke gpfs_open_inodescan_with_xattrs() 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_open_inodescan_with_xattrs() 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) returns all inodes of existing files. An incremental inode scan (prev_fssnapId not NULL) returns inodes for files that have changed 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_inodescan_with_xattrs() 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 the same as the fssnapid of the fssnapHandle parameter, the scan only returns the inodes copied into the corresponding snapshot.
nxAttrs: The count of extended attributes to be returned. If nxAttrs is set to 0, call returns no extended attributes, like gpfs_open_inodescan(). If nxAttrs is set to -1, call returns all extended attributes.
xattrsList: A pointer to an array of pointers to names of extended attributes to be returned. nxAttrsList may be null if nxAttrs is set to 0 or -1.
maxIno: A pointer to inode number or NULL. If provided, gpfs_open_inodescan_with_xattrs() returns the maximum inode number in the file system or snapshot being scanned.

Exit status

If the gpfs_open_inodescan_with_xattrs() subroutine is successful, it returns a pointer to gpfs_iscan_t.

If the gpfs_open_inodescan_with_xattrs() 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_inodescan_with_xattrs() 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_inodescan_with_xattrs() calls the standard library subroutines dup() and malloc(); if one of these called subroutines returns an error, gpfs_open_inodescan_with_xattrs() also returns that error.

Examples

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

Location

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

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