[qmail] / stralloc.3

.TH stralloc 3
.SH NAME
stralloc \- dynamically allocated strings
.SH SYNTAX
.B #include <stralloc.h>

int \fBstralloc_ready\fP(&\fIsa\fR,\fIlen\fR);
.br
int \fBstralloc_readyplus\fP(&\fIsa\fR,\fIlen\fR);

int \fBstralloc_copy\fP(&\fIsa\fR,&\fIsa2\fR);
.br
int \fBstralloc_copys\fP(&\fIsa\fR,\fIbuf\fR);
.br
int \fBstralloc_copyb\fP(&\fIsa\fR,\fIbuf\fR,\fIlen\fR);

int \fBstralloc_cat\fP(&\fIsa\fR,&\fIsa2\fR);
.br
int \fBstralloc_cats\fP(&\fIsa\fR,\fIbuf\fR);
.br
int \fBstralloc_catb\fP(&\fIsa\fR,\fIbuf\fR,\fIlen\fR);

int \fBstralloc_append\fP(&\fIsa\fR,\fIbuf\fR);
.br
int \fBstralloc_0\fP(&\fIsa\fR);

int \fBstralloc_starts\fP(&\fIsa\fR,\fIbuf\fR);

stralloc \fIsa\fR = {0};
.br
stralloc \fIsa2\fR = {0};
.br
unsigned int \fIlen\fR;
.br
char *\fIbuf\fR;
.SH DESCRIPTION
A
.B stralloc
variable holds a string in dynamically allocated space.
String length is limited only by memory.
String contents are unrestricted.

The
.B stralloc
structure has three components:
.I sa\fB.s
is a pointer to the string, or 0 if it is not allocated;
.I sa\fB.len
is the number of bytes in the string, if it is allocated;
.I sa\fB.a
is the number of bytes allocated for the string, if it is allocated.
A
.B stralloc
variable should be initialized to {0},
meaning unallocated.

.B stralloc_ready
makes sure that
.I sa
has enough space allocated for
.I len
characters.
It allocates extra space if necessary.

.B stralloc_readyplus
makes sure that
.I sa
has enough space allocated for
.I len
characters more than its current length.
If
.I sa
is unallocated,
.B stralloc_readyplus
is the same as
.BR stralloc_ready .

.B stralloc_copy
copies
.I sa2
to
.IR sa ,
allocating space if necessary.
Here
.I sa2
is an allocated
.B stralloc
variable.

.B stralloc_copys
copies a 0-terminated string,
.IR buf ,
to
.IR sa ,
without the 0.

.B stralloc_copyb
copies
.I len
characters from
.I buf
to
.IR sa .

.B stralloc_cat
appends
.I sa2
to
.IR sa ,
allocating space if necessary.
If
.I sa
is unallocated,
.B stralloc_cat
is the same as
.BR stralloc_copy .

.B stralloc_cats
and
.B stralloc_catb
are analogous to
.B stralloc_copys
and
.BR stralloc_copyb .

.B stralloc_append
adds a single character,
.IR *buf ,
to
.IR sa ,
allocating space if necessary.

.B stralloc_0
adds a single 0 character
to
.IR sa .

.B stralloc_starts
returns 1 if the 0-terminated string
.IR buf ,
without the 0,
is a prefix of
.IR sa .
.SH "ERROR HANDLING"
If a
.B stralloc
routine runs out of memory,
it leaves
.I sa
alone and returns 0,
setting
.B errno
appropriately.
On success it returns 1;
this guarantees that
.I sa
is allocated.
.SH "SEE ALSO"
alloc(3),
error(3)
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)