X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/750e4b6cad56c36353b9604788c202d49eb8de56..36b6fecc4670f4d351cd662a6772a5a196108ceb:/man/dstr.3

diff --git a/man/dstr.3 b/man/dstr.3
index 998e3f3..b7c6cfb 100644
--- a/man/dstr.3
+++ b/man/dstr.3
@@ -19,7 +19,8 @@
 ..
 .ie t .ds o \(bu
 .el .ds o o
-.TH dstr 3 "8 May 1999" "mLib"
+.TH dstr 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
 dstr \- a simple dynamic string type
 .\" @dstr_create
 .\" @dstr_destroy
@@ -62,7 +63,7 @@ dstr \- a simple dynamic string type
 .BI "void dstr_putc(dstr *" d ", char " ch );
 .BI "void dstr_putz(dstr *" d );
 .BI "void dstr_puts(dstr *" d ", const char *" s );
-.BI "int dstr_vputf(dstr *" d ", va_list " ap );
+.BI "int dstr_vputf(dstr *" d ", va_list *" ap );
 .BI "int dstr_putf(dstr *" d ", ...);"
 .BI "void dstr_putd(dstr *" d ", const dstr *" p );
 .BI "void dstr_putm(dstr *" d ", const void *" p ", size_t " sz );
@@ -103,6 +104,7 @@ typedef struct dstr {
   char *buf;		/* Pointer to string buffer */
   size_t sz;		/* Size of the buffer */
   size_t len;		/* Length of the string */
+  arena *a;		/* Pointer to arena */
 } dstr;
 .VE
 The
@@ -150,7 +152,7 @@ is zero, then
 is a null pointer.
 .hP \*o
 At all times,
-.BI sz " >= " len\fR.
+.BR sz " \(>= " len.
 .PP
 Note that there is no equivalent of the standard C distinction between
 the empty string (a pointer to an array of characters whose first
@@ -159,20 +161,28 @@ element is zero) and the nonexistent string (a null pointer).  Any
 whose
 .B len
 is zero is an empty string.
+.PP
+The
+.I a
+member refers to the arena from which the string's buffer has been
+allocated.  Immediately after creation, this is set to be
+.BR arena_stdlib (3);
+you can set it to point to any other arena of your choice before the
+buffer is allocated.
 .SS "Creation and destruction"
 The caller is responsible for allocating the
 .B dstr
-structure.  It can be initialized in any of the following ways:
+structure.  It can be initialized:
 .hP \*o
-Using the macro
+using the macro
 .B DSTR_INIT
-as an initializer in the declaration of the object.
+as an initializer in the declaration of the object,
 .hP \*o
-Passing its address to the
+passing its address to the
 .B dstr_create
-function.
+function, or
 .hP \*o
-Passing its address to the (equivalent)
+passing its address to the (equivalent)
 .B DCREATE
 macro.
 .PP
@@ -330,12 +340,15 @@ The function
 .B dstr_vputf
 provides access to the `guts' of
 .BR dstr_putf :
-given a format string and a
-.B va_list
-pointer, it will format the arguments according to the format string,
-just as
+given a format string and a pointer to a
+.BR va_list
+it will format the arguments according to the format string, just as
 .B dstr_putf
-does.
+does.  (Note: that's a
+.BR "va_list *" ,
+not a plain
+.BR va_list ,
+so that it gets updated properly on exit.)
 .PP
 The function
 .B dstr_putd
@@ -398,4 +411,4 @@ independent people who know what they're doing.
 .BR exc (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>