substdio_in(3)

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.

SEE ALSO
substdio(3)