IBM General Parallel File System for AIX: Administration and Programming Reference

gpfs_fcntl( ) Subroutine

Name

gpfs_fcntl - Passes hints and directives to GPFS on behalf of an open file.

Library

GPFS Library (libgpfs.a)

Synopsis

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

Description

This function passes hint and directives to GPFS on behalf of an open file, while obtaining the necessary size, version, and error information from the gpfsFcntlHeader_t structure (see Communicating file access patterns to GPFS):

• hints:
  1. gpfsAccessRange_t
  2. gpfsFreeRange_t
  3. gpfsMultipleAccessRange_t
  4. gpfsClearFileCache_t
• directives:
  1. gpfsCancelHints_t
  2. gpfsDataShipStart_t
  3. gpfsDataShipMap_t
  4. gpfsDataShipStop_t

Notes:

1. Compile any program that uses this function from the libgpfs.a library with the -lgpfs flag.

2. In order to use the 64-bit version of this function, compile it with the appropriate compiler options for 64-bit mode.

Parameters

fileDesc

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

fcntlArgP

A pointer to the list of hints and directives to be passed to GPFS.

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

ENOSYS

The gpfs_fcntl( ) function is not supported under the current file system format.

EBADF

The file descriptor is invalid.

EINVAL

The file descriptor does not refer to a GPFS file or a regular file.

The hint or directive is invalid.

E2BIG

An argument is longer than GPFS_MAX_FCNTL_LENGTH.

Examples

The following piece of code will release all cache data held by the file handle and tell GPFS that the file will write the portion of the file with file offsets between 2G and 3G-1:

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); 

Location

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