gpfs_fcntl() subroutine

Performs operations on an open file.

Library

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

Synopsis

#include <gpfs_fcntl.h>
int gpfs_fcntl(gpfs_file_t fileDesc, void* fcntlArgP);

Description

The gpfs_fcntl() subroutine is used to pass file access pattern information and to control certain file attributes on behalf of an open file. More than one operation can be requested with a single invocation of gpfs_fcntl(). The type and number of operations is determined by the second operand, fcntlArgP, which is a pointer to a data structure built in memory by the application. This data structure consists of:

A fixed-length header, which is mapped by gpfsFcntlHeader_t.
A variable list of individual file access hints, directives, or other control structures:
- File access hints:
  - gpfsAccessRange_t
  - gpfsClearFileCache_t
  - gpfsCreateSharing_t
  - gpfsDisableInodePrefetch_t
  - gpfsFineGrainReadSharing_t
  - gpfsFineGrainWriteSharing_t
  - gpfsFreeRange_t
  - gpfsMultipleAccessRange_t
  - gpfsPurgeFileAndStatCache_t
  - gpfsPrefetch_t
- File access directives:
  - gpfsCancelHints_t
- Platform-independent extended attribute operations:
  - gpfsGetSetXAttr_t
  - gpfsListXAttr_t
- Other file attribute operations:
  - gpfsGetDataBlkDiskIdx_t
  - gpfsGetFilesetName_t
  - gpfsGetReplication_t
  - gpfsGetSnapshotName_t
  - gpfsGetStoragePool_t
  - gpfsRestripeData_t
  - gpfsSetReplication_t
  - gpfsSetStoragePool_t
These hints, directives and other operations may be mixed within a single gpfs_fcntl() subroutine, and are performed in the order that they appear. A subsequent hint or directive may cancel out a preceding one.

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

Restriction: On Linux, do not use the F_OFD_SETLK, F_OFD_SETLKW, or F_OFD_GETLK parameter values with gpfs_fcntl(). The Linux kernel cannot properly interpret these parameter values.

The unfulfillment of this restriction may cause different problems, up to and including faulty nodes in the IBM Storage Scale file system.

fileDesc

The file descriptor identifying the file to which GPFS applies the hints and directives.

fcntlArgP

A pointer to the list of operations to be passed to GPFS. It includes a list of file access hints. Some of these are described in the following section:

gpfsCreateSharing_t: The Create Sharing hint is used to optimize the performance of a parallel application that has multiple threads creating files in a shared directory. The mdtest hard write workload included in the IO500 benchmark suite shows an example. For more information, see IO500 benchmark.
This hint is issued only when the GPFS configuration attribute preferDesignatedMnode is set to yes on all the participating clusters.
gpfsDisableInodePrefetch_t: The Disable Inode Prefetch hint disables prefetching of inodes cluster-wide or for a specific directory.
Inode prefetch is optimized for ls -l operations, but does not benefit applications accessing only a small fraction of files in a large directory or access files in an order different than the one returned by the readdir function. Workloads with such access patterns benefit from disabling inode prefetch by using this hint.
gpfsFineGrainReadSharing_t: The Fine Grain Read Sharing hint is used to optimize the performance of multiple nodes or tasks that issue small strided reads that are less than a full block. The strided reads are issued to a shared file from a parallel application. The IOR Hard Read workload included in the IO500 benchmark suite shows an example. For more information, see IO500 benchmark.

gpfsFineGrainWriteSharing_t

This hint is used to optimize the performance of small strided writes to a shared file from a parallel application, for example as seen in the IO500 benchmark, ior hard write. The hint should be issued on every file descriptor that will be used to write to the file.

Using this hint, write() calls will be processed asynchronously. That means after successful return from the write() call, read() and stat() may return old data and information for a while, and some error notifications may be delayed, possibly up until the time of file close. All pending writes will be completed when the application issues hint to stop Fine Grain Write Sharing, calls fsync(), or when the file descriptor on which the hint was issued is closed.

If disabling the Fine Grain Write Sharing hint, fsync(), or close() calls returns an error, some data may have been lost even if all previous write() calls returned successfully. Otherwise, all subsequent read() and stat() calls are guaranteed to return up-to-date data and information.

Note: This is just a hint to GPFS and certain operations, such as O_SYNC, AIO, Direct IO, and mmap, are not compatible with this mode of operation. If one of these other options is used the fine-grain write sharing hint is ignored.

gpfsPurgeFileAndStatCache_t

The Purge File and Stat Cache hint attempts to remove all cached files and stat cache entries, and the associated tokens. Files that are open or actively being accessed at the time the hint is issued are not touched.

This hint reduces token conflicts which benefits applications accessing a file whose entries are in the file and stat cache of a node and is accessed by the application on another node.

Exit status

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

If the gpfs_fcntl() 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 file descriptor does not refer to a GPFS file or a regular file.
The system call is not valid.
ENOSYS: The gpfs_fcntl() subroutine is not supported under the current file system format.

Examples

This programming segment releases all cache data held by the file handle and tell GPFS that the subroutine will write the portion of the file with file offsets between 2 GB and 3 GB minus one:


struct
{
  gpfsFcntlHeader_t hdr;
  gpfsClearFileCache_t rel;
  gpfsAccessRange_t acc;
} arg;

arg.hdr.totalLength = sizeof(arg);
arg.hdr.fcntlVersion = GPFS_FCNTL_CURRENT_VERSION;
arg.hdr.fcntlReserved = 0;
arg.rel.structLen = sizeof(arg.rel);
arg.rel.structType = GPFS_CLEAR_FILE_CACHE;
arg.acc.structLen = sizeof(arg.acc);
arg.acc.structType = GPFS_ACCESS_RANGE;
arg.acc.start = 2LL * 1024LL * 1024LL * 1024LL;
arg.acc.length = 1024 * 1024 * 1024;
arg.acc.isWrite = 1;
rc = gpfs_fcntl(handle, &arg);

This programming segment gets the storage pool name and fileset name of a file from GPFS.


struct {
gpfsFcntlHeader_t hdr;
gpfsGetStoragePool_t pool;
gpfsGetFilesetName_t fileset;
} fcntlArg;
fcntlArg.hdr.totalLength = sizeof(fcntlArg.hdr) + sizeof(fcntlArg.pool) + sizeof(fcntlArg.fileset);
fcntlArg.hdr.fcntlVersion = GPFS_FCNTL_CURRENT_VERSION;
fcntlArg.hdr.fcntlReserved = 0;

fcntlArg.pool.structLen = sizeof(fcntlArg.pool);
fcntlArg.pool.structType = GPFS_FCNTL_GET_STORAGEPOOL;

fcntlArg.fileset.structLen = sizeof(fcntlArg.fileset);
fcntlArg.fileset.structType = GPFS_FCNTL_GET_FILESETNAME;

rc = gpfs_fcntl(fd, &fcntlArg);

Location

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

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