This page last updated 1997-10-09. qmail now includes documentation for stralloc, making this page unnecessary. This paragraph added 1999-02-26.
The stralloc library is a set of stuff that the author of qmail, (about which more info is available at the qmail page) D. J. Bernstein, qmail@pobox.com wrote because he thought stdio strings were stupid. It's an instance of a more generic vector mechanism the author wrote in the C preprocessor.
The interface looks like this:
typedef struct stralloc { char *s; int len; int a; } stralloc;
extern int stralloc_ready(stralloc *x, int n);
extern int stralloc_readyplus(stralloc *x, int n);
/* beware: this takes a pointer to 1 char */
extern int stralloc_append(stralloc *sa, char *i);
extern int stralloc_copy(stralloc *sato, stralloc *safrom);
extern int stralloc_cat(stralloc *sato, stralloc *safrom);
extern int stralloc_copys(stralloc *sa, char *s);
extern int stralloc_cats(stralloc *sa, char *s);
extern int stralloc_copyb(stralloc *sa, char *s, unsigned n);
extern int stralloc_catb(stralloc *sa, char *s, unsigned n);
The fields of a stralloc have the meanings you'd guess: s points to the beginning of the string, len tells how long it is, and a tells how much space is allocated for it. s is NULL if the stralloc has not been successfully initialized. If s is null, the len and a fields may have all sorts of values; ignore them.
extern int stralloc_ready(stralloc *x, int n);
stralloc_ready makes the stralloc x able to hold a string of length n. If the stralloc is already big enough, stralloc_ready just returns 1. If it needs to be expanded a bit, the stralloc will be expanded until it can hold the string, plus thirty chars, plus an extra eighth of the string. If it has not been initialized, it will be initialized to hold exactly the size of the string. Like the other functions, it returns 0 on failure or 1 on success. On success, you can safely copy the string into the stralloc; on failure, the stralloc is left unharmed.
extern int stralloc_readyplus(stralloc *x, int n);
stralloc_readyplus appears to be mostly cut and pasted from stralloc_ready. It makes sure n characters can be appended onto the stralloc; its behavior is otherwise exactly the same as stralloc_ready. It treats an uninitialized stralloc the same way stralloc_ready does -- makes it able to hold exactly the number of chars passed as an argument.
All the following functions use the above two to ensure that they don't fandango on core:
extern int stralloc_append(stralloc *sa, char *i);
stralloc_append is a very simple function; it appends a single character (passed by reference in *i) to the stralloc *sa. Like the other functions, it returns 0 on failure or 1 on success.
extern int stralloc_copy(stralloc *sato, stralloc *safrom);
stralloc_copy copies one stralloc, *safrom, to another, *sato. Like the other functions, it returns 0 on failure or 1 on success.
extern int stralloc_cat(stralloc *sato, stralloc *safrom);
stralloc_cat appends one stralloc, *safrom to another, *sato. Like the other functions, it returns 0 on failure or 1 on success.
extern int stralloc_copys(stralloc *sa, char *s);
stralloc_copys copies a null-terminated string s into a stralloc. It replaces the null at the end with a capital `Z' to let you know if you've done something stupid. Like the other functions, it returns 0 on failure or 1 on success.
extern int stralloc_cats(stralloc *sa, char *s);
stralloc_cats appends a null-terminated string onto the stralloc *sa. It doesn't bother to do the offensive programming stralloc_copys does. Like the other functions, it returns 0 on failure or 1 on success.
extern int stralloc_copyb(stralloc *sa, char *s, unsigned n);
stralloc_copyb copies a string of n bytes starting at s into the stralloc *sa. Like the other functions, it returns 0 on failure or 1 on success.
extern int stralloc_catb(stralloc *sa, char *s, unsigned n);
stralloc_catb appends n bytes starting at s to the stralloc *sa. Like the other functions, it returns 0 on failure or 1 on success.