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) iobuf_error(&(out)->io)
#define | obuf_closed(out) iobuf_closed(&(out)->io)
#define | obuf_timedout(out) iobuf_timedout(&((out)->io))
#define | obuf_rewind(out) obuf_seek(out,0)
#define | obuf_tell(out) ((out)->io.offset+(out)->bufpos)
#define | obuf_puts(out, str) obuf_write(out,str,strlen(str))
#define | obuf_putstr(out, str) obuf_write(out,(str)->s,(str)->len)

## 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 | ) | iobuf_closed(&(out)->io)

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 | ) | iobuf_error(&(out)->io)

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
| ) |  | obuf_write(out,str,strlen(str))

Write a C string to the `obuf`

Referenced by dns_ip4_r(), dns_ip6_r(), dns_name4_r(), dns_name6_r(), dns_resolvconfip(), dns_txt_r(), envstr_find(), envstr_get(), envstr_make_array(), fmt_sign_pad(), fmt_sllnumw(), fmt_snumw(), fmt_ullnumw(), fmt_unumw(), iobuf_init(), ipv4_parse(), ipv6_scan(), obuf_put2s(), obuf_put3s(), obuf_put4s(), obuf_put5s(), obuf_put6s(), obuf_put7s(), obuf_putns(), obuf_putsflush(), obuf_write(), path_match(), str_case_matchs(), and str_matchs().

## obuf_putstr

#define obuf_putstr | ( |  | out,
|  |  | str
| ) |  | obuf_write(out,(str)->s,(str)->len)

Write a dynamic string to the `iobuf`

Referenced by path_merge().

## obuf_rewind

#define obuf_rewind | ( |  | out | ) | obuf_seek(out,0)

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

## obuf_tell

#define obuf_tell | ( |  | out | ) | ((out)->io.offset+(out)->bufpos)

Look up the current effective write position.

## obuf_timedout

#define obuf_timedout | ( |  | out | ) | iobuf_timedout(&((out)->io))

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 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().

Referenced by dns_domain_fromdot(), envstr_find(), envstr_get(), envstr_make_array(), fmt_char(), selfpipe_close(), signalfd_close(), str_case_end(), str_case_start(), str_endb(), str_startb(), and surf().

## obuf_flush()

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

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

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

Referenced by dns_name4_r(), dns_name6_r(), iobuf_copyflush(), ipv4_parse(), ipv6_scan(), 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 bufpos, count, io, iobuf_init(), and writefn.

Referenced by obuf_open(), and obuf_write().

## 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, and outbuf.

Referenced by fmt_ipv6addr(), ipv4_parse(), ipv6_scan(), selfpipe_close(), and signalfd_close().

## 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, and outbuf.

## 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, and outbuf.

## 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, and outbuf.

## 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, and outbuf.

## 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, and outbuf.

## obuf_putc()

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

Write a single character to the `obuf`

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

Referenced by dns_domain_fromdot(), dns_ip4_r(), dns_ip6_r(), dns_name4_r(), dns_name6_r(), envstr_make_array(), fmt_ipv6addr(), fmt_sign_pad(), fmt_sllnumw(), fmt_snumw(), fmt_ullnumw(), fmt_unumw(), ipv4_parse(), ipv6_scan(), obuf_endl(), obuf_pad(), obuf_putnetstring(), obuf_sign_pad(), path_match(), str_case_matchs(), str_matchs(), and surfrand_uniform().

## obuf_putf()

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

Write a formatted string using `fmt_multi` from variable arguments

Examples:
  adt/ghash_test.c.

References obuf_putfv(), and outbuf.

Referenced by dns_domain_fromdot(), dns_name4_r(), dns_name6_r(), dns_qualify(), ibuf_getc(), ibuf_getnetstring(), ibuf_gets(), ibuf_getstr_crlf(), resolve_ipv4addr(), and resolve_ipv4name_n().

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

Examples:
  adt/gqueue_test.c, and adt/gstack_test.c.

References fmt_lcase_digits, obuf_putiw(), obuf_putsnumw(), and outbuf.

Referenced by envstr_make_array(), iobuf_init(), ipv4_parse(), path_match(), selfpipe_close(), signalfd_close(), str_findnext(), str_findnextof(), str_findprev(), str_findprevnot(), and str_findprevof().

## 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, obuf_putiwll(), obuf_putsllnumw(), and outbuf.

## 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().

Referenced by obuf_puti().

## 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().

Referenced by obuf_putill().

## 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, and outbuf.

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

Referenced by fmt_ipv4addr_reverse().

## 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 fmt_char(), fmt_sign_pad(), fmt_sllnumw(), fmt_snumw(), fmt_ullnumw(), fmt_unumw(), iobuf_init(), obuf_putnetstring(), path_match(), str_case_end(), str_case_start(), str_endb(), str_startb(), and str_xlate().

## 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().

Referenced by obuf_putX().

## 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().

Referenced by obuf_putXll().

## 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().

Referenced by iobuf_init().

## 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, obuf_putunumw(), obuf_putuw(), obuf_putxw(), obuf_putXw(), and outbuf.

## 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_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, obuf_putullnumw(), obuf_putuwll(), obuf_putxwll(), obuf_putXwll(), and outbuf.

## 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().

Referenced by fmt_ipv6addr(), ipv6_scan(), obuf_putX(), surf(), and surfrand_uniform().

## 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().

Referenced by obuf_putX().

## 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().

Referenced by obuf_putXll().

## 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().

Referenced by obuf_putXll().

## obuf_seek()

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

Set the effective write position.

References iobuf::buflen, bufpos, count, iobuf::errnum, iobuf::fd, iobuf::flags, 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(), obuf_putc(), and outbuf.

## obuf_sync()

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

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

References iobuf::fd, 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, bufpos, iobuf::bufsize, count, io, iobuf_bad, obuf_flush(), obuf_init(), obuf_puts, and obuf_write_large().

Referenced by fmt_char(), 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 count, iobuf::fd, io, iobuf_bad, IOBUF_SET_ERROR, iobuf_timeout(), obuf_flush(), iobuf::offset, iobuf::timeout, and writefn.

Referenced by iobuf_copy(), and obuf_write().

## Variable Documentation

## errbuf

obuf errbuf

Output buffer for `stderr`

## outbuf

obuf outbuf

Output buffer for `stdout`

Examples:
  adt/ghash_test.c, adt/gqueue_test.c, and adt/gstack_test.c.

Referenced by dns_domain_fromdot(), dns_ip4_r(), dns_ip6_r(), dns_name4_r(), dns_name6_r(), dns_qualify(), dns_resolvconfip(), dns_txt_r(), envstr_find(), envstr_get(), envstr_make_array(), fmt_char(), fmt_ipv4addr_reverse(), fmt_ipv6addr(), fmt_sign_pad(), fmt_sllnumw(), fmt_snumw(), fmt_ullnumw(), fmt_unumw(), ibuf_getc(), ibuf_getnetstring(), ibuf_gets(), ibuf_getstr_crlf(), iobuf_init(), ipv4_parse(), ipv6_scan(), obuf_put2s(), obuf_put3s(), obuf_put4s(), obuf_put5s(), obuf_put6s(), obuf_put7s(), obuf_putf(), obuf_puti(), obuf_putill(), obuf_putns(), obuf_putX(), obuf_putXll(), obuf_sign_pad(), path_match(), path_merge(), resolve_ipv4addr(), resolve_ipv4name_n(), selfpipe_close(), signalfd_close(), str_case_end(), str_case_matchs(), str_case_start(), str_endb(), str_findnext(), str_findnextof(), str_findprev(), str_findprevnot(), str_findprevof(), str_matchs(), str_startb(), str_xlate(), surf(), and surfrand_uniform().