gpfs_iputattrsx() subroutine

Sets the extended file attributes for a file.

Library

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

Synopsis

#include <gpfs.h>
int gpfs_iputattrsx(gpfs_ifile_t *ifile,
                    int flags, 
                    void *buffer,
                    const char *pathName);

Description

The gpfs_iputattrsx() subroutine, together with gpfs_igetattrsx(), is intended for use by a backup program to save (gpfs_igetattrsx()) and restore (gpfs_iputattrsx()) all of the extended attributes of a file. This subroutine also sets the storage pool for the file and sets data replication to the values that are saved in the extended attributes.

This subroutine can optionally invoke the policy engine to match a RESTORE rule using the file's attributes saved in the extended attributes to set the file's storage pool and data replication as when calling gpfs_fputattrswithpathname(). When used with the policy engine, the caller should include the full path to the file, including the file name, to allow rule selection based on file name or path.

By default, the routine will not use RESTORE policy rules for data placement. The pathName parameter will be ignored and may be set to NULL.

If the call does not use RESTORE policy rules, or if the file fails to match a RESTORE rule, or if there are not RESTORE rules installed, then the storage pool and data replication are selected as when calling gpfs_fputattrs().

The buffer passed in should contain extended attribute data that was obtained by a previous call to gpfs_fgetattrs().

Note: This call will restore extended attributes used for the Data Storage Management (XDSM) API (also known as DMAPI) if they are present in the buffer.

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

A pointer to gpfs_ifile_t from gpfs_iopen().

flags

Flags must have one of the following values:

GPFS_ATTRFLAG_NO_PLACEMENT: File attributes are restored, but the storage pool and data replication are unchanged.
GPFS_ATTRFLAG_IGNORE_POOL: File attributes are restored, but the storage pool and data replication are selected by matching the saved attributes to a placement rule instead of restoring the saved storage pool.
GPFS_ATTRFLAG_USE_POLICY: File attributes are restored, but the storage pool and data replication are selected by matching the saved attributes to a RESTORE rule instead of restoring the saved storage pool.
GPFS_ATTRFLAG_USE_POLICY: Uses the restore policy rules to determine the pool ID.
GPFS_ATTRFLAG_INCL_DMAPI: Includes the DMAPI attributes.
GPFS_ATTRFLAG_FINALIZE_ATTRS: Finalizes immutability attributes.
GPFS_ATTRFLAG_SKIP_IMMUTABLE: Skips immutable attributes.
GPFS_ATTRFLAG_INCL_ENCR: Includes encryption attributes.
GPFS_ATTRFLAG_SKIP_CLONE: Skips clone attributes.
GPFS_ATTRFLAG_MODIFY_CLONEPARENT: Allows modification on the clone parent.

buffer

A pointer to the buffer containing the extended attributes for the file.

pathName

A pointer to a file path and file name. NULL is a valid value for pathName.

Note: pathName is a UTF-8 encoded string. On Windows, applications can convert UTF-16 (Unicode) to UTF-8 using the platform's WideCharToMultiByte function.

Exit status

If the gpfs_iputattrsx() subroutine is successful, it returns a value of 0.

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

EINVAL: The buffer pointed to by buffer does not contain valid attribute data, or invalid flags were provided.
ENOSYS: The gpfs_iputattrsx() subroutine is not supported under the current file system format.
EPERM: The caller of the subroutine must have superuser privilege.
ESTALE: The cached fs information was not valid.
GPFS_E_INVAL_IFILE: The ifile parameters provided were not valid.

Location

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

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