mdw@git.distorted.org.uk Git - qmail/blob - stralloc.3

   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)