Commit | Line | Data |
---|---|---|
2117e02e MW |
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) |