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)