gio - Geoscience buffered input/output package

SYNOPSIS

#include "gio.h"
GFILE *gstdin, *gstdout, *gstderr;

DESCRIPTION

Read and write functions may be used to access GIO streams. Functions are provided that use traditional "copy" semantics, where the caller provides a buffer to read or write. Other functions return pointers into buffers managed by GIO. The functions that use "pointer" semantics offer three advantages. Application code may be reduced, because i/o buffers don't have to be allocated and freed. Second, total memory usage may be reduced, because redundant buffers are eliminated. Third, copying of data between redundant buffers is minimized.

Pointer semantics introduce one complexity into the API. The caller must specify constraints on the buffer address that is returned by the i/o function. For example, the caller may need to reference the buffer as an array of floats, shorts, or characters. Each type may have a different minimum alignment. If the address is not properly aligned, access errors will occur or efficiency will suffer.

Buffer address constaints are specified with the align argument. Maximum efficiency is obtained when the nominal buffer address is congruent with align. If not congruent, GIO uses an auxiliary buffer to achieve alignment and may copy data to/from the primary buffer. The GIO_ALIGN typedef provides an enumerated value for aligning each "C" type. The GIO_MALLOC value is suiteable for any type, like pointers returned by malloc. It should be used for buffers containing structures and unions. 

typedef enum {  /* GIO buffer address constraints */
        GIO_CHAR            = GIODEF_ALIGN_CHAR,
        GIO_SHORT           = GIODEF_ALIGN_SHORT,
        GIO_INT             = GIODEF_ALIGN_INT,
        GIO_LONG            = GIODEF_ALIGN_LONG,
        GIO_LONG_LONG       = GIODEF_ALIGN_LONG_LONG,
        GIO_FLOAT           = GIODEF_ALIGN_FLOAT,
        GIO_DOUBLE          = GIODEF_ALIGN_DOUBLE,
        GIO_LONG_DOUBLE     = GIODEF_ALIGN_LONG_DOUBLE,
        GIO_CHAR_PTR        = GIODEF_ALIGN_CHAR_PTR,
        GIO_SHORT_PTR       = GIODEF_ALIGN_SHORT_PTR,
        GIO_INT_PTR         = GIODEF_ALIGN_INT_PTR,
        GIO_LONG_PTR        = GIODEF_ALIGN_LONG_PTR,
        GIO_LONG_LONG_PTR   = GIODEF_ALIGN_LONG_LONG_PTR,
        GIO_FLOAT_PTR       = GIODEF_ALIGN_FLOAT_PTR,
        GIO_DOUBLE_PTR      = GIODEF_ALIGN_DOUBLE_PTR,
        GIO_LONG_DOUBLE_PTR = GIODEF_ALIGN_LONG_DOUBLE_PTR,
        GIO_VOID_PTR        = GIODEF_ALIGN_VOID_PTR,
        GIO_ENUM            = GIODEF_ALIGN_ENUM,
        GIO_MALLOC          = GIODEF_ALIGN_MALLOC
} GIO_ALIGN;
GIO supports "huge" files and offsets, greater than 2 gigabytes. The "gpos_t" typedef is nominally a 64 bit signed integer. If the host doesn't support this binary type, it is emulated within GIO functions.

Applications may use a combination of "copy" and "pointer" semantics on the same i/o stream.

SPEED

Comparision of measured performance using GIO and other packages. Contrast several access patterns and host vagaries.

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.

Deferred: line buffering, scanf, printf.

Extensions: gunread, flags for gsetvbuf.

FILES

$DDSROOT/include/gio.h
$DDSROOT/include/$TARCH/fgio.h (Fortran)
$DDSROOT/lib/$TARCH/libgio.a

STANDARDS

Function names, return values and formal arguments parallel stdio. The GFILE typedef is similar to, but not compatible with stdio FILE, yet. The same is true for gstdin, gstdout, and gstderr. The names of functions which use GFILE are prefixed by "g", instead of "f". This simplifies the transition, if this package is integrated into stdio, where FILE and GFILE are compatible.

Global name space pollution is minimized by prefixing all symbols with "GIO", or "gio" unless they are actually part of the application program interface.

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.