obuf: Output Buffer Management

## Data Structures

struct | obuf

## Macros

#define | OBUF_CREATE O_CREAT
#define | OBUF_EXCLUSIVE O_EXCL
#define | OBUF_TRUNCATE O_TRUNC
#define | OBUF_APPEND O_APPEND
#define | obuf_error(out)
#define | obuf_closed(out)
#define | obuf_timedout(out)
#define | obuf_rewind(out)
#define | obuf_tell(out)
#define | obuf_puts(out, str)
#define | obuf_putstr(out, str)

## Typedefs

typedef int(* | obuf_fn) (int, const void *, unsigned long)
typedef struct obuf | obuf

## Functions

int | obuf_init (obuf *out, int fd, obuf_fn fn, unsigned flags, unsigned bufsize)
int | obuf_open (obuf *out, const char *filename, int oflags, int mode, unsigned bufsize)
int | obuf_close (obuf *out)
int | obuf_flush (obuf *out)
int | obuf_sync (obuf *out)
int | obuf_write_large (obuf *out, const char *data, unsigned datalen)
int | obuf_write (obuf *out, const char *data, unsigned datalen)
int | obuf_seek (obuf *out, unsigned offset)
int | obuf_pad (obuf *out, unsigned width, char ch)
int | obuf_endl (obuf *out)
int | obuf_putc (obuf *out, char ch)
int | obuf_put2s (obuf *out, const char *s1, const char *s2)
int | obuf_put3s (obuf *out, const char *s1, const char *s2, const char *s3)
int | obuf_put4s (obuf *out, const char *s1, const char *s2, const char *s3, const char *s4)
int | obuf_put5s (obuf *out, const char *s1, const char *s2, const char *s3, const char *s4, const char *s5)
int | obuf_put6s (obuf *out, const char *s1, const char *s2, const char *s3, const char *s4, const char *s5, const char *s6)
int | obuf_put7s (obuf *out, const char *s1, const char *s2, const char *s3, const char *s4, const char *s5, const char *s6, const char *s7)
int | obuf_putns (obuf *out, unsigned int count,...)
int | obuf_putf (obuf *out, const char *format,...)
int | obuf_putfv (obuf *out, const char *format, va_list ap)
int | obuf_putsflush (obuf *out, const char *s)
int | obuf_puti (obuf *out, long data)
int | obuf_putiw (obuf *out, long data, unsigned width, char pad)
int | obuf_putu (obuf *out, unsigned long data)
int | obuf_putuw (obuf *out, unsigned long data, unsigned width, char pad)
int | obuf_putill (obuf *out, long long data)
int | obuf_putiwll (obuf *out, long long data, unsigned width, char pad)
int | obuf_putull (obuf *out, unsigned long long data)
int | obuf_putuwll (obuf *out, unsigned long long data, unsigned width, char pad)
int | obuf_putx (obuf *out, unsigned long data)
int | obuf_putxw (obuf *out, unsigned long data, unsigned width, char pad)
int | obuf_putX (obuf *out, unsigned long data)
int | obuf_putXw (obuf *out, unsigned long data, unsigned width, char pad)
int | obuf_putxll (obuf *out, unsigned long long data)
int | obuf_putxwll (obuf *out, unsigned long long data, unsigned width, char pad)
int | obuf_putXll (obuf *out, unsigned long long data)
int | obuf_putXwll (obuf *out, unsigned long long data, unsigned width, char pad)
int | obuf_putsnumw (obuf *out, long num, unsigned width, char pad, unsigned base, const char *digits)
int | obuf_putunumw (obuf *out, unsigned long num, unsigned width, char pad, unsigned base, const char *digits)
int | obuf_putsllnumw (obuf *out, long long num, unsigned width, char pad, unsigned base, const char *digits)
int | obuf_putullnumw (obuf *out, unsigned long long num, unsigned width, char pad, unsigned base, const char *digits)
int | obuf_putnetstring (obuf *out, const char *data, unsigned datalen)
int | obuf_sign_pad (obuf *out, int sign, unsigned width, char pad)

## Variables

obuf | outbuf
obuf | errbuf
const char obuf_dec_digits[10] | __DEPRECATED__
const char | obuf_hex_lcase_digits [16] = "0123456789abcdef"
const char | obuf_hex_ucase_digits [16] = "0123456789ABCDEF"

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

## OBUF_APPEND

#define OBUF_APPEND O_APPEND

All writes go to the end of the file.

## obuf_closed

#define obuf_closed | ( |  | out | ) |

Value:
iobuf_closed(&(out)->io)
iobuf_closed
#define iobuf_closed(io)
Definition iobuf_common.h:83

Test if the `obuf` has been closed.

## OBUF_CREATE

#define OBUF_CREATE O_CREAT

Create the file if it does not already exist.

## obuf_error

#define obuf_error | ( |  | out | ) |

Value:
iobuf_error(&(out)->io)
iobuf_error
#define iobuf_error(io)
Definition iobuf_common.h:85

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

Referenced by iobuf_copy(), and obuf_copyfromfd().

## OBUF_EXCLUSIVE

#define OBUF_EXCLUSIVE O_EXCL

If `OBUF_CREATE` is set, fail to create the file if it already exists.

## obuf_puts

#define obuf_puts | ( |  | out,
|  |  | str )

Value:
obuf_write(out,str,strlen(str))
obuf_write
int obuf_write(obuf *out, const char *data, unsigned datalen)
Definition obuf_write.c:30
str
Definition str.h:31

Write a C string to the `obuf`

Referenced by obuf_put2s(), obuf_put3s(), obuf_put4s(), obuf_put5s(), obuf_put6s(), obuf_put7s(), obuf_putns(), and obuf_putsflush().

## obuf_putstr

#define obuf_putstr | ( |  | out,
|  |  | str )

Value:
obuf_write(out,(str)->s,(str)->len)

Write a dynamic string to the `iobuf`

## obuf_rewind

#define obuf_rewind | ( |  | out | ) |

Value:
obuf_seek(out,0)
obuf_seek
int obuf_seek(obuf *out, unsigned offset)
Definition obuf_seek.c:7

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

## obuf_tell

#define obuf_tell | ( |  | out | ) |

Value:
((out)->io.offset+(out)->bufpos)

Look up the current effective write position.

## obuf_timedout

#define obuf_timedout | ( |  | out | ) |

Value:
iobuf_timedout(&((out)->io))
iobuf_timedout
#define iobuf_timedout(io)
Definition iobuf_common.h:87

Test if the last `obuf` write timed out.

## OBUF_TRUNCATE

#define OBUF_TRUNCATE O_TRUNC

If the file exists, truncate it to length 0.

## Typedef Documentation

## obuf

typedef struct obuf obuf

Output specific buffer typedef.

## obuf_fn

typedef int(* obuf_fn) (int, const void *, unsigned long)

`obuf` write function pointer prototype.

## Function Documentation

## obuf_close()

int obuf_close | ( | obuf * | out | ) |

Flush and close the `obuf`

References obuf::io, iobuf_close(), and obuf_flush().

## obuf_endl()

int obuf_endl | ( | obuf * | out | ) |

Write a newline to the `obuf` and flush it.

References obuf_flush(), and obuf_putc().

## obuf_flush()

int obuf_flush | ( | obuf * | out | ) |

Write all pending data in the `obuf` to the file descriptor.

References iobuf::buffer, iobuf::buflen, obuf::bufpos, iobuf::bufstart, iobuf::fd, obuf::io, iobuf_bad, IOBUF_SET_ERROR, iobuf_timeout(), iobuf::offset, iobuf::timeout, and obuf::writefn.

Referenced by iobuf_copyflush(), obuf_close(), obuf_copyfromfd(), obuf_endl(), obuf_putc(), obuf_putsflush(), obuf_seek(), obuf_sync(), obuf_write(), and obuf_write_large().

## obuf_init()

int obuf_init | ( | obuf * | out,
|  | int | fd,
|  | obuf_fn | fn,
|  | unsigned | flags,
|  | unsigned | bufsize )

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

References obuf::bufpos, obuf::count, obuf::io, iobuf_init(), and obuf::writefn.

Referenced by obuf_open().

## obuf_open()

int obuf_open | ( | obuf * | out,
|  | const char * | filename,
|  | int | oflags,
|  | int | mode,
|  | unsigned | bufsize )

Initialize an `obuf` by opening a file for writing.

References IOBUF_NEEDSCLOSE, IOBUF_SEEKABLE, and obuf_init().

## obuf_pad()

int obuf_pad | ( | obuf * | out,
|  | unsigned | width,
|  | char | ch )

Pad the output with `width` instances of the single character `ch`.

References obuf_putc().

Referenced by obuf_sign_pad().

## obuf_put2s()

int obuf_put2s | ( | obuf * | out,
|  | const char * | s1,
|  | const char * | s2 )

Write 2 C strings to the `obuf`

References obuf_puts.

## obuf_put3s()

int obuf_put3s | ( | obuf * | out,
|  | const char * | s1,
|  | const char * | s2,
|  | const char * | s3 )

Write 3 C strings to the `obuf`

References obuf_puts.

## obuf_put4s()

int obuf_put4s | ( | obuf * | out,
|  | const char * | s1,
|  | const char * | s2,
|  | const char * | s3,
|  | const char * | s4 )

Write 4 C strings to the `obuf`

References obuf_puts.

## obuf_put5s()

int obuf_put5s | ( | obuf * | out,
|  | const char * | s1,
|  | const char * | s2,
|  | const char * | s3,
|  | const char * | s4,
|  | const char * | s5 )

Write 5 C strings to the `obuf`

References obuf_puts.

## obuf_put6s()

int obuf_put6s | ( | obuf * | out,
|  | const char * | s1,
|  | const char * | s2,
|  | const char * | s3,
|  | const char * | s4,
|  | const char * | s5,
|  | const char * | s6 )

Write 6 C strings to the `obuf`

References obuf_puts.

## obuf_put7s()

int obuf_put7s | ( | obuf * | out,
|  | const char * | s1,
|  | const char * | s2,
|  | const char * | s3,
|  | const char * | s4,
|  | const char * | s5,
|  | const char * | s6,
|  | const char * | s7 )

Write 7 C strings to the `obuf`

References obuf_puts.

## obuf_putc()

int obuf_putc | ( | obuf * | out,
|  | char | ch )

Write a single character to the `obuf`

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

Referenced by obuf_endl(), obuf_pad(), obuf_putnetstring(), and obuf_sign_pad().

## obuf_putf()

int obuf_putf | ( | obuf * | out,
|  | const char * | format,
|  |  | ... )

Write a formatted string using `fmt_multi` from variable arguments

References obuf_putfv().

## obuf_putfv()

int obuf_putfv | ( | obuf * | out,
|  | const char * | format,
|  | va_list | ap )

Write a formatted string using `fmt_multi` from a `va_list`

References fmt_multiv(), and obuf_write().

Referenced by obuf_putf().

## obuf_puti()

int obuf_puti | ( | obuf * | out,
|  | long | data )

Write a signed integer as decimal to the `obuf`.

References fmt_lcase_digits, and obuf_putsnumw().

## obuf_putill()

int obuf_putill | ( | obuf * | out,
|  | long long | data )

Write a signed long long integer as decimal to the `obuf`.

References fmt_lcase_digits, and obuf_putsllnumw().

## obuf_putiw()

int obuf_putiw | ( | obuf * | out,
|  | long | data,
|  | unsigned | width,
|  | char | pad )

Write a signed integer as decimal to the `obuf` with padding.

References fmt_lcase_digits, and obuf_putsnumw().

## obuf_putiwll()

int obuf_putiwll | ( | obuf * | out,
|  | long long | data,
|  | unsigned | width,
|  | char | pad )

Write a signed long long integer as decimal to the `obuf` with padding.

References fmt_lcase_digits, and obuf_putsllnumw().

## obuf_putnetstring()

int obuf_putnetstring | ( | obuf * | out,
|  | const char * | data,
|  | unsigned | datalen )

Write the binary block to the `obuf` as a "netstring".

References obuf_putc(), obuf_putu(), and obuf_write().

## obuf_putns()

int obuf_putns | ( | obuf * | out,
|  | unsigned int | count,
|  |  | ... )

Write N C strings to the `obuf`

References obuf_puts.

## obuf_putsflush()

int obuf_putsflush | ( | obuf * | out,
|  | const char * | str )

Write a C string to the `obuf` and flush it.

References obuf_flush(), and obuf_puts.

## obuf_putsllnumw()

int obuf_putsllnumw | ( | obuf * | out,
|  | long long | data,
|  | unsigned | width,
|  | char | pad,
|  | unsigned | base,
|  | const char * | digits )

Write a signed long long integer to the `obuf` with optional padding.

References fmt_sllnumw(), and obuf_write().

Referenced by obuf_putill(), and obuf_putiwll().

## obuf_putsnumw()

int obuf_putsnumw | ( | obuf * | out,
|  | long | data,
|  | unsigned | width,
|  | char | pad,
|  | unsigned | base,
|  | const char * | digits )

Write a signed integer to the `obuf` with optional padding.

References fmt_snumw(), and obuf_write().

Referenced by obuf_puti(), and obuf_putiw().

## obuf_putu()

int obuf_putu | ( | obuf * | out,
|  | unsigned long | data )

Write an unsigned integer as decimal to the `obuf`.

References fmt_lcase_digits, and obuf_putunumw().

Referenced by obuf_putnetstring().

## obuf_putull()

int obuf_putull | ( | obuf * | out,
|  | unsigned long long | data )

Write an unsigned long long integer as decimal to the `obuf`.

References fmt_lcase_digits, and obuf_putullnumw().

## obuf_putullnumw()

int obuf_putullnumw | ( | obuf * | out,
|  | unsigned long long | data,
|  | unsigned | width,
|  | char | pad,
|  | unsigned | base,
|  | const char * | digits )

Write an unsigned long long integer to the `obuf` with optional padding.

References fmt_ullnumw(), and obuf_write().

Referenced by obuf_putull(), obuf_putuwll(), obuf_putXll(), obuf_putxll(), obuf_putXwll(), and obuf_putxwll().

## obuf_putunumw()

int obuf_putunumw | ( | obuf * | out,
|  | unsigned long | data,
|  | unsigned | width,
|  | char | pad,
|  | unsigned | base,
|  | const char * | digits )

Write an unsigned integer to the `obuf` with optional padding.

References fmt_unumw(), and obuf_write().

Referenced by obuf_putu(), obuf_putuw(), obuf_putX(), obuf_putx(), obuf_putXw(), and obuf_putxw().

## obuf_putuw()

int obuf_putuw | ( | obuf * | out,
|  | unsigned long | data,
|  | unsigned | width,
|  | char | pad )

Write an unsigned integer as decimal to the `obuf` with padding.

References fmt_lcase_digits, and obuf_putunumw().

## obuf_putuwll()

int obuf_putuwll | ( | obuf * | out,
|  | unsigned long long | data,
|  | unsigned | width,
|  | char | pad )

Write an unsigned long long integer as decimal to the `obuf` with padding.

References fmt_lcase_digits, and obuf_putullnumw().

## obuf_putX()

int obuf_putX | ( | obuf * | out,
|  | unsigned long | data )

Write an unsigned integer as (upper-case) hexadecimal to the `obuf`.

References fmt_ucase_digits, and obuf_putunumw().

## obuf_putx()

int obuf_putx | ( | obuf * | out,
|  | unsigned long | data )

Write an unsigned integer as (lower-case) hexadecimal to the `obuf`.

References fmt_lcase_digits, and obuf_putunumw().

## obuf_putXll()

int obuf_putXll | ( | obuf * | out,
|  | unsigned long long | data )

Write an unsigned long long integer as (upper-case) hexadecimal to the `obuf`.

References fmt_ucase_digits, and obuf_putullnumw().

## obuf_putxll()

int obuf_putxll | ( | obuf * | out,
|  | unsigned long long | data )

Write an unsigned long long integer as (lower-case) hexadecimal to the `obuf`.

References fmt_lcase_digits, and obuf_putullnumw().

## obuf_putXw()

int obuf_putXw | ( | obuf * | out,
|  | unsigned long | data,
|  | unsigned | width,
|  | char | pad )

Write an unsigned integer as (upper-case) hexadecimal to the `obuf` with padding.

References fmt_ucase_digits, and obuf_putunumw().

## obuf_putxw()

int obuf_putxw | ( | obuf * | out,
|  | unsigned long | data,
|  | unsigned | width,
|  | char | pad )

Write an unsigned integer as (lower-case) hexadecimal to the `obuf` with padding.

References fmt_lcase_digits, and obuf_putunumw().

## obuf_putXwll()

int obuf_putXwll | ( | obuf * | out,
|  | unsigned long long | data,
|  | unsigned | width,
|  | char | pad )

Write an unsigned long long integer as (upper-case) hexadecimal to the `obuf` with padding.

References fmt_ucase_digits, and obuf_putullnumw().

## obuf_putxwll()

int obuf_putxwll | ( | obuf * | out,
|  | unsigned long long | data,
|  | unsigned | width,
|  | char | pad )

Write an unsigned long long integer as (lower-case) hexadecimal to the `obuf` with padding.

References fmt_lcase_digits, and obuf_putullnumw().

## obuf_seek()

int obuf_seek | ( | obuf * | out,
|  | unsigned | offset )

Set the effective write position.

References iobuf::buflen, obuf::bufpos, obuf::count, iobuf::errnum, iobuf::fd, iobuf::flags, obuf::io, iobuf_bad, IOBUF_ERROR, obuf_flush(), and iobuf::offset.

## obuf_sign_pad()

int obuf_sign_pad | ( | obuf * | out,
|  | int | sign,
|  | unsigned | width,
|  | char | pad )

Pad the output with `width` instances of the single character `ch`, preceded by an optional negative sign at an appropriate place.

If the pad character is `'0'` then any negative sign is placed as the first character, followed by padding. Otherwise, it is preceded by the padding.

References obuf_pad(), and obuf_putc().

## obuf_sync()

int obuf_sync | ( | obuf * | out | ) |

Flush the `obuf` and then `fsync` the file descriptor.

References iobuf::fd, obuf::io, IOBUF_SET_ERROR, and obuf_flush().

## obuf_write()

int obuf_write | ( | obuf * | out,
|  | const char * | data,
|  | unsigned | datalen )

Write a block of data to the `obuf`

References iobuf::buffer, iobuf::buflen, obuf::bufpos, iobuf::bufsize, obuf::count, obuf::io, iobuf_bad, obuf_flush(), and obuf_write_large().

Referenced by obuf_putfv(), obuf_putnetstring(), obuf_putsllnumw(), obuf_putsnumw(), obuf_putullnumw(), and obuf_putunumw().

## obuf_write_large()

int obuf_write_large | ( | obuf * | out,
|  | const char * | data,
|  | unsigned | datalen )

Write a large block of data to the `obuf`, avoiding copying.

References obuf::count, iobuf::fd, obuf::io, iobuf_bad, IOBUF_SET_ERROR, iobuf_timeout(), obuf_flush(), iobuf::offset, iobuf::timeout, and obuf::writefn.

Referenced by iobuf_copy(), and obuf_write().

## Variable Documentation

## errbuf

obuf errbuf

extern

Output buffer for `stderr`

## outbuf

obuf outbuf

extern

Output buffer for `stdout`