X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/08da152ecf0c34dbb9fbfa9e863f1057c092e860..471f9daa24ee9251730e234fe92ad65c1fa9dff3:/man/dstr.3

diff --git a/man/dstr.3 b/man/dstr.3
index 6fde3a1..70d7292 100644
--- a/man/dstr.3
+++ b/man/dstr.3
@@ -1,7 +1,7 @@
 .\" -*-nroff-*-
 .de VS
 .sp 1
-.RS 5
+.RS
 .nf
 .ft B
 ..
@@ -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
@@ -36,6 +37,7 @@ dstr \- a simple dynamic string type
 .\" @dstr_putline
 .\" @dstr_write
 .\"
+.\" @DSTR_INIT
 .\" @DCREATE
 .\" @DDESTROY
 .\" @DRESET
@@ -61,13 +63,14 @@ 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_putf(dstr *" d ", ...);
+.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 );
 .BI "int dstr_putline(dstr *" d ", FILE *" fp );
 .BI "size_t dstr_write(const dstr *" d ", FILE *" fp );
 
+.BI "dstr " d " = DSTR_INIT;"
 .BI "void DCREATE(dstr *" d );
 .BI "void DDESTROY(dstr *" d );
 .BI "void DRESET(dstr *" d );
@@ -79,7 +82,7 @@ dstr \- a simple dynamic string type
 .BI "void DPUTM(dstr *" d ", const void *" p ", size_t " sz );
 .BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
 .fi
-.SH SUMMARY
+.SH DESCRIPTION
 The header
 .B dstr.h
 declares a type for representing dynamically extending strings, and a
@@ -92,7 +95,7 @@ is raised.
 Many of the functions which act on dynamic strings have macro
 equivalents.  These equivalent macros may evaluate their arguments
 multiple times.
-.SH "UNDERLYING TYPE"
+.SS "Underlying type"
 A
 .B dstr
 object is a small structure with the following members:
@@ -101,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
@@ -148,29 +152,37 @@ 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 equaivalent of the standard C distinction between
+Note that there is no equivalent of the standard C distinction between
 the empty string (a pointer to an array of characters whose first
-element is zero) and the nonexistant string (a null pointer).  Any
+element is zero) and the nonexistent string (a null pointer).  Any
 .B dstr
 whose
 .B len
 is zero is an empty string.
-.SH "CREATION AND DESTRUCTION"
+.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
@@ -197,12 +209,12 @@ The
 function empties a string
 .I without
 deallocating any memory.  Therefore appending more characters is quick,
-beause the old buffer is still there and doesn't need to be allocated.
+because the old buffer is still there and doesn't need to be allocated.
 Calling
 .VS
 dstr_reset(d);
 .VE
-is equivalent to directly assinging
+is equivalent to directly assigning
 .VS
 d->len = 0;
 .VE
@@ -211,7 +223,7 @@ There's also a macro
 which does the same job as the
 .B dstr_reset
 function.
-.SH "EXTENDING A STRING"
+.SS "Extending a string"
 All memory allocation for strings is done by the function
 .BR dstr_ensure .
 Given a pointer 
@@ -254,11 +266,11 @@ The function
 `trims' a string's buffer so that it's just large enough for the string
 contents and a null terminating byte.  This might raise an exception due
 to lack of memory.  (There are two possible ways this might happen.
-Firstly, the underlying allocator might just be braindamaged enough to
+Firstly, the underlying allocator might just be brain-damaged enough to
 fail on reducing a block's size.  Secondly, tidying an empty string with no
 buffer allocated for it causes allocation of a buffer large enough for
 the terminating null byte.)
-.SH "CONTRIBUTING DATA TO A STRING"
+.SS "Contributing data to a string"
 There are a collection of functions which add data to a string.  All of
 these functions add their new data to the
 .I end
@@ -320,7 +332,7 @@ because the former has to do most of its work itself.  In particular,
 .B dstr_putf
 doesn't (and probably never will) understand the
 .RB ` n$ '
-positional paramter notation accepted by many Unix C libraries.  There
+positional parameter notation accepted by many Unix C libraries.  There
 is no macro equivalent of
 .BR dstr_putf .
 .PP
@@ -328,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
@@ -363,14 +378,15 @@ and appends it to a string.  If an error occurs, or end-of-file is
 encountered, before any characters have been read, then
 .B dstr_putline
 returns the value
-.BR EOF.
-Otherwise, it reads until it encounters a newline character, an error,
-or end-of-file, and returns the number of characters read.  If reading
-was terminated by a newline character, the newline character is
+.B EOF
+and does not extend the string.  Otherwise, it reads until it encounters
+a newline character, an error, or end-of-file, and returns the number of
+characters read.  If reading was terminated by a newline character, the
+newline character is
 .I not
 inserted in the buffer.  A terminating null is appended, as by
 .BR dstr_putz .
-.SH "OTHER FUNCTIONS"
+.SS "Other functions"
 The
 .B dstr_write
 function writes a string to an output stream
@@ -383,13 +399,13 @@ The macro
 .B DWRITE
 is equivalent.
 .SH "SECURITY CONSIDERATIONS"
-The implemenetation of the
+The implementation of the
 .B dstr
 functions is designed to do string handling in security-critical
 programs.  However, there may be bugs in the code somewhere.  In
 particular, the
 .B dstr_putf
-functions is quite complicated, and could do with some checking by
+functions are quite complicated, and could do with some checking by
 independent people who know what they're doing.
 .SH "SEE ALSO"
 .BR exc (3),