bglibs: iobuf: I/O Buffer Management

bglibs

Data Structures
iobuf: I/O Buffer Management

## Data Structures
struct | iobuf

## Mass copying functions.
int | iobuf_copy (ibuf *in, obuf *out)
int | iobuf_copyflush (ibuf *in, obuf *out)
int | ibuf_copytofd (ibuf *in, int out)
int | obuf_copyfromfd (int in, obuf *out)

## Status Flags
unsigned | iobuf_bufsize
#define | IOBUF_EOF 1
#define | IOBUF_ERROR 2
#define | IOBUF_TIMEOUT 4
#define | IOBUF_BADFLAGS 0xf
#define | IOBUF_SEEKABLE 0x10
#define | IOBUF_NEEDSCLOSE 0x20
#define | IOBUF_NEEDSFREE 0x40
#define | IOBUF_NEEDSMUNMAP 0x80

## Common
typedef struct iobuf | iobuf
int | iobuf_init (iobuf *io, int fd, unsigned bufsize, char *buffer, unsigned flags)
int | iobuf_close (iobuf *io)
int | iobuf_timeout (iobuf *io, int poll_out)
#define | IOBUF_SET_ERROR(io)
#define | iobuf_closed(io) ((io)->fd == -1)
#define | iobuf_error(io) ((io)->flags & IOBUF_ERROR)
#define | iobuf_timedout(io) ((io)->flags & IOBUF_TIMEOUT)
#define | iobuf_bad(io) ((io)->flags & IOBUF_BADFLAGS)

## 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

## ◆ iobuf_bad

#define iobuf_bad | ( |  | io | ) | ((io)->flags & IOBUF_BADFLAGS)

True if the `iobuf` is in a "bad" state.

Referenced by ibuf_refill(), obuf_flush(), obuf_putc(), obuf_seek(), obuf_write(), and obuf_write_large().

## ◆ IOBUF_BADFLAGS

#define IOBUF_BADFLAGS 0xf

Mask of all the error type flags.

## ◆ iobuf_closed

#define iobuf_closed | ( |  | io | ) | ((io)->fd == -1)

True if the `iobuf` has been closed.

## ◆ IOBUF_EOF

#define IOBUF_EOF 1

Reading reached end of file.

Referenced by ibuf_eof(), ibuf_read_large(), ibuf_refill(), and ibuf_seek().

## ◆ IOBUF_ERROR

#define IOBUF_ERROR 2

The iobuf has encountered an error.

Referenced by obuf_seek().

## ◆ iobuf_error

#define iobuf_error | ( |  | io | ) | ((io)->flags & IOBUF_ERROR)

True if the `iobuf` has an error flag.

## ◆ IOBUF_NEEDSCLOSE

#define IOBUF_NEEDSCLOSE 0x20

The file descriptor needs to be closed.

Referenced by ibuf_open(), iobuf_close(), and obuf_open().

## ◆ IOBUF_NEEDSFREE

#define IOBUF_NEEDSFREE 0x40

The buffer needs to be deallocated with `free`

Referenced by iobuf_close(), and iobuf_init().

## ◆ IOBUF_NEEDSMUNMAP

#define IOBUF_NEEDSMUNMAP 0x80

The buffer needs to be deallocated with `munmap`

Referenced by iobuf_close(), and iobuf_init().

## ◆ IOBUF_SEEKABLE

#define IOBUF_SEEKABLE 0x10

`lseek` is possible on the file descriptor.

Referenced by ibuf_open(), and obuf_open().

## ◆ IOBUF_SET_ERROR

#define IOBUF_SET_ERROR | ( |  | io | ) |

Value:
do{ \
io->flags |= IOBUF_ERROR; \
io->errnum = errno; \
return 0; \
}while(0)
IOBUF_ERROR
#define IOBUF_ERROR
Definition: iobuf_common.h:27

Set the error flag, save `errno`, and return false.

Referenced by ibuf_read_large(), ibuf_refill(), ibuf_seek(), iobuf_timeout(), obuf_flush(), obuf_sync(), and obuf_write_large().

## ◆ iobuf_timedout

#define iobuf_timedout | ( |  | io | ) | ((io)->flags & IOBUF_TIMEOUT)

True if the input or output to the `iobuf` previously timed out.

## ◆ IOBUF_TIMEOUT

#define IOBUF_TIMEOUT 4

The timeout expired before the read or write could be completed.

Referenced by iobuf_timeout().

## Function Documentation

## ◆ ibuf_copytofd()

int ibuf_copytofd | ( | ibuf * | in,
|  | int | out
| ) |  |

Copy all the data from an `ibuf` to an output file descriptor.

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

## ◆ iobuf_close()

int iobuf_close | ( | iobuf * | io | ) |

Close an `iobuf` and deallocate the buffer.

References buffer, bufsize, fd, flags, IOBUF_NEEDSCLOSE, IOBUF_NEEDSFREE, and IOBUF_NEEDSMUNMAP.

Referenced by obuf_close().

## ◆ iobuf_copy()

int iobuf_copy | ( | ibuf * | in,
|  | obuf * | out
| ) |  |

Copy all the data from an `ibuf` to an `obuf`.

References buffer, buflen, bufstart, ibuf_eof(), ibuf_error, ibuf_refill(), ibuf::io, obuf_error, and obuf_write_large().

Referenced by iobuf_copyflush().

## ◆ iobuf_copyflush()

int iobuf_copyflush | ( | ibuf * | in,
|  | obuf * | out
| ) |  |

Copy all the data from an `ibuf` to an `obuf`, and flush the `obuf` after writing is completed.

References iobuf_copy(), and obuf_flush().

## ◆ iobuf_init()

int iobuf_init | ( | iobuf * | io,
|  | int | fd,
|  | unsigned | bufsize,
|  | char * | buffer,
|  | unsigned | flags
| ) |  |

Initialize an `iobuf` structure.

References buffer, bufsize, fd, flags, iobuf_bufsize, IOBUF_NEEDSFREE, IOBUF_NEEDSMUNMAP, obuf_puti(), obuf_puts, obuf_putu(), obuf_putx(), and outbuf.

Referenced by ibuf_init(), and obuf_init().

## ◆ iobuf_timeout()

int iobuf_timeout | ( | iobuf * | io,
|  | int | poll_out
| ) |  |

Wait for a file descriptor to be ready for reading or writing.

References fd, flags, IOBUF_SET_ERROR, IOBUF_TIMEOUT, and timeout.

Referenced by ibuf_read_large(), ibuf_refill(), obuf_flush(), and obuf_write_large().

## ◆ obuf_copyfromfd()

int obuf_copyfromfd | ( | int | in,
|  | obuf * | out
| ) |  |

Copy all the data from an input file descriptor to an `obuf`.

References buffer, buflen, obuf::bufpos, bufsize, obuf::count, obuf::io, obuf_error, and obuf_flush().

## Variable Documentation

## ◆ iobuf_bufsize

unsigned iobuf_bufsize

The default iobuf buffer size, defaults to 8192.

Referenced by iobuf_init().