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
          allocated 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
          necessary.  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
          necessary.  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,
          allocating 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)