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