nightmaremail

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs

stralloc.3 (2624B)

      1 .TH stralloc 3
      2 .SH NAME
      3 stralloc \- dynamically allocated strings
      4 .SH SYNTAX
      5 .B #include <stralloc.h>
      6 
      7 int \fBstralloc_ready\fP(&\fIsa\fR,\fIlen\fR);
      8 .br
      9 int \fBstralloc_readyplus\fP(&\fIsa\fR,\fIlen\fR);
     10 
     11 int \fBstralloc_copy\fP(&\fIsa\fR,&\fIsa2\fR);
     12 .br
     13 int \fBstralloc_copys\fP(&\fIsa\fR,\fIbuf\fR);
     14 .br
     15 int \fBstralloc_copyb\fP(&\fIsa\fR,\fIbuf\fR,\fIlen\fR);
     16 
     17 int \fBstralloc_cat\fP(&\fIsa\fR,&\fIsa2\fR);
     18 .br
     19 int \fBstralloc_cats\fP(&\fIsa\fR,\fIbuf\fR);
     20 .br
     21 int \fBstralloc_catb\fP(&\fIsa\fR,\fIbuf\fR,\fIlen\fR);
     22 
     23 int \fBstralloc_append\fP(&\fIsa\fR,\fIbuf\fR);
     24 .br
     25 int \fBstralloc_0\fP(&\fIsa\fR);
     26 
     27 int \fBstralloc_starts\fP(&\fIsa\fR,\fIbuf\fR);
     28 
     29 stralloc \fIsa\fR = {0};
     30 .br
     31 stralloc \fIsa2\fR = {0};
     32 .br
     33 unsigned int \fIlen\fR;
     34 .br
     35 char *\fIbuf\fR;
     36 .SH DESCRIPTION
     37 A
     38 .B stralloc
     39 variable holds a string in dynamically allocated space.
     40 String length is limited only by memory.
     41 String contents are unrestricted.
     42 
     43 The
     44 .B stralloc
     45 structure has three components:
     46 .I sa\fB.s
     47 is a pointer to the string, or 0 if it is not allocated;
     48 .I sa\fB.len
     49 is the number of bytes in the string, if it is allocated;
     50 .I sa\fB.a
     51 is the number of bytes allocated for the string, if it is allocated.
     52 A
     53 .B stralloc
     54 variable should be initialized to {0},
     55 meaning unallocated.
     56 
     57 .B stralloc_ready
     58 makes sure that
     59 .I sa
     60 has enough space allocated for
     61 .I len
     62 characters.
     63 It allocates extra space if necessary.
     64 
     65 .B stralloc_readyplus
     66 makes sure that
     67 .I sa
     68 has enough space allocated for
     69 .I len
     70 characters more than its current length.
     71 If
     72 .I sa
     73 is unallocated,
     74 .B stralloc_readyplus
     75 is the same as
     76 .BR stralloc_ready .
     77 
     78 .B stralloc_copy
     79 copies
     80 .I sa2
     81 to
     82 .IR sa ,
     83 allocating space if necessary.
     84 Here
     85 .I sa2
     86 is an allocated
     87 .B stralloc
     88 variable.
     89 
     90 .B stralloc_copys
     91 copies a 0-terminated string,
     92 .IR buf ,
     93 to
     94 .IR sa ,
     95 without the 0.
     96 
     97 .B stralloc_copyb
     98 copies
     99 .I len
    100 characters from
    101 .I buf
    102 to
    103 .IR sa .
    104 
    105 .B stralloc_cat
    106 appends
    107 .I sa2
    108 to
    109 .IR sa ,
    110 allocating space if necessary.
    111 If
    112 .I sa
    113 is unallocated,
    114 .B stralloc_cat
    115 is the same as
    116 .BR stralloc_copy .
    117 
    118 .B stralloc_cats
    119 and
    120 .B stralloc_catb
    121 are analogous to
    122 .B stralloc_copys
    123 and
    124 .BR stralloc_copyb .
    125 
    126 .B stralloc_append
    127 adds a single character,
    128 .IR *buf ,
    129 to
    130 .IR sa ,
    131 allocating space if necessary.
    132 
    133 .B stralloc_0
    134 adds a single 0 character
    135 to
    136 .IR sa .
    137 
    138 .B stralloc_starts
    139 returns 1 if the 0-terminated string
    140 .IR buf ,
    141 without the 0,
    142 is a prefix of
    143 .IR sa .
    144 .SH "ERROR HANDLING"
    145 If a
    146 .B stralloc
    147 routine runs out of memory,
    148 it leaves
    149 .I sa
    150 alone and returns 0,
    151 setting
    152 .B errno
    153 appropriately.
    154 On success it returns 1;
    155 this guarantees that
    156 .I sa
    157 is allocated.
    158 .SH "SEE ALSO"
    159 alloc(3),
    160 error(3)