greada, greadb, greadc, greadm, gunread - stream input

SYNOPSIS

#include "gio.h"
int greadc(GFILE *stream, void *buf , size_t size);
int greadm(GFILE *stream, void **buf , size_t size);
int greada(GFILE *stream, void **buf , size_t size, GIO_ALIGN align);
int greadb(GFILE *stream, void **buf , size_t size, GIO_ALIGN align , size_t bias);
int gunread(GFILE *stream, const void *buf , size_t size);

DESCRIPTION

greadc is called to read data from the i/o stream referenced by stream. Up to size bytes are read into a buffer provided by the caller, beginning at buf.

greadm is called to read data from the i/o stream referenced by stream. The function reserves buffer space for at least sizebytes of data. The buffer alignment is suitable for any host data type, like pointers returned by malloc. A pointer to the buffer is assigned to *buf. The buffer may be accessed read-only, until the next operation on stream. Behavior is undefined, if the caller attempts to modify the buffer contents.

greada is similar to greadm, except for buffer alignment. The minimum alignment is specified by align (GIO_CHAR, GIO_SHORT, GIO_INT, etc.). The values required for various types are defined in "gio.h" and describe in gio. If align equals GIO_MALLOC, then the call is functionally equivalent to greadm.

greadb is similar to greada, except for an alignment bias. The alignment is associated with ((char*)*buf+bias) instead of the beginning of the buffer. This variation can accommidate weird composite transfers, i.e. "short" prefix on an array of "double" values.

gunread is called to queue data for subsequent reads on the i/o stream referenced by stream. Size bytes are queued from a buffer provided by the caller, beginning at buf. The actual stream position and contents are not changed. Any existing queue contents are discarded, when any write, unread, or reposition operation is performed on stream. If the stream is non-buffered and data is queued, then the entire queue is consumed by the next read.

RETURN VALUES

If positive, the function return value is the number of bytes actually read. The current file position is incremented by this amount. If the return value is less than the number of bytes requested, then an error or EOF was encountered. If the return value is zero, *buf is undefined, and no data was transferred. gerror and geof may be called to determine the current status.

unread returns the number of bytes actually queued, and doesn't change the file position.

ERRORS

Potential errors are defined by read(2), mmap(2).

BUGS

Read and write can be intermixed, with or without intervening file position requests. Applications may break, if converted to stdio, where such sequences are undefined.

When reading 8mm tapes, the requested size should be greater than or equal to the physical record length. The SunOS kernel (4.1.3_U1) will return errno 22 (Invalid argument) if the requested size is less than the physical tape record. This problem was first noted 13 Feb 1996 by Jerry Ehlers. It unknown whether this problem occurs on other hosts or tape device.

EXAMPLE

{  /* read 80 bytes, into a char buffer */
    GFILE *fp; char *buf; int n;
    n = greada(fp, &buf, 80, GIO_CHAR);
}

{  /* read 200 gpos_t structures */
    GFILE *fp; gpos_t *buf; int n;
    n = greada(fp, &buf, 200 * sizeof(gpos_t), GIO_MALLOC);
}

{  /* read and write, with minimal data copying */
    GFILE *fp_in, *fp_out; const char *buf; int n;
    while(0 < (n = greada(fp_in, &buf, 32 * 1024, GIO_CHAR)))
    gwritec(fp_out, buf, n);
}

{  /* unread three characters, for subsequent input */
    GFILE *fp;
    gunread(fp, "abc", 3);
}

FILES

$DDSROOT/include/gio.h
$DDSROOT/lib/$TARCH/libgio.a

AUTHOR

R. L. Selzler, EPTG (Oct 1995)

REFERENCES

1. Orran Krieger and Michael Stumm, "The Alloc Stream Facility, A Redesign of Application-Level Stream I/O" IEEE Computer, Vol. 27, No. 3, Mar. 1994, pp. 75-82.