Data Dictionary System: Maintainers Directories (gio

Indexgio
gopen
gopenmax
gclose
gfcntl
gsetbuf
gsetpos
gseek
gread
gwrite
gerror

gwritea, gwriteb, gwritec, gwritem - stream output

SYNOPSIS

#include "gio.h"
int gwritec(GFILE *stream, const void *buf , size_t size);
int gwritem(GFILE *stream, void **buf , size_t size);
int gwritea(GFILE *stream, void **buf , size_t size, GIO_ALIGN align);
int gwriteb(GFILE *stream, void **buf , size_t size, GIO_ALIGN align , size_t bias);

DESCRIPTION

gwritec is called to write data into the i/o stream referenced by stream. Up to size bytes are written from a buffer provided by the caller, beginning at buf. gwritem is called to write data into the i/o stream referenced by stream. The function reserves buffer space for at least size bytes 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-write, until the next operation on stream. The initial contents of the buffer are undefined. Behavior is undefined, if the caller does not initialize the entire buffer. A subsequent read or write on stream implicitly transfers the data.

gwritea is similar to gwritem, 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 gwritem.

gwriteb is similar to gwritea, except for a pointer 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.

RETURN VALUES

If positive, the function return value is the number of bytes actually written. The current file position is incremented by this amount. If the return value is less than the number of bytes requested, then an error has occurred. 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.

ERRORS

Potential errors are defined by write(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.

EXAMPLE

{  /* write 80 bytes, from a char buffer */
    GFILE *fp; char *buf; int n;
    n = gwritea(fp, &buf, 80, GIO_CHAR);
    /* now initialize entire buffer with data */
}

{  /* write 200 gpos_t structures */
    GFILE *fp; gpos_t *buf; int n;
    n = gwritea(fp, &buf, 200 * sizeof(gpos_t), GIO_MALLOC);
    /* now initialize entire buffer with data */
}

{  /* 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, 1)))
    gwritec(fp_out, buf, n);
}

FILES

/home/dds/include/gio.h
/home/dds/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.