substdio_in(3) substdio_in(3) NNAAMMEE substdio_in - substdio input routines SSYYNNTTAAXX ##iinncclluuddee <> int ssuubbssttddiioo__ggeett(&_s,_t_o,_l_e_n); int ssuubbssttddiioo__bbggeett(&_s,_t_o,_l_e_n); int ssuubbssttddiioo__ffeeeedd(&_s); char *ssuubbssttddiioo__ppeeeekk(&_s); void ssuubbssttddiioo__sseeeekk(&_s,_l_e_n); substdio _s; char *_t_o; int _l_e_n; DDEESSCCRRIIPPTTIIOONN ssuubbssttddiioo__ggeett reads at most _l_e_n characters from _s into the character array _t_o. It returns the number of characters read, 0 for end of file, or -1 for error, setting eerrrrnnoo appropriately. ssuubbssttddiioo__bbggeett has the same function as ssuubbssttddiioo__ggeett. The difference is what happens when there is no buffered data and _l_e_n exceeds the buffer size: ssuubbssttddiioo__ggeett tries to read _l_e_n characters, whereas ssuubbssttddiioo__bbggeett tries to read one buffer of characters. In some cases ssuubbssttddiioo__bbggeett will be more efficient than ssuubbssttddiioo__ggeett. ssuubbssttddiioo__ffeeeedd makes sure that there is buffered data, so that the next ssuubbssttddiioo__ggeett or ssuubbssttddiioo__bbggeett will succeed. If the buffer is empty, ssuubbssttddiioo__ffeeeedd 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, ssuubbssttddiioo__ffeeeedd leaves it alone and returns the number of buffered characters. ssuubbssttddiioo__ppeeeekk returns a pointer to the buffered data. ssuubbssttddiioo__sseeeekk throws away _l_e_n buffered characters, as if they had been read. _l_e_n must be at least 0 and at most the amount of buffered data. The ssuubbssttddiioo__PPEEEEKK and ssuubbssttddiioo__SSEEEEKK macros behave the same way as ssuubb-- ssttddiioo__ppeeeekk and ssuubbssttddiioo__sseeeekk but may evaluate their arguments several times. The point of ssuubbssttddiioo__ppeeeekk and ssuubbssttddiioo__sseeeekk 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 SSUUBBSSTTDDIIOO__IINNSSIIZZEE macro is defined as a reasonably large input buffer size for ssuubbssttddiioo__ffddbbuuff. IINNTTEERRNNAALLSS When a ssuubbssttddiioo variable _s is used for input, there is free buffer space from _s..xx to _s..xx + _s..nn; data is buffered from _s..xx + _s..nn to _s..xx + _s..nn + _s..pp; the total buffer length is _s..nn + _s..pp. SSEEEE AALLSSOO substdio(3) substdio_in(3)