Change interface for @dstr_vputf@.

[mLib] / man / dstr.3

diff --git a/man/dstr.3 b/man/dstr.3
index 3eec044bece7d84cd20d6b6fb6bdd7ce70312fce..b7317157bf145652c7eef9eb14a30dc0fa1a7bfd 100644 (file)
--- a/man/dstr.3
+++ b/man/dstr.3
@@ -1,7 +1,7 @@
 .\" -*-nroff-*-
 .de VS
 .sp 1
 .\" -*-nroff-*-
 .de VS
 .sp 1

-.RS 5
+.RS

 .nf
 .ft B
 ..
 .nf
 .ft B
 ..


@@ -11,7 +11,7 @@
 .RE
 .sp 1
 ..
 .RE
 .sp 1
 ..

-.de HP
+.de hP

 .IP
 .ft B
 \h'-\w'\\$1\ 'u'\\$1\ \c
 .IP
 .ft B
 \h'-\w'\\$1\ 'u'\\$1\ \c


@@ -19,8 +19,36 @@
 ..
 .ie t .ds o \(bu
 .el .ds o o
 ..
 .ie t .ds o \(bu
 .el .ds o o

-.TH dstr 3mLib "8 May 1999" "mLib"
+.TH dstr 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME

 dstr \- a simple dynamic string type
 dstr \- a simple dynamic string type

+.\" @dstr_create
+.\" @dstr_destroy
+.\" @dstr_reset
+.\" @dstr_ensure
+.\" @dstr_tidy
+.\"
+.\" @dstr_putc
+.\" @dstr_putz
+.\" @dstr_puts
+.\" @dstr_putf
+.\" @dstr_putd
+.\" @dstr_putm
+.\" @dstr_putline
+.\" @dstr_write
+.\"
+.\" @DSTR_INIT
+.\" @DCREATE
+.\" @DDESTROY
+.\" @DRESET
+.\" @DENSURE
+.\" @DPUTC
+.\" @DPUTZ
+.\" @DPUTS
+.\" @DPUTD
+.\" @DPUTM
+.\" @DWRITE
+.\"

 .SH SYNOPSIS
 .nf
 .B "#include <mLib/dstr.h>"
 .SH SYNOPSIS
 .nf
 .B "#include <mLib/dstr.h>"


@@ -35,24 +63,26 @@ 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_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 "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 DENSURE(dstr *" d ", size_t " sz );
 .BI "void DCREATE(dstr *" d );
 .BI "void DDESTROY(dstr *" d );
 .BI "void DRESET(dstr *" d );
 .BI "void DENSURE(dstr *" d ", size_t " sz );

+.BI "void DPUTC(dstr *" c ", char " ch );

 .BI "void DPUTZ(dstr *" d );
 .BI "void DPUTS(dstr *" d ", const char *" s );
 .BI "void DPUTD(dstr *" d ", const dstr *" p );
 .BI "void DPUTM(dstr *" d ", const void *" p ", size_t " sz );
 .BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
 .fi
 .BI "void DPUTZ(dstr *" d );
 .BI "void DPUTS(dstr *" d ", const char *" s );
 .BI "void DPUTD(dstr *" d ", const dstr *" p );
 .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


@@ -65,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:


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


@@ -107,7 +138,7 @@ include a null-terminating byte, if there is one.
 The following invariants are maintained by
 .B dstr
 and must hold when any function is called:
 The following invariants are maintained by
 .B dstr
 and must hold when any function is called:

-.HP \*o
+.hP \*o

 If 
 .B sz
 is nonzero, then
 If 
 .B sz
 is nonzero, then


@@ -119,30 +150,38 @@ If
 is zero, then
 .B buf
 is a null pointer.
 is zero, then
 .B buf
 is a null pointer.

-.HP \*o
+.hP \*o

 At all times,
 At all times,

-.BI sz " >= " len\fR.
+.BR sz " \(>= " len.

 .PP
 .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
 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.
 .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:
 The caller is responsible for allocating the
 .B dstr
 structure.  It can be initialized in any of the following ways:

-.HP \*o
+.hP \*o

 Using the macro
 .B DSTR_INIT
 as an initializer in the declaration of the object.
 Using the macro
 .B DSTR_INIT
 as an initializer in the declaration of the object.

-.HP \*o
+.hP \*o

 Passing its address to the
 .B dstr_create
 function.
 Passing its address to the
 .B dstr_create
 function.

-.HP \*o
+.hP \*o

 Passing its address to the (equivalent)
 .B DCREATE
 macro.
 Passing its address to the (equivalent)
 .B DCREATE
 macro.


@@ -170,12 +209,12 @@ The
 function empties a string
 .I without
 deallocating any memory.  Therefore appending more characters is quick,
 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
 Calling
 .VS
 dstr_reset(d);
 .VE

-is equivalent to directly assinging
+is equivalent to directly assigning

 .VS
 d->len = 0;
 .VE
 .VS
 d->len = 0;
 .VE


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


@@ -204,7 +243,7 @@ Extending a string never returns a failure result.  Instead, if there
 isn't enough memory for a longer string, the exception
 .B EXC_NOMEM
 is raised.  See
 isn't enough memory for a longer string, the exception
 .B EXC_NOMEM
 is raised.  See

-.BR exc (3mLib)
+.BR exc (3)

 for more information about 
 .BR mLib 's
 exception handling system.
 for more information about 
 .BR mLib 's
 exception handling system.


@@ -227,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.
 `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.)
 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


@@ -293,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$ '
 .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
 is no macro equivalent of
 .BR dstr_putf .
 .PP


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


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


@@ -356,13 +399,16 @@ The macro
 .B DWRITE
 is equivalent.
 .SH "SECURITY CONSIDERATIONS"
 .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
 .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.
 independent people who know what they're doing.

+.SH "SEE ALSO"
+.BR exc (3),
+.BR mLib (3).

 .SH AUTHOR
 Mark Wooding, <mdw@nsict.org>
 .SH AUTHOR
 Mark Wooding, <mdw@nsict.org>