io_ctx

NAME: io_ctx - standard input/output abstraction

SYNOPSIS

#include <io_ctx.h>

int IO_delete(ctxp)
  io_ctx    *ctxp;

int IO_fread(ptr, size, nitems, ctx)
  char      *ptr;
  int        size;
  int        nitems;
  io_ctx     ctx;

int IO_fwrite(ptr, size, nitems, ctx)
  char      *ptr;
  int        size;
  int        nitems;
  io_ctx     ctx;

int IO_fgetc(ctx)
  io_ctx     ctx;

int IO_fputc(c, ctx)
  int        c;
  io_ctx     ctx;

int IO_ungetc(c, ctx)
  char       c;
  io_ctx     ctx;

int IO_fflush(ctx)
  io_ctx     ctx;

long IO_ftell(ctx)
  io_ctx     ctx;

int IO_fseek(ctx, offset, ptrname)
  io_ctx     ctx;
  long       offset;
  position   ptrname;

typedef int position;        /* either BOF, CUR, or EOF */ 
#define FSEEK_BOF   0
#define FSEEK_CUR   1
#define FSEEK_EOF   2

DESCRIPTION

io_ctx is an input/output abstraction based on the UNIX stdio package. Except for IO_delete() (which is unique to io_ctx), it is intended to behave identically to the stdio package.

IO_delete() deletes the io_ctx, and frees any memory that io_ctx functions have allocated. File handles, pointers to memory, and so on that have been passed to io_ctx functions are not affected by a call to IO_delete(). An io_ctx is no longer usable following a call to IO_delete().

See documentation on stdio for information on the individual stdio-based routines: IO_fread(), IO_fwrite(), IO_fgetc(), IO_fputc(), IO_ungetc(), IO_fflush(), IO_ftell(), and IO_fseek().

RETURN VALUES

On success, IO_delete() returns NO_ERROR. On failure, IO_delete() returns IO_CTX_ERR_BAD_PARAMETER.

See UNIX documentation on stdio for the return values of the individual stdio-based routines: IO_fread(), IO_fwrite(), IO_fgetc(), IO_fputc(), IO_ungetc(), IO_fflush(), IO_ftell(), and IO_fseek().

See Return Values for descriptions of individual error codes. For documentation on displaying or logging return values, see error_ctx.

SEE ALSO: io_ctx_memio, io_ctx_stdio

NOTES: The ctx argument must be initialized prior to use. See io_ctx_memio, io_ctx_stdio, or io_ctx_sysio for information on creating an io_ctx.
IO_delete(), IO_fread(), IO_fwrite(), IO_fgetc(), IO_fputc(), IO_ungetc(), IO_fflush(), IO_ftell(), and IO_fseek() are macros, but only the ctx argument appears more than once in the macro expansion. Therefore, it is safe to use computed arguments, such as those using the ++ or -- operator, for all arguments except ctx. These macros should always be used to invoke the underlying functions, rather than invoking the functions directly.

BUGS: This document describes a beta implementation. The information contained in this document may be incomplete and is subject to change.