substdio_in

Section: C Library Functions (3)
Index Return to Main Contents

NAME

substdio_in - substdio input routines

SYNTAX

#include <substdio.h>

int substdio_get(&s,to,len);

int substdio_bget(&s,to,len);

int substdio_feed(&s);

char *substdio_peek(&s);

void substdio_seek(&s,len);

substdio s;
char *to;
int len;

DESCRIPTION

substdio_get reads at most len characters from s into the character array to. It returns the number of characters read, 0 for end of file, or -1 for error, setting errno appropriately.

substdio_bget has the same function as substdio_get. The difference is what happens when there is no buffered data and len exceeds the buffer size: substdio_get tries to read len characters, whereas substdio_bget tries to read one buffer of characters. In some cases substdio_bget will be more efficient than substdio_get.

substdio_feed makes sure that there is buffered data, so that the next substdio_get or substdio_bget will succeed. If the buffer is empty, substdio_feed tries to fill it; it returns 0 for end of file, -1 for error, or the number of buffered characters on success. If the buffer already had data, substdio_feed leaves it alone and returns the number of buffered characters.

substdio_peek returns a pointer to the buffered data.

substdio_seek throws away len buffered characters, as if they had been read. len must be at least 0 and at most the amount of buffered data.

The substdio_PEEK and substdio_SEEK macros behave the same way as substdio_peek and substdio_seek but may evaluate their arguments several times.

The point of substdio_peek and substdio_seek is to read data without unnecessary copies. Sample code:

  for (;;) {

    n = substdio_feed(s);

    if (n <= 0) return n;

    x = substdio_PEEK(s);

    handle(x,n);

    substdio_SEEK(s,n);

  }

The SUBSTDIO_INSIZE macro is defined as a reasonably large input buffer size for substdio_fdbuf.

INTERNALS

When a substdio variable s is used for input, there is free buffer space from s.x to s.x + s.n; data is buffered from s.x + s.n to s.x + s.n + s.p; the total buffer length is s.n + s.p.