ibuf: Input Buffer Managemenet

## Data Structures

struct | ibuf

## Macros

#define | ibuf_close(in) iobuf_close(&((in)->io))
#define | ibuf_closed(in) iobuf_closed(&((in)->io))
#define | ibuf_error(in) iobuf_error(&((in)->io))
#define | ibuf_timedout(in) iobuf_timedout(&((in)->io))
#define | ibuf_rewind(in) ibuf_seek(in,0)
#define | ibuf_seekfwd(in, off) ibuf_seek(ibuf_tell(in)+(offset))

## Typedefs

typedef int(* | ibuf_fn) (int, void *, unsigned long)
typedef struct ibuf | ibuf

## Functions

int | ibuf_init (ibuf *in, int fd, ibuf_fn fn, unsigned flags, unsigned bufsize)
int | ibuf_open (ibuf *in, const char *filename, unsigned bufsize)
int | ibuf_eof (ibuf *in)
int | ibuf_refill (ibuf *in)
int | ibuf_read_large (ibuf *in, char *data, unsigned datalen)
int | ibuf_read (ibuf *in, char *data, unsigned datalen)
unsigned | ibuf_tell (ibuf *in)
int | ibuf_seek (ibuf *in, unsigned offset)
int | ibuf_peek (ibuf *in, char *ch)
int | ibuf_getc (ibuf *in, char *ch)
int | ibuf_getu (ibuf *in, unsigned long *data)
int | ibuf_gets (ibuf *in, char *data, unsigned datalen, char boundary)
int | ibuf_getstr (ibuf *in, struct str *s, char boundary)
int | ibuf_getstr_crlf (ibuf *in, struct str *s)
int | ibuf_getnetstring (ibuf *in, struct str *s)
int | ibuf_readall (ibuf *in, struct str *s)
int | ibuf_openreadclose (const char *filename, struct str *s)

## Variables

ibuf | inbuf

## Detailed Description

Calling Convention

Unless otherwise specified, the return value is non-zero (true) if the entire requested operation completed, and `0` (false) otherwise.

## Macro Definition Documentation

## ibuf_close

#define ibuf_close | ( |  | in | ) | iobuf_close(&((in)->io))

Close the `ibuf`.

Referenced by ibuf_openreadclose().

## ibuf_closed

#define ibuf_closed | ( |  | in | ) | iobuf_closed(&((in)->io))

Test if the `ibuf` has been closed.

## ibuf_error

#define ibuf_error | ( |  | in | ) | iobuf_error(&((in)->io))

Test if the `ibuf` is in an error state.

Referenced by ibuf_copytofd(), ibuf_getc(), ibuf_gets(), ibuf_getstr(), ibuf_peek(), ibuf_read(), ibuf_read_large(), ibuf_readall(), and iobuf_copy().

## ibuf_rewind

#define ibuf_rewind | ( |  | in | ) | ibuf_seek(in,0)

Set the effective read position to the start of the file.

## ibuf_seekfwd

#define ibuf_seekfwd | ( |  | in,
|  |  | off
| ) |  | ibuf_seek(ibuf_tell(in)+(offset))

Set the effective read position `off` bytes forward.

## ibuf_timedout

#define ibuf_timedout | ( |  | in | ) | iobuf_timedout(&((in)->io))

Test if the last `ibuf` read timed out.

Referenced by ibuf_gets(), and ibuf_getstr().

## Typedef Documentation

## ibuf

typedef struct ibuf ibuf

Input specific buffer typedef.

## ibuf_fn

typedef int(* ibuf_fn) (int, void *, unsigned long)

`ibuf` read function pointer prototype.

## Function Documentation

## ibuf_eof()

int ibuf_eof | ( | ibuf * | in | ) |

Test if the `ibuf` has reaced end of file.

References iobuf::buflen, iobuf::bufstart, iobuf::flags, io, and IOBUF_EOF.

Referenced by ibuf_copytofd(), ibuf_getc(), ibuf_gets(), ibuf_getstr(), ibuf_peek(), ibuf_read(), ibuf_read_large(), ibuf_readall(), and iobuf_copy().

## ibuf_getc()

int ibuf_getc | ( | ibuf * | in,
|  | char * | ch
| ) |  |

Retrieve a single character from the `ibuf`.

References iobuf::buffer, iobuf::buflen, iobuf::bufstart, count, ibuf_eof(), ibuf_error, ibuf_refill(), io, obuf_putf(), and outbuf.

Referenced by ibuf_getnetstring(), and ibuf_getu().

## ibuf_getnetstring()

int ibuf_getnetstring | ( | ibuf * | in,
|  | struct str * | s
| ) |  |

Read a netstring from the given `ibuf` .

If the input is not a netstring, `errno` (and `in->io.errnum` ) will be set to `EPROTOTYPE` and the state of `in` will be undefined.

References iobuf::errnum, ibuf_getc(), ibuf_getu(), ibuf_read(), io, str::len, obuf_putf(), outbuf, str::s, and str_ready.

## ibuf_gets()

int ibuf_gets | ( | ibuf * | in,
|  | char * | data,
|  | unsigned | datalen,
|  | char | boundary
| ) |  |

Read a line from the `ibuf` into a C string.

References iobuf::buffer, iobuf::buflen, iobuf::bufstart, count, ibuf_eof(), ibuf_error, ibuf_refill(), ibuf_timedout, io, obuf_putf(), and outbuf.

## ibuf_getstr()

int ibuf_getstr | ( | ibuf * | in,
|  | struct str * | s,
|  | char | boundary
| ) |  |

Read a line from the `ibuf` into a dynamic string.

References iobuf::buffer, iobuf::buflen, iobuf::bufstart, count, ibuf_eof(), ibuf_error, ibuf_refill(), ibuf_timedout, io, str_catc(), and str_truncate().

Referenced by ibuf_getstr_crlf().

## ibuf_getstr_crlf()

int ibuf_getstr_crlf | ( | ibuf * | in,
|  | struct str * | s
| ) |  |

Read a line from the `ibuf` into a dynamic string, terminated by a CR+LF pair.

References count, ibuf_getstr(), str::len, obuf_putf(), outbuf, str::s, and str_truncate().

## ibuf_getu()

int ibuf_getu | ( | ibuf * | in,
|  | unsigned long * | data
| ) |  |

Read an unsigned long from the `ibuf`

References ibuf_getc(), and ibuf_peek().

Referenced by ibuf_getnetstring().

## ibuf_init()

int ibuf_init | ( | ibuf * | in,
|  | int | fd,
|  | ibuf_fn | fn,
|  | unsigned | flags,
|  | unsigned | bufsize
| ) |  |

Initialize an `ibuf` from an already-opened file descriptor.

References count, io, iobuf_init(), and readfn.

Referenced by ibuf_open().

## ibuf_open()

int ibuf_open | ( | ibuf * | in,
|  | const char * | filename,
|  | unsigned | bufsize
| ) |  |

Initialize an `ibuf` by opening a file for reading.

References ibuf_init(), IOBUF_NEEDSCLOSE, and IOBUF_SEEKABLE.

Referenced by ibuf_openreadclose().

## ibuf_openreadclose()

int ibuf_openreadclose | ( | const char * | filename,
|  | struct str * | out
| ) |  |

Open and read the entire file into the `str` .

References ibuf_close, ibuf_open(), and ibuf_readall().

Referenced by dns_read_resolvconf().

## ibuf_peek()

int ibuf_peek | ( | ibuf * | in,
|  | char * | ch
| ) |  |

Retrieve the next character in the `ibuf` without advancing the current read position.

References iobuf::buffer, iobuf::buflen, iobuf::bufstart, ibuf_eof(), ibuf_error, ibuf_refill(), and io.

Referenced by ibuf_getu().

## ibuf_read()

int ibuf_read | ( | ibuf * | in,
|  | char * | data,
|  | unsigned | datalen
| ) |  |

Read a block of data from the `ibuf`

Returns true only if the entire block was read. If the return value is false, the caller will need to check if a partial block was read.

References iobuf::buffer, iobuf::buflen, iobuf::bufsize, iobuf::bufstart, count, ibuf_eof(), ibuf_error, ibuf_read_large(), ibuf_refill(), and io.

Referenced by ibuf_getnetstring().

## ibuf_read_large()

int ibuf_read_large | ( | ibuf * | in,
|  | char * | data,
|  | unsigned | datalen
| ) |  |

Read a block of data from the `ibuf`.

This routine differs from `ibuf_read` in that the data is, as much as is possible, read directly into the given buffer, rather than first being read into the `iobuf` buffer and then into the given buffer. `ibuf_read` automatically calls this routine if the requested `datalen` is larger than or equal to the `iobuf` buffer size.

References iobuf::buffer, iobuf::buflen, iobuf::bufstart, count, iobuf::fd, iobuf::flags, ibuf_eof(), ibuf_error, io, IOBUF_EOF, IOBUF_SET_ERROR, iobuf_timeout(), iobuf::offset, readfn, and iobuf::timeout.

Referenced by ibuf_read().

## ibuf_readall()

int ibuf_readall | ( | ibuf * | in,
|  | struct str * | out
| ) |  |

Read the remainder of the `ibuf` into the `str`.

References iobuf::buffer, iobuf::buflen, iobuf::bufstart, ibuf_eof(), ibuf_error, ibuf_refill(), io, and str_catb().

Referenced by ibuf_openreadclose().

## ibuf_refill()

int ibuf_refill | ( | ibuf * | in | ) |

(Re)fill the buffer from the file descriptor.

Note
  This function may only be called when the buffer is completely empty.

References iobuf::buffer, iobuf::buflen, iobuf::bufsize, iobuf::bufstart, iobuf::fd, iobuf::flags, io, iobuf_bad, IOBUF_EOF, IOBUF_SET_ERROR, iobuf_timeout(), iobuf::offset, readfn, and iobuf::timeout.

Referenced by ibuf_copytofd(), ibuf_getc(), ibuf_gets(), ibuf_getstr(), ibuf_peek(), ibuf_read(), ibuf_readall(), and iobuf_copy().

## ibuf_seek()

int ibuf_seek | ( | ibuf * | in,
|  | unsigned | offset
| ) |  |

Set the effective read position.

References iobuf::buflen, iobuf::bufstart, count, iobuf::fd, iobuf::flags, io, IOBUF_EOF, IOBUF_SET_ERROR, and iobuf::offset.

## ibuf_tell()

unsigned ibuf_tell | ( | ibuf * | in | ) |

Look up the current effective read position.

References iobuf::buflen, iobuf::bufstart, io, and iobuf::offset.

## Variable Documentation

## inbuf

ibuf inbuf

Input buffer for `stdin`