ffread

Date:: 10-20-2011

NAME

ffread, ffwrite, ffweof, ffweod, ffreadf, ffwritef, ffweodf, ffweoff, ffflush - Provides flexible file I/O

SYNOPSIS

#include <ffio.h>

ssize_t ffread (int fd, void *buf, size_t nb);

size_t ffreadf (int fd, void *buf, size_t nb , struct ffsw *stat,
int fulp, int *ubc);

ssize_t ffwrite (int fd, const void *buf, size_t nb);

size_t ffwritef (int fd, const void *buf, size_t nb,
struct ffsw*stat, int fulp, int *ubc);

int ffweof (int fd);

int ffweoff (int fd, struct ffsw *stat);

int ffweod (int fd);

int ffweodf (int fd, struct ffsw *stat);

int ffflush (int fd, struct ffsw *stat);

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

The ffread and ffwrite functions provide flexible file I/O (FFIO) to record-oriented or byte stream-oriented data in an application-transparent manner.

Function ffweof writes an end-of-file (EOF) if the function is supported for the layer in use.

Function ffweod writes an end-of-data (EOD). If the FFIO specification is stream oriented, this requests truncation of the file at the current position.

Function ffflush instructs the layer to flush as much data to the file as is convenient. For some layers, and layers which do no buffering (for example, the syscall layer), this operation does nothing. For record layers, the ffflush function will not terminate any partially- written records. This function is intended for use on files which are being written. It is undefined for files which are being read.

The arguments are as follows:

fd: Number returned by ffopen(3c).
buf: Pointer to the user data buffer.
nb: Requested number of bytes to be read or written.
stat: Pointer to the returned status structure.
fulp: Either FULL or PARTIAL (defined in header file ffio.h); indicates whether I/O should be performed in full or partial record mode.
ubc: Unused bit count. The word pointed to by this pointer is in the range of 0 through 7; it is used to specify how many bits in the last byte are not valid data.

The nb and ubc arguments are used together to determine an exact number of bits to be transferred. nb always indicates the number of bytes affected by the data transfer, even if only one bit is transferred in that byte.

If argument ubc is omitted, it is assumed to be 0.

If ubc is specified, it functions as both an input and output argument. It is passed to ffread or ffwrite as a request to omit processing the specified number of bits in the last byte of the request. For example, to read 2 bits from a file, you should set nb to 1, set the word at ubc to 6, and call ffread. On completion of the ffread request, the word pointed to by ubc is set by ffread to indicate the number of unused bits in the last byte read. As in the preceding example, if only one bit were available to be read, then the word at ubc would be set to 7 by ffread.

For ffwrite, ubc is an input argument specifying the number of bits in the last byte transferred that should not be written to the file. Function ffwrite normally will not change the value of the word at ubc, because, if the specified number of bits is not written, an error is returned.

RETURN VALUES

Upon successful completion, a non-negative value is returned. Otherwise, -1 is returned and, if the stat argument is passed, the error value is found in stat.sw_error. If the stat parameter is not provided, the error code is found in errno.

If the stat parameter is passed, the sw_stat field is set to one of the following values, indicating the condition that terminated the operations:

FFERR: An error was encountered.
FFEOR: An end-of-record (EOR) was encountered.
FFEOF: An end-of-file (EOF) was encountered.
FFEOD: An end-of-data (EOD) was encountered.
FFCNT: For layers without record handling, some data was read before an EOF or EOD was encountered.

For layers with record handling, the count was satisfied before an EOR was encountered. If the count was satisfied simultaneously with encountering an EOR, the FFEOR status is returned.

The FFSTAT macro, defined in ffio.h, can be used to obtain the value of the sw_stat field.