diff options
Diffstat (limited to 'static/freebsd/man9/sbuf.9 4.html')
| -rw-r--r-- | static/freebsd/man9/sbuf.9 4.html | 525 |
1 files changed, 0 insertions, 525 deletions
diff --git a/static/freebsd/man9/sbuf.9 4.html b/static/freebsd/man9/sbuf.9 4.html deleted file mode 100644 index 320c464f..00000000 --- a/static/freebsd/man9/sbuf.9 4.html +++ /dev/null @@ -1,525 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">SBUF(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">SBUF(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">sbuf</code>, <code class="Nm">sbuf_new</code>, - <code class="Nm">sbuf_new_auto</code>, - <code class="Nm">sbuf_new_for_sysctl</code>, - <code class="Nm">sbuf_clear</code>, <code class="Nm">sbuf_get_flags</code>, - <code class="Nm">sbuf_set_flags</code>, - <code class="Nm">sbuf_clear_flags</code>, - <code class="Nm">sbuf_setpos</code>, <code class="Nm">sbuf_bcat</code>, - <code class="Nm">sbuf_bcopyin</code>, <code class="Nm">sbuf_bcpy</code>, - <code class="Nm">sbuf_cat</code>, <code class="Nm">sbuf_copyin</code>, - <code class="Nm">sbuf_cpy</code>, <code class="Nm">sbuf_nl_terminate</code>, - <code class="Nm">sbuf_printf</code>, <code class="Nm">sbuf_vprintf</code>, - <code class="Nm">sbuf_putc</code>, <code class="Nm">sbuf_set_drain</code>, - <code class="Nm">sbuf_trim</code>, <code class="Nm">sbuf_error</code>, - <code class="Nm">sbuf_finish</code>, <code class="Nm">sbuf_data</code>, - <code class="Nm">sbuf_len</code>, <code class="Nm">sbuf_done</code>, - <code class="Nm">sbuf_delete</code>, - <code class="Nm">sbuf_start_section</code>, - <code class="Nm">sbuf_end_section</code>, - <code class="Nm">sbuf_hexdump</code>, - <code class="Nm">sbuf_printf_drain</code>, - <code class="Nm">sbuf_putbuf</code> — <span class="Nd">safe string - composition</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="LIBRARY"><a class="permalink" href="#LIBRARY">LIBRARY</a></h1> -<p class="Pp"><span class="Lb">Safe String Composition Library (libsbuf, - -lsbuf)</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/types.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/sbuf.h</a>></code></p> -<p class="Pp"><var class="Ft">typedef int</var> - <br/> - <code class="Fn">(sbuf_drain_func)</code>(<var class="Fa">void *arg</var>, - <var class="Fa">const char *data</var>, <var class="Fa">int len</var>);</p> -<p class="Pp"> - <br/> - <var class="Ft">struct sbuf *</var> - <br/> - <code class="Fn">sbuf_new</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">char *buf</var>, <var class="Fa">int length</var>, - <var class="Fa">int flags</var>);</p> -<p class="Pp"><var class="Ft">struct sbuf *</var> - <br/> - <code class="Fn">sbuf_new_auto</code>(<var class="Fa">void</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sbuf_clear</code>(<var class="Fa">struct sbuf *s</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_get_flags</code>(<var class="Fa">struct sbuf - *s</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sbuf_set_flags</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">int flags</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sbuf_clear_flags</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">int flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_setpos</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">int pos</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_bcat</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">const void *buf</var>, <var class="Fa">size_t - len</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_bcpy</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">const void *buf</var>, <var class="Fa">size_t - len</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_cat</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">const char *str</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_cpy</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">const char *str</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_nl_terminate</code>(<var class="Fa" style="white-space: nowrap;">struct - sbuf *</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_printf</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">const char *fmt</var>, <var class="Fa">...</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_vprintf</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">const char *fmt</var>, <var class="Fa">va_list - ap</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_putc</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">int c</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sbuf_set_drain</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">sbuf_drain_func *func</var>, <var class="Fa">void - *arg</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_trim</code>(<var class="Fa">struct sbuf *s</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_error</code>(<var class="Fa">struct sbuf *s</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_finish</code>(<var class="Fa">struct sbuf *s</var>);</p> -<p class="Pp"><var class="Ft">char *</var> - <br/> - <code class="Fn">sbuf_data</code>(<var class="Fa">struct sbuf *s</var>);</p> -<p class="Pp"><var class="Ft">ssize_t</var> - <br/> - <code class="Fn">sbuf_len</code>(<var class="Fa">struct sbuf *s</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_done</code>(<var class="Fa">struct sbuf *s</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sbuf_delete</code>(<var class="Fa">struct sbuf *s</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sbuf_start_section</code>(<var class="Fa">struct sbuf - *s</var>, <var class="Fa">ssize_t *old_lenp</var>);</p> -<p class="Pp"><var class="Ft">ssize_t</var> - <br/> - <code class="Fn">sbuf_end_section</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">ssize_t old_len</var>, <var class="Fa">size_t pad</var>, - <var class="Fa">int c</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sbuf_hexdump</code>(<var class="Fa">struct sbuf *sb</var>, - <var class="Fa">void *ptr</var>, <var class="Fa">int length</var>, - <var class="Fa">const char *hdr</var>, <var class="Fa">int flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_printf_drain</code>(<var class="Fa">void *arg</var>, - <var class="Fa">const char *data</var>, <var class="Fa">int len</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">sbuf_putbuf</code>(<var class="Fa">struct sbuf *s</var>);</p> -<p class="Pp"><code class="Fd">#ifdef _KERNEL</code></p> -<p class="Pp"><code class="In">#include - <<a class="In">sys/types.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/sbuf.h</a>></code></p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_bcopyin</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">const void *uaddr</var>, <var class="Fa">size_t - len</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sbuf_copyin</code>(<var class="Fa">struct sbuf *s</var>, - <var class="Fa">const void *uaddr</var>, <var class="Fa">size_t - len</var>);</p> -<p class="Pp"><code class="In">#include - <<a class="In">sys/sysctl.h</a>></code></p> -<p class="Pp"><var class="Ft">struct sbuf *</var> - <br/> - <code class="Fn">sbuf_new_for_sysctl</code>(<var class="Fa">struct sbuf - *s</var>, <var class="Fa">char *buf</var>, <var class="Fa">int length</var>, - <var class="Fa">struct sysctl_req *req</var>);</p> -<p class="Pp"><code class="Fd">#endif /* _KERNEL */</code></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">sbuf</code> family of functions allows one to - safely allocate, compose and release strings in kernel or user space.</p> -<p class="Pp">Instead of arrays of characters, these functions operate on - structures called <var class="Fa">sbufs</var>, defined in - <code class="In"><<a class="In">sys/sbuf.h</a>></code>.</p> -<p class="Pp">Any errors encountered during the allocation or composition of the - string will be latched in the data structure, making a single error test at - the end of the composition sufficient to determine success or failure of the - entire process.</p> -<p class="Pp" id="sbuf_new">The - <a class="permalink" href="#sbuf_new"><code class="Fn">sbuf_new</code></a>() - function initializes the <var class="Fa">sbuf</var> pointed to by its first - argument. If that pointer is <code class="Dv">NULL</code>, - <code class="Fn">sbuf_new</code>() allocates a <var class="Vt">struct - sbuf</var> using <a class="Xr">malloc(9)</a>. The <var class="Fa">buf</var> - argument is a pointer to a buffer in which to store the actual string; if it - is <code class="Dv">NULL</code>, <code class="Fn">sbuf_new</code>() will - allocate one using <a class="Xr">malloc(9)</a>. The - <var class="Fa">length</var> is the initial size of the storage buffer. The - fourth argument, <var class="Fa">flags</var>, may be comprised of the - following flags:</p> -<dl class="Bl-tag"> - <dt id="SBUF_FIXEDLEN"><a class="permalink" href="#SBUF_FIXEDLEN"><code class="Dv">SBUF_FIXEDLEN</code></a></dt> - <dd>The storage buffer is fixed at its initial size. Attempting to extend the - sbuf beyond this size results in an overflow condition.</dd> - <dt id="SBUF_AUTOEXTEND"><a class="permalink" href="#SBUF_AUTOEXTEND"><code class="Dv">SBUF_AUTOEXTEND</code></a></dt> - <dd>This indicates that the storage buffer may be extended as necessary, so - long as resources allow, to hold additional data.</dd> - <dt id="SBUF_INCLUDENUL"><a class="permalink" href="#SBUF_INCLUDENUL"><code class="Dv">SBUF_INCLUDENUL</code></a></dt> - <dd>This causes the final nulterm byte to be counted in the length of the - data.</dd> - <dt id="SBUF_DRAINTOEOR"><a class="permalink" href="#SBUF_DRAINTOEOR"><code class="Dv">SBUF_DRAINTOEOR</code></a></dt> - <dd>Treat top-level sections started with - <code class="Fn">sbuf_start_section</code>() as a record boundary marker - that will be used during drain operations to avoid records being split. If - a record grows sufficiently large such that it fills the - <var class="Fa">sbuf</var> and therefore cannot be drained without being - split, an error of <code class="Er">EDEADLK</code> is set.</dd> - <dt id="SBUF_NOWAIT"><a class="permalink" href="#SBUF_NOWAIT"><code class="Dv">SBUF_NOWAIT</code></a></dt> - <dd>Indicates that attempts to extend the storage buffer should fail in low - memory conditions, like <a class="Xr">malloc(9)</a> - <code class="Dv">M_NOWAIT</code>.</dd> -</dl> -<p class="Pp">Note that if <var class="Fa">buf</var> is not - <code class="Dv">NULL</code>, it must point to an array of at least - <var class="Fa">length</var> characters. The result of accessing that array - directly while it is in use by the sbuf is undefined.</p> -<p class="Pp" id="sbuf_new_auto">The - <a class="permalink" href="#sbuf_new_auto"><code class="Fn">sbuf_new_auto</code></a>() - function is a shortcut for creating a completely dynamic - <code class="Nm">sbuf</code>. It is the equivalent of calling - <code class="Fn">sbuf_new</code>() with values <code class="Dv">NULL</code>, - <code class="Dv">NULL</code>, <code class="Dv">0</code>, and - <code class="Dv">SBUF_AUTOEXTEND</code>.</p> -<p class="Pp" id="sbuf_new_for_sysctl">The - <a class="permalink" href="#sbuf_new_for_sysctl"><code class="Fn">sbuf_new_for_sysctl</code></a>() - function will set up an sbuf with a drain function to use - <a class="permalink" href="#SYSCTL_OUT"><code class="Fn" id="SYSCTL_OUT">SYSCTL_OUT</code></a>() - when the internal buffer fills. Note that if the various functions which - append to an sbuf are used while a non-sleepable lock is held, the user - buffer should be wired using - <a class="permalink" href="#sysctl_wire_old_buffer"><code class="Fn" id="sysctl_wire_old_buffer">sysctl_wire_old_buffer</code></a>().</p> -<p class="Pp" id="sbuf_delete">The - <a class="permalink" href="#sbuf_delete"><code class="Fn">sbuf_delete</code></a>() - function clears the <var class="Fa">sbuf</var> and frees any memory - allocated for it. There must be a call to - <code class="Fn">sbuf_delete</code>() for every call to - <code class="Fn">sbuf_new</code>(). Any attempt to access the sbuf after it - has been deleted will fail.</p> -<p class="Pp" id="sbuf_clear">The - <a class="permalink" href="#sbuf_clear"><code class="Fn">sbuf_clear</code></a>() - function invalidates the contents of the <var class="Fa">sbuf</var> and - resets its position to zero.</p> -<p class="Pp" id="sbuf_get_flags">The - <a class="permalink" href="#sbuf_get_flags"><code class="Fn">sbuf_get_flags</code></a>() - function returns the current user flags. The - <a class="permalink" href="#sbuf_set_flags"><code class="Fn" id="sbuf_set_flags">sbuf_set_flags</code></a>() - and - <a class="permalink" href="#sbuf_clear_flags"><code class="Fn" id="sbuf_clear_flags">sbuf_clear_flags</code></a>() - functions set or clear one or more user flags, respectively. The user flags - are described under the <code class="Fn">sbuf_new</code>() function.</p> -<p class="Pp" id="sbuf_setpos">The - <a class="permalink" href="#sbuf_setpos"><code class="Fn">sbuf_setpos</code></a>() - function sets the <var class="Fa">sbuf</var>'s end position to - <var class="Fa">pos</var>, which is a value between zero and the current - position in the buffer. It can only truncate the sbuf to the new - position.</p> -<p class="Pp" id="sbuf_bcat">The - <a class="permalink" href="#sbuf_bcat"><code class="Fn">sbuf_bcat</code></a>() - function appends the first <var class="Fa">len</var> bytes from the buffer - <var class="Fa">buf</var> to the <var class="Fa">sbuf</var>.</p> -<p class="Pp" id="sbuf_bcopyin">The - <a class="permalink" href="#sbuf_bcopyin"><code class="Fn">sbuf_bcopyin</code></a>() - function copies <var class="Fa">len</var> bytes from the specified userland - address into the <var class="Fa">sbuf</var>.</p> -<p class="Pp" id="sbuf_bcpy">The - <a class="permalink" href="#sbuf_bcpy"><code class="Fn">sbuf_bcpy</code></a>() - function replaces the contents of the <var class="Fa">sbuf</var> with the - first <var class="Fa">len</var> bytes from the buffer - <var class="Fa">buf</var>.</p> -<p class="Pp" id="sbuf_cat">The - <a class="permalink" href="#sbuf_cat"><code class="Fn">sbuf_cat</code></a>() - function appends the NUL-terminated string <var class="Fa">str</var> to the - <var class="Fa">sbuf</var> at the current position.</p> -<p class="Pp" id="sbuf_set_drain">The - <a class="permalink" href="#sbuf_set_drain"><code class="Fn">sbuf_set_drain</code></a>() - function sets a drain function <var class="Fa">func</var> for the - <var class="Fa">sbuf</var>, and records a pointer <var class="Fa">arg</var> - to be passed to the drain on callback. The drain function cannot be changed - while <var class="Fa">sbuf_len</var> is non-zero.</p> -<p class="Pp" id="sbuf_set_drain~2">The registered drain function - <var class="Vt">sbuf_drain_func</var> will be called with the argument - <var class="Fa">arg</var> provided to - <a class="permalink" href="#sbuf_set_drain~2"><code class="Fn">sbuf_set_drain</code></a>(), - a pointer <var class="Fa">data</var> to a byte string that is the contents - of the sbuf, and the length <var class="Fa">len</var> of the data. If the - drain function exists, it will be called when the sbuf internal buffer is - full, or on behalf of <code class="Fn">sbuf_finish</code>(). The drain - function may drain some or all of the data, but must drain at least 1 byte. - The return value from the drain function, if positive, indicates how many - bytes were drained. If negative, the return value indicates the negative - error code which will be returned from this or a later call to - <code class="Fn">sbuf_finish</code>(). If the returned drained length is 0, - an error of <code class="Er">EDEADLK</code> is set. To do unbuffered - draining, initialize the sbuf with a two-byte buffer. The drain will be - called for every byte added to the sbuf. The - <code class="Fn">sbuf_bcopyin</code>(), <code class="Fn">sbuf_bcpy</code>(), - <code class="Fn">sbuf_clear</code>(), <code class="Fn">sbuf_copyin</code>(), - <code class="Fn">sbuf_cpy</code>(), <code class="Fn">sbuf_trim</code>(), - <code class="Fn">sbuf_data</code>(), and <code class="Fn">sbuf_len</code>() - functions cannot be used on an sbuf with a drain.</p> -<p class="Pp" id="sbuf_copyin">The - <a class="permalink" href="#sbuf_copyin"><code class="Fn">sbuf_copyin</code></a>() - function copies a NUL-terminated string from the specified userland address - into the <var class="Fa">sbuf</var>. If the <var class="Fa">len</var> - argument is non-zero, no more than <var class="Fa">len</var> characters (not - counting the terminating NUL) are copied; otherwise the entire string, or as - much of it as can fit in the <var class="Fa">sbuf</var>, is copied.</p> -<p class="Pp" id="sbuf_cpy">The - <a class="permalink" href="#sbuf_cpy"><code class="Fn">sbuf_cpy</code></a>() - function replaces the contents of the <var class="Fa">sbuf</var> with those - of the NUL-terminated string <var class="Fa">str</var>. This is equivalent - to calling <code class="Fn">sbuf_cat</code>() with a fresh - <var class="Fa">sbuf</var> or one which position has been reset to zero with - <code class="Fn">sbuf_clear</code>() or - <code class="Fn">sbuf_setpos</code>().</p> -<p class="Pp" id="sbuf_nl_terminate">The - <a class="permalink" href="#sbuf_nl_terminate"><code class="Fn">sbuf_nl_terminate</code></a>() - function appends a trailing newline character, if the current line is - non-empty and not already terminated by a newline character.</p> -<p class="Pp" id="sbuf_printf">The - <a class="permalink" href="#sbuf_printf"><code class="Fn">sbuf_printf</code></a>() - function formats its arguments according to the format string pointed to by - <var class="Fa">fmt</var> and appends the resulting string to the - <var class="Fa">sbuf</var> at the current position.</p> -<p class="Pp" id="sbuf_vprintf">The - <a class="permalink" href="#sbuf_vprintf"><code class="Fn">sbuf_vprintf</code></a>() - function behaves the same as <code class="Fn">sbuf_printf</code>() except - that the arguments are obtained from the variable-length argument list - <var class="Fa">ap</var>.</p> -<p class="Pp" id="sbuf_putc">The - <a class="permalink" href="#sbuf_putc"><code class="Fn">sbuf_putc</code></a>() - function appends the character <var class="Fa">c</var> to the - <var class="Fa">sbuf</var> at the current position.</p> -<p class="Pp" id="sbuf_trim">The - <a class="permalink" href="#sbuf_trim"><code class="Fn">sbuf_trim</code></a>() - function removes trailing whitespace from the - <var class="Fa">sbuf</var>.</p> -<p class="Pp" id="sbuf_error">The - <a class="permalink" href="#sbuf_error"><code class="Fn">sbuf_error</code></a>() - function returns any error value that the <var class="Fa">sbuf</var> may - have accumulated, either from the drain function, or - <code class="Er">ENOMEM</code> if the <var class="Fa">sbuf</var> overflowed. - This function is generally not needed and instead the error code from - <code class="Fn">sbuf_finish</code>() is the preferred way to discover - whether an sbuf had an error.</p> -<p class="Pp" id="sbuf_finish">The - <a class="permalink" href="#sbuf_finish"><code class="Fn">sbuf_finish</code></a>() - function will call the attached drain function if one exists until all the - data in the <var class="Fa">sbuf</var> is flushed. If there is no attached - drain, <code class="Fn">sbuf_finish</code>() NUL-terminates the - <var class="Fa">sbuf</var>. In either case it marks the - <var class="Fa">sbuf</var> as finished, which means that it may no longer be - modified using <code class="Fn">sbuf_setpos</code>(), - <code class="Fn">sbuf_cat</code>(), <code class="Fn">sbuf_cpy</code>(), - <code class="Fn">sbuf_printf</code>() or - <code class="Fn">sbuf_putc</code>(), until - <code class="Fn">sbuf_clear</code>() is used to reset the sbuf.</p> -<p class="Pp" id="sbuf_data">The - <a class="permalink" href="#sbuf_data"><code class="Fn">sbuf_data</code></a>() - function returns the actual string; <code class="Fn">sbuf_data</code>() only - works on a finished <var class="Fa">sbuf</var>. The - <a class="permalink" href="#sbuf_len"><code class="Fn" id="sbuf_len">sbuf_len</code></a>() - function returns the length of the string. For an <var class="Fa">sbuf</var> - with an attached drain, <code class="Fn">sbuf_len</code>() returns the - length of the un-drained data. - <a class="permalink" href="#sbuf_done"><code class="Fn" id="sbuf_done">sbuf_done</code></a>() - returns non-zero if the <var class="Fa">sbuf</var> is finished.</p> -<p class="Pp" id="sbuf_start_section">The - <a class="permalink" href="#sbuf_start_section"><code class="Fn">sbuf_start_section</code></a>() - and - <a class="permalink" href="#sbuf_end_section"><code class="Fn" id="sbuf_end_section">sbuf_end_section</code></a>() - functions may be used for automatic section alignment. The arguments - <var class="Fa">pad</var> and <var class="Fa">c</var> specify the padding - size and a character used for padding. The arguments - <var class="Fa">old_lenp</var> and <var class="Fa">old_len</var> are to save - and restore the current section length when nested sections are used. For - the top level section <code class="Dv">NULL</code> and -1 can be specified - for <var class="Fa">old_lenp</var> and <var class="Fa">old_len</var> - respectively.</p> -<p class="Pp" id="sbuf_hexdump">The - <a class="permalink" href="#sbuf_hexdump"><code class="Fn">sbuf_hexdump</code></a>() - function prints an array of bytes to the supplied sbuf, along with an ASCII - representation of the bytes if possible. See the - <a class="Xr">hexdump(3)</a> man page for more details on the interface.</p> -<p class="Pp" id="sbuf_printf_drain">The - <a class="permalink" href="#sbuf_printf_drain"><code class="Fn">sbuf_printf_drain</code></a>() - function is a drain function that will call printf, or log to the console. - The argument <var class="Fa">arg</var> must be either - <code class="Dv">NULL</code>, or a valid pointer to a - <var class="Vt">size_t</var>. If <var class="Fa">arg</var> is not - <code class="Dv">NULL</code>, the total bytes drained will be added to the - value pointed to by <var class="Fa">arg</var>.</p> -<p class="Pp" id="sbuf_putbuf">The - <a class="permalink" href="#sbuf_putbuf"><code class="Fn">sbuf_putbuf</code></a>() - function printfs the sbuf to stdout if in userland, and to the console and - log if in the kernel. The <var class="Fa">sbuf</var> must be finished before - calling <code class="Fn">sbuf_putbuf</code>(). It does not drain the buffer - or update any pointers.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> -<p class="Pp">If an operation caused an <var class="Fa">sbuf</var> to overflow, - most subsequent operations on it will fail until the - <var class="Fa">sbuf</var> is finished using - <code class="Fn">sbuf_finish</code>() or reset using - <code class="Fn">sbuf_clear</code>(), or its position is reset to a value - between 0 and one less than the size of its storage buffer using - <code class="Fn">sbuf_setpos</code>(), or it is reinitialized to a - sufficiently short string using <code class="Fn">sbuf_cpy</code>().</p> -<p class="Pp">Drains in user-space will not always function as indicated. While - the drain function will be called immediately on overflow from the - <var class="Fa">sbuf_putc</var>, <var class="Fa">sbuf_bcat</var>, - <var class="Fa">sbuf_cat</var> functions, <var class="Fa">sbuf_printf</var> - and <var class="Fa">sbuf_vprintf</var> currently have no way to determine - whether there will be an overflow until after it occurs, and cannot do a - partial expansion of the format string. Thus when using libsbuf the buffer - may be extended to allow completion of a single printf call, even though a - drain is attached.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp">The <code class="Fn">sbuf_new</code>() function returns - <code class="Dv">NULL</code> if it failed to allocate a storage buffer, and - a pointer to the new <var class="Fa">sbuf</var> otherwise.</p> -<p class="Pp">The <code class="Fn">sbuf_setpos</code>() function returns -1 if - <var class="Fa">pos</var> was invalid, and zero otherwise.</p> -<p class="Pp">The <code class="Fn">sbuf_bcat</code>(), - <code class="Fn">sbuf_cat</code>(), <code class="Fn">sbuf_cpy</code>(), - <code class="Fn">sbuf_printf</code>(), <code class="Fn">sbuf_putc</code>(), - and <code class="Fn">sbuf_trim</code>() functions all return -1 if the - buffer overflowed, and zero otherwise.</p> -<p class="Pp">The <code class="Fn">sbuf_error</code>() function returns a - non-zero value if the buffer has an overflow or drain error, and zero - otherwise.</p> -<p class="Pp">The <code class="Fn">sbuf_len</code>() function returns -1 if the - buffer overflowed.</p> -<p class="Pp">The <code class="Fn">sbuf_copyin</code>() function returns -1 if - copying string from userland failed, and number of bytes copied - otherwise.</p> -<p class="Pp">The <code class="Fn">sbuf_end_section</code>() function returns - the section length or -1 if the buffer has an error.</p> -<p class="Pp">The <code class="Fn">sbuf_finish</code>(<var class="Fa">9</var>) - function (the kernel version) returns <code class="Er">ENOMEM</code> if the - sbuf overflowed before being finished, or returns the error code from the - drain if one is attached.</p> -<p class="Pp">The <code class="Fn">sbuf_finish</code>(<var class="Fa">3</var>) - function (the userland version) will return zero for success and -1 and set - errno on error.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<div class="Bd Li"> -<pre>#include <sys/types.h> -#include <sys/sbuf.h> - -struct sbuf *sb; - -sb = sbuf_new_auto(); -sbuf_cat(sb, "Customers found:\n"); -TAILQ_FOREACH(foo, &foolist, list) { - sbuf_printf(sb, " %4d %s\n", foo->index, foo->name); - sbuf_printf(sb, " Address: %s\n", foo->address); - sbuf_printf(sb, " Zip: %s\n", foo->zipcode); -} -if (sbuf_finish(sb) != 0) /* Check for any and all errors */ - err(1, "Could not generate message"); -transmit_msg(sbuf_data(sb), sbuf_len(sb)); -sbuf_delete(sb);</pre> -</div> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">hexdump(3)</a>, <a class="Xr">printf(3)</a>, - <a class="Xr">strcat(3)</a>, <a class="Xr">strcpy(3)</a>, - <a class="Xr">copyin(9)</a>, <a class="Xr">copyinstr(9)</a>, - <a class="Xr">printf(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">sbuf</code> family of functions first - appeared in <span class="Ux">FreeBSD 4.4</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The <code class="Nm">sbuf</code> family of functions was designed - by <span class="An">Poul-Henning Kamp</span> - <<a class="Mt" href="mailto:phk@FreeBSD.org">phk@FreeBSD.org</a>> and - implemented by <span class="An">Dag-Erling Smørgrav</span> - <<a class="Mt" href="mailto:des@FreeBSD.org">des@FreeBSD.org</a>>. - Additional improvements were suggested by <span class="An">Justin T. - Gibbs</span> - <<a class="Mt" href="mailto:gibbs@FreeBSD.org">gibbs@FreeBSD.org</a>>. - Auto-extend support added by <span class="An">Kelly Yancey</span> - <<a class="Mt" href="mailto:kbyanc@FreeBSD.org">kbyanc@FreeBSD.org</a>>. - Drain functionality added by <span class="An">Matthew Fleming</span> - <<a class="Mt" href="mailto:mdf@FreeBSD.org">mdf@FreeBSD.org</a>>.</p> -<p class="Pp">This manual page was written by <span class="An">Dag-Erling - Smørgrav</span> - <<a class="Mt" href="mailto:des@FreeBSD.org">des@FreeBSD.org</a>>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">October 3, 2023</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |