From owner-svn-src-all@FreeBSD.ORG Tue May 17 18:25:00 2011 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 44A881065673; Tue, 17 May 2011 18:25:00 +0000 (UTC) (envelope-from phk@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 1A9EF8FC17; Tue, 17 May 2011 18:25:00 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id p4HIOxD6042154; Tue, 17 May 2011 18:24:59 GMT (envelope-from phk@svn.freebsd.org) Received: (from phk@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id p4HIOxHY042152; Tue, 17 May 2011 18:24:59 GMT (envelope-from phk@svn.freebsd.org) Message-Id: <201105171824.p4HIOxHY042152@svn.freebsd.org> From: Poul-Henning Kamp Date: Tue, 17 May 2011 18:24:59 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r222034 - head/share/man/man9 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 17 May 2011 18:25:00 -0000 Author: phk Date: Tue May 17 18:24:59 2011 New Revision: 222034 URL: http://svn.freebsd.org/changeset/base/222034 Log: Try to explain what sbufs do and add an example to show it. Clarify return values. Modified: head/share/man/man9/sbuf.9 Modified: head/share/man/man9/sbuf.9 ============================================================================== --- head/share/man/man9/sbuf.9 Tue May 17 17:37:58 2011 (r222033) +++ head/share/man/man9/sbuf.9 Tue May 17 18:24:59 2011 (r222034) @@ -52,7 +52,7 @@ .Nm sbuf_len , .Nm sbuf_done , .Nm sbuf_delete -.Nd safe string formatting +.Nd safe string composition .Sh SYNOPSIS .In sys/types.h .In sys/sbuf.h @@ -106,14 +106,20 @@ .Sh DESCRIPTION The .Nm -family of functions allows one to safely allocate, construct and -release bounded NUL-terminated strings in kernel space. +family of functions allows one to safely allocate, compose and +release strings in kernel or user space. +.Pp Instead of arrays of characters, these functions operate on structures called .Fa sbufs , defined in .In sys/sbuf.h . .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. +.Pp The .Fn sbuf_new function initializes the @@ -468,14 +474,35 @@ The function returns \-1 if copying string from userland failed, and number of bytes copied otherwise. +.Pp The -.Fn sbuf_finish -function returns ENOMEM if the sbuf overflowed before being finished, +.Fn sbuf_finish 9 +function (the kernel version) returns ENOMEM if the sbuf overflowed before +being finished, or returns the error code from the drain if one is attached. -When used as -.Xr sbuf_finish 3 , -.Fn sbuf_finish -will return \-1 and set errno on error instead. +.Pp +The +.Fn sbuf_finish 3 +function (the userland version) +will return zero for success and \-1 and set errno on error. +.Sh EXAMPLES +.Bd -literal -compact +#include + +struct sbuf *sb; + +sb = sbuf_new_auto(); +sbuf_cat("Customers found:\en"); +TAILQ_FOREACH(foo, &foolist, list) { + sbuf_printf(" %4d %s\en", foo->index, foo->name); + sbuf_printf(" Address: %s\en", foo->address); + sbuf_printf(" Zip: %s\en", foo->zipcode); +} +if (sbuf_finish(sb)) + err(1,"Could not generate message"); +transmit_msg(sbuf_data(sb), sbuf_len(sb)); +sbuf_delete(sb); +.Ed .Sh SEE ALSO .Xr printf 3 , .Xr strcat 3 ,