fffcntl

Date:: 10-20-2011

NAME

fffcntl - Performs functions on files opened using flexible file I/O

SYNOPSIS

#include <ffio.h>

int fffcntl (int fd, int cmd, void *arg, struct ffsw *stat);

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

The fffcntl function performs a variety of functions on files opened by ffopen or ffopens, using flexible file I/O (FFIO).

Arguments to fffcntl are as follows:

fd: Value returned from an ffopen or ffopens call.
cmd: Specifies values defined in header file ffio.h. See under the next heading, VALUES FOR cmd ARGUMENT.
arg: The type and value of arg is cmd specific. See preceding descriptions.
stat: Pointer to the ffsw status return structure, described in detail in ffread(3c).

Values for cmd Argument

The following values can be used for the cmd argument introduced above:

FC_ASPOLL

Checks for completion of an asynchronous FFIO request. Argument arg is a pointer to a structure of type struct ffsw, which had previously been passed to an asynchronous FFIO request. The purpose of this call is to pass control to the underlying layers to do intermediate processing or cleanup on the request. If the request is complete, fields in the status return structure are set as described under function ffread(3c).

FC_GETINFO

Gets information about the layers connected to this open file. arg is a pointer to structure ffc_info_s. The information returned in this structure is as follows:

ffc_flags

Flag word containing attributes of the file/connection. These bit masks are defined in header file ffio.h and if true, are set as follows:

FFC_STRM: Can handle stream I/O.
FFC_REC: Can handle records.
FFC_WEOF: Can represent EOF.
FFC_WEOD: Can represent EOD (always set).
FFC_BKSP: Can handle backspace.
FFC_BKFIL: Can handle backfile.
FFC_SEEKA: Can seek absolute.
FFC_SEEKR: Can seek relative.
FFC_SEEKE: Can seek to end.
FFC_POSREC: Can position by record number.
FFC_POSFIL: Can position by EOF mark.
FFC_RWND: Can rewind by seek(x,0,0).
FFC_FIXD: Can do fixed-length records.
FFC_VAR: Can do variable-length records.
FFC_BINARY: Can do binary data.
FFC_CODED: Can do formatted (character) data.
FFC_RDM: Can do random I/O (no truncation).
FFC_SEQ: Can do sequential I/O.
FFC_ASYNC: Can do asynchronous I/O. (All layers have asynchronous entry points, but this bit tells whether the behavior is actually async.)
FFC_WRTRUNC: Write implies truncation.
FFC_NOTRN: Does no transformation on data; no control words are added or subtracted. Data is not changed.

ffc_gran

Minimum granularity. This is the smallest size in bits of a valid data transfer. For example, the system call layer has an ffc_gran of 8, as it can handle a byte as its smallest unit of data transfer.

ffc_reclen

Valid only for fixed length records. This is the record length in bits.

ffc_fd

Lowest level file descriptor for the layer that makes system calls. This is not always available, or may not be meaningful for some layers or combinations of layers. This is -1 if no descriptor is available.

FC_GETLK

Performs an fcntl call with cmd F_GETLK. arg is a pointer to structure flock (defined in sys/fcntl.h), which is used in the fcntl call. Currently supported only by the syscall and system layers.

FC_GETLKW

Performs an fcntl call with cmd F_GETLKW. arg is a pointer to structure flock (defined in sys/fcntl.h), which is used in the fcntl call. Currently supported only by the syscall and system layers.

FC_RECALL

Awaits completion of an asynchronous FFIO request. Argument arg is a pointer to a structure of type struct ffsw, which is the status return structure of the asynchronous request. Function fffcntl waits for completion of the asynchronous request, if necessary. Fields in the status return structure are set as described under function ffread(3c).

FC_SCRATCH

Specifies that a file is to be deleted at close time. The arg argument is a pointer to int. On exit, *arg is set to contain zero or more of the following result bits:

SCR_NOFLUSH: Set if ffclose processing has been optimized to suppress buffer flushing.
SCR_SINGLELINK: Set if the file is not a pipe or a tty, has a link count equal to one, and is not a symbolically linked file.
SCR_UNLINKED: Set if this fffcntl call has successfully unlinked the file.

FC_SETLK

Performs an fcntl call with cmd F_SETLK. arg is a pointer to structure flock (defined in sys/fcntl.h), which is used in the fcntl call. Currently supported only by the syscall and system layers.

FC_STAT

Returns a structure much like the one returned by the fstat (see stat(2)) system call. arg is a pointer to a ffc_stat_s structure (from ffio.h). Fields in this structure are filled in as appropriate by the layers. For the system call layer, all fields are simply retrieved by doing an fstat call. For other layers, such as mr, the size field in the stat structure is modified to reflect the buffered data. Other layers can make similar changes to the basic information from the system for similar reasons. The result is a stat structure that can be used in the same way and for the same purposes as the fstat system call.

RETURN VALUES

The fffcntl function returns 0 on success. Otherwise, it returns -1 and the sw_error field of the stat structure contains the error number.