X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/b6b9d458c78364bdbbd7fbd7ec543bc364014b45..36b6fecc4670f4d351cd662a6772a5a196108ceb:/man/dstr.3 diff --git a/man/dstr.3 b/man/dstr.3 index 3eec044..b7c6cfb 100644 --- a/man/dstr.3 +++ b/man/dstr.3 @@ -1,7 +1,7 @@ .\" -*-nroff-*- .de VS .sp 1 -.RS 5 +.RS .nf .ft B .. @@ -11,7 +11,7 @@ .RE .sp 1 .. -.de HP +.de hP .IP .ft B \h'-\w'\\$1\ 'u'\\$1\ \c @@ -19,8 +19,36 @@ .. .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_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 " @@ -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 "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 ); .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 -.SH SUMMARY +.SH DESCRIPTION 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. -.SH "UNDERLYING TYPE" +.SS "Underlying type" 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 */ + arena *a; /* Pointer to arena */ } 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: -.HP \*o +.hP \*o If .B sz is nonzero, then @@ -119,31 +150,39 @@ If is zero, then .B buf is a null pointer. -.HP \*o +.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: -.HP \*o -Using the macro +structure. It can be initialized: +.hP \*o +using the macro .B DSTR_INIT -as an initializer in the declaration of the object. -.HP \*o -Passing its address to the +as an initializer in the declaration of the object, +.hP \*o +passing its address to the .B dstr_create -function. -.HP \*o -Passing its address to the (equivalent) +function, or +.hP \*o +passing its address to the (equivalent) .B DCREATE macro. .PP @@ -170,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 @@ -184,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 @@ -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 -.BR exc (3mLib) +.BR exc (3) 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. -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 @@ -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$ ' -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 @@ -301,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 @@ -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 -.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 @@ -356,13 +399,16 @@ 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), +.BR mLib (3). .SH AUTHOR -Mark Wooding, +Mark Wooding,