Update manual style.

[mLib] / man / dstr.3

diff --git a/man/dstr.3 b/man/dstr.3
index 2ef8300abe92c44a929a597d412950e6b55640d3..e019b24c55633a4e4842d38da47dd8a5367cb111 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


@@ -68,6 +70,7 @@ dstr \- a simple dynamic string type
 .BI "int dstr_putline(dstr *" d ", FILE *" fp );
 .BI "size_t dstr_write(const dstr *" d ", FILE *" fp );
 
 .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,7 +161,15 @@ 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
 structure.  It can be initialized in any of the following ways:
 The caller is responsible for allocating the
 .B dstr
 structure.  It can be initialized in any of the following ways:


@@ -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


@@ -363,14 +375,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 +402,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),