Various Debian fixes.

[mLib] / man / dstr.3

diff --git a/man/dstr.3 b/man/dstr.3
index 2ef8300abe92c44a929a597d412950e6b55640d3..70d729271a7125889a414f991055431b14dbf629 100644 (file)
--- a/man/dstr.3
+++ b/man/dstr.3
@@ -19,7 +19,8 @@
 ..
 .ie t .ds o \(bu
 .el .ds o o
 ..
 .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
 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_putline
 .\" @dstr_write
 .\"

+.\" @DSTR_INIT

 .\" @DCREATE
 .\" @DDESTROY
 .\" @DRESET
 .\" @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 "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 );
 .BI "int dstr_putline(dstr *" d ", FILE *" fp );
 .BI "size_t dstr_write(const dstr *" d ", FILE *" fp );
 
 .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 );
 .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
 .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
 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.
 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:
 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 */
   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
 } dstr;
 .VE
 The


@@ -148,7 +152,7 @@ is zero, then
 is a null pointer.
 .hP \*o
 At all times,
 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
 .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


@@ -157,20 +161,28 @@ element is zero) and the nonexistent string (a null pointer).  Any
 whose
 .B len
 is zero is an empty string.
 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
 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
 .hP \*o

-Using the macro
+using the macro

 .B DSTR_INIT
 .B DSTR_INIT

-as an initializer in the declaration of the object.
+as an initializer in the declaration of the object,

 .hP \*o
 .hP \*o

-Passing its address to the
+passing its address to the

 .B dstr_create
 .B dstr_create

-function.
+function, or

 .hP \*o
 .hP \*o

-Passing its address to the (equivalent)
+passing its address to the (equivalent)

 .B DCREATE
 macro.
 .PP
 .B DCREATE
 macro.
 .PP


@@ -211,7 +223,7 @@ There's also a macro
 which does the same job as the
 .B dstr_reset
 function.
 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 
 All memory allocation for strings is done by the function
 .BR dstr_ensure .
 Given a pointer 


@@ -258,7 +270,7 @@ 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.)
 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
 There are a collection of functions which add data to a string.  All of
 these functions add their new data to the
 .I end


@@ -328,12 +340,15 @@ The function
 .B dstr_vputf
 provides access to the `guts' of
 .BR dstr_putf :
 .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
 .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
 .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
 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 .
 .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
 The
 .B dstr_write
 function writes a string to an output stream


@@ -389,7 +405,7 @@ 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
 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),
 independent people who know what they're doing.
 .SH "SEE ALSO"
 .BR exc (3),