gpfs_fputattrs() subroutine

Sets all the extended file attributes for a file.

Library

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

Synopsis

#include <gpfs.h>
int gpfs_fputattrs(gpfs_file_t fileDesc,
                   int flags,
                   void *bufferP);

Description

The gpfs_fputattrs() subroutine, together with gpfs_fgetattrs(), is intended for use by a backup program to save (gpfs_fgetattrs()) and restore (gpfs_fputattrs()) 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.

If the saved storage pool is not valid or if the GPFS_ATTRFLAG_IGNORE_POOL flag is set, GPFS will select the storage pool by matching a PLACEMENT rule using the saved file attributes. If GPFS fails to match a placement rule or if there are no placement rules installed, GPFS assigns the file to the system storage pool.

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

fileDesc

The file descriptor identifying the file whose extended attributes are being set.

flags

Must have one of the following values:

GPFS_ATTRFLAG_DEFAULT: Restores the previously assigned storage pool and previously assigned data replication.
GPFS_ATTRFLAG_NO_PLACEMENT: Does not change storage pool and data replication.
GPFS_ATTRFLAG_IGNORE_POOL: Selects storage pool and data replication by matching the saved attributes to a placement 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.

Non-placement attributes such as ACLs are always restored, regardless of value of the flag.

bufferP

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

If you specify a value of NULL, all extended ACLs for the file are deleted.

Exit status

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

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

EBADF: The file descriptor is not valid.
EINVAL: The buffer pointed to by bufferP does not contain valid attribute data, or the file descriptor does not refer to a GPFS file.
ENOSYS: The gpfs_fputattrs() subroutine is not supported under the current file system format.

Examples

To copy extended file attributes from file f1 to file f2:

char buf[4096];
int f1, f2, attrSize, rc;

rc = gpfs_fgetattrs(f1, GPFS_ATTRFLAG_DEFAULT, buf, sizeof(buf), &attrSize);
if (rc != 0)
    ...                                 // error handling
if (attrSize != 0)
   rc = gpfs_fputattrs(f2, 0, buf);     // copy attributes from f1 to f2
else
   rc = gpfs_fputattrs(f2, 0, NULL);    // f1 has no attributes
                                        // delete attributes on f2

Location

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

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