MAN PAGES FOR QMAIL 1.03

NAME

     stralloc - dynamically allocated strings

SYNTAX

     #include <stralloc.h>

     int stralloc_ready(&sa,len);
     int stralloc_readyplus(&sa,len);

     int stralloc_copy(&sa,&sa2);
     int stralloc_copys(&sa,buf);
     int stralloc_copyb(&sa,buf,len);

     int stralloc_cat(&sa,&sa2);
     int stralloc_cats(&sa,buf);
     int stralloc_catb(&sa,buf,len);

     int stralloc_append(&sa,buf);
     int stralloc_0(&sa);

     int stralloc_starts(&sa,buf);

     stralloc sa = {0};
     stralloc sa2 = {0};
     unsigned int len;
     char *buf;

DESCRIPTION

     A stralloc variable holds a string in dynamically  allocated
     space.   String  length  is  limited only by memory.  String
     contents are unrestricted.

     The stralloc structure has  three  components:   sa.s  is  a
     pointer  to  the string, or 0 if it is not allocated; sa.len
     is the number of bytes in the string, if  it  is  allocated;
     sa.a  is the number of bytes allocated for the string, if it
     is allocated.  A stralloc variable should be initialized  to
     {0}, meaning unallocated.

     stralloc_ready makes sure that sa has enough space allocated
     for len characters.  It allocates extra space if necessary.

     stralloc_readyplus makes sure that sa has enough space allo-
     cated  for  len characters more than its current length.  If
     sa  is  unallocated,  stralloc_readyplus  is  the  same   as
     stralloc_ready.

     stralloc_copy copies sa2 to sa, allocating space  if  neces-
     sary.  Here sa2 is an allocated stralloc variable.

     stralloc_copys copies a 0-terminated  string,  buf,  to  sa,
     without the 0.
     stralloc_copyb copies len characters from buf to sa.

     stralloc_cat appends sa2 to sa, allocating space  if  neces-
     sary.   If  sa  is  unallocated, stralloc_cat is the same as
     stralloc_copy.

     stralloc_cats   and   stralloc_catb   are    analogous    to
     stralloc_copys and stralloc_copyb.

     stralloc_append adds a single character, *buf, to sa,  allo-
     cating space if necessary.

     stralloc_0 adds a single 0 character to sa.

     stralloc_starts returns 1 if the  0-terminated  string  buf,
     without the 0, is a prefix of sa.

ERROR HANDLING

     If a stralloc routine runs out of memory, it leaves sa alone
     and  returns  0, setting errno appropriately.  On success it
     returns 1; this guarantees that sa is allocated.

SEE ALSO

     alloc(3), error(3)