Age Owner Branch data TLA Line data Source code
1 : : /*-------------------------------------------------------------------------
2 : : *
3 : : * stringinfo.c
4 : : *
5 : : * StringInfo provides an extensible string data type (currently limited to a
6 : : * length of 1GB). It can be used to buffer either ordinary C strings
7 : : * (null-terminated text) or arbitrary binary data. All storage is allocated
8 : : * with palloc() (falling back to malloc in frontend code).
9 : : *
10 : : * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
11 : : * Portions Copyright (c) 1994, Regents of the University of California
12 : : *
13 : : * src/common/stringinfo.c
14 : : *
15 : : *-------------------------------------------------------------------------
16 : : */
17 : :
18 : : #ifndef FRONTEND
19 : :
20 : : #include "postgres.h"
21 : : #include "utils/memutils.h"
22 : :
23 : : #else
24 : :
25 : : #include "postgres_fe.h"
26 : :
27 : : #endif
28 : :
29 : : #include "lib/stringinfo.h"
30 : :
31 : :
32 : : /*
33 : : * initStringInfoInternal
34 : : *
35 : : * Initialize a StringInfoData struct (with previously undefined contents)
36 : : * to describe an empty string.
37 : : * The initial memory allocation size is specified by 'initsize'.
38 : : * The valid range for 'initsize' is 1 to MaxAllocSize.
39 : : */
40 : : static inline void
593 ishii@postgresql.org 41 :CBC 6817931 : initStringInfoInternal(StringInfo str, int initsize)
42 : : {
43 [ + - + + ]: 6817931 : Assert(initsize >= 1 && initsize <= MaxAllocSize);
44 : :
45 : 6817931 : str->data = (char *) palloc(initsize);
46 : 6817931 : str->maxlen = initsize;
47 : 6817931 : resetStringInfo(str);
48 : 6817931 : }
49 : :
50 : : /*
51 : : * makeStringInfoInternal(int initsize)
52 : : *
53 : : * Create an empty 'StringInfoData' & return a pointer to it.
54 : : * The initial memory allocation size is specified by 'initsize'.
55 : : * The valid range for 'initsize' is 1 to MaxAllocSize.
56 : : */
57 : : static inline StringInfo
58 : 66278 : makeStringInfoInternal(int initsize)
59 : : {
261 michael@paquier.xyz 60 : 66278 : StringInfo res = palloc_object(StringInfoData);
61 : :
593 ishii@postgresql.org 62 : 66278 : initStringInfoInternal(res, initsize);
63 : 66278 : return res;
64 : : }
65 : :
66 : : /*
67 : : * makeStringInfo
68 : : *
69 : : * Create an empty 'StringInfoData' & return a pointer to it.
70 : : */
71 : : StringInfo
9986 tgl@sss.pgh.pa.us 72 : 66226 : makeStringInfo(void)
73 : : {
593 ishii@postgresql.org 74 : 66226 : return makeStringInfoInternal(STRINGINFO_DEFAULT_SIZE);
75 : : }
76 : :
77 : : /*
78 : : * makeStringInfoExt(int initsize)
79 : : *
80 : : * Create an empty 'StringInfoData' & return a pointer to it.
81 : : * The initial memory allocation size is specified by 'initsize'.
82 : : * The valid range for 'initsize' is 1 to MaxAllocSize.
83 : : */
84 : : StringInfo
85 : 52 : makeStringInfoExt(int initsize)
86 : : {
87 : 52 : return makeStringInfoInternal(initsize);
88 : : }
89 : :
90 : : /*
91 : : * initStringInfo
92 : : *
93 : : * Initialize a StringInfoData struct (with previously undefined contents)
94 : : * to describe an empty string.
95 : : */
96 : : void
9986 tgl@sss.pgh.pa.us 97 : 6738265 : initStringInfo(StringInfo str)
98 : : {
593 ishii@postgresql.org 99 : 6738265 : initStringInfoInternal(str, STRINGINFO_DEFAULT_SIZE);
100 : 6738265 : }
101 : :
102 : : /*
103 : : * initStringInfoExt
104 : : *
105 : : * Initialize a StringInfoData struct (with previously undefined contents)
106 : : * to describe an empty string.
107 : : * The initial memory allocation size is specified by 'initsize'.
108 : : * The valid range for 'initsize' is 1 to MaxAllocSize.
109 : : */
110 : : void
111 : 13388 : initStringInfoExt(StringInfo str, int initsize)
112 : : {
113 : 13388 : initStringInfoInternal(str, initsize);
7117 neilc@samurai.com 114 : 13388 : }
115 : :
116 : : /*
117 : : * resetStringInfo
118 : : *
119 : : * Reset the StringInfo: the data buffer remains valid, but its
120 : : * previous content, if any, is cleared.
121 : : *
122 : : * Read-only StringInfos as initialized by initReadOnlyStringInfo cannot be
123 : : * reset.
124 : : */
125 : : void
126 : 21740067 : resetStringInfo(StringInfo str)
127 : : {
128 : : /* don't allow resets of read-only StringInfos */
1036 drowley@postgresql.o 129 [ - + ]: 21740067 : Assert(str->maxlen != 0);
130 : :
9986 tgl@sss.pgh.pa.us 131 : 21740067 : str->data[0] = '\0';
7117 neilc@samurai.com 132 : 21740067 : str->len = 0;
8531 tgl@sss.pgh.pa.us 133 : 21740067 : str->cursor = 0;
9986 134 : 21740067 : }
135 : :
136 : : /*
137 : : * appendStringInfo
138 : : *
139 : : * Format text data under the control of fmt (an sprintf-style format string)
140 : : * and append it to whatever is already in str. More space is allocated
141 : : * to str if necessary. This is sort of like a combination of sprintf and
142 : : * strcat.
143 : : */
144 : : void
106 145 : 28614887 : appendStringInfo(StringInfo str, const char *fmt, ...)
146 : : {
2892 147 : 28614887 : int save_errno = errno;
148 : :
149 : : for (;;)
8526 150 : 32108 : {
151 : : va_list args;
152 : : int needed;
153 : :
154 : : /* Try to format the data. */
155 : 28646995 : va_start(args, fmt);
4690 156 : 28646995 : needed = appendStringInfoVA(str, fmt, args);
8526 157 : 28646995 : va_end(args);
158 : :
7 tgl@sss.pgh.pa.us 159 [ + + ]:GNC 28646995 : if (likely(needed == 0))
4690 tgl@sss.pgh.pa.us 160 :CBC 28614887 : break; /* success */
161 : :
162 : : /* Increase the buffer size and try again. */
163 : 32108 : enlargeStringInfo(str, needed);
7 tgl@sss.pgh.pa.us 164 :GNC 32108 : errno = save_errno;
165 : : }
8526 tgl@sss.pgh.pa.us 166 :CBC 28614887 : }
167 : :
168 : : /*
169 : : * appendStringInfoVA
170 : : *
171 : : * Attempt to format text data under the control of fmt (an sprintf-style
172 : : * format string) and append it to whatever is already in str. If successful
173 : : * return zero; if not (because there's not enough space), return an estimate
174 : : * of the space needed, without modifying str. Typically the caller should
175 : : * pass the return value to enlargeStringInfo() before trying again; see
176 : : * appendStringInfo for standard usage pattern.
177 : : *
178 : : * Caution: callers must be sure to preserve their entry-time errno
179 : : * when looping, in case the fmt contains "%m".
180 : : *
181 : : * XXX This API is ugly, but there seems no alternative given the C spec's
182 : : * restrictions on what can portably be done with va_list arguments: you have
183 : : * to redo va_start before you can rescan the argument list, and we can't do
184 : : * that from here.
185 : : */
186 : : inline int
187 : 29029051 : appendStringInfoVA(StringInfo str, const char *fmt, va_list args)
188 : : {
189 : : int avail;
190 : : int nprinted;
191 : :
192 : : /*
193 : : * If there's hardly any space, don't bother trying, just fail to make the
194 : : * caller enlarge the buffer first. We have to guess at how much to
195 : : * enlarge, since we're skipping the formatting work.
196 : : */
4690 197 : 29029051 : avail = str->maxlen - str->len;
8526 198 [ + + ]: 29029051 : if (avail < 16)
4690 199 : 30030 : return 32;
200 : :
7 tgl@sss.pgh.pa.us 201 :GNC 28999021 : nprinted = vsnprintf(str->data + str->len, (size_t) avail, fmt, args);
202 : :
203 : : /* We assume failure means the fmt is bogus, hence hard failure is OK */
204 [ - + ]: 28999021 : if (unlikely(nprinted < 0))
205 : : {
206 : : #ifndef FRONTEND
7 tgl@sss.pgh.pa.us 207 [ # # ]:UNC 0 : elog(ERROR, "vsnprintf failed: %m with format string \"%s\"", fmt);
208 : : #else
209 : 0 : fprintf(stderr, "vsnprintf failed: %m with format string \"%s\"\n",
210 : : fmt);
211 : 0 : exit(EXIT_FAILURE);
212 : : #endif
213 : : }
214 : :
7 tgl@sss.pgh.pa.us 215 [ + + ]:GNC 28999021 : if (likely(nprinted < avail))
216 : : {
217 : : /* Success. Note nprinted does not include trailing null. */
218 : 28994330 : str->len += nprinted;
4690 tgl@sss.pgh.pa.us 219 :CBC 28994330 : return 0;
220 : : }
221 : :
222 : : /* Restore the trailing null so that str is unmodified. */
8526 223 : 4691 : str->data[str->len] = '\0';
224 : :
225 : : /*
226 : : * We assume a C99-compliant vsnprintf, so believe its estimate of the
227 : : * required space. (If it's wrong, the logic will still work, but we may
228 : : * loop multiple times.)
229 : : *
230 : : * Unlike pvsnprintf(), we don't check for overrunning MaxAllocSize,
231 : : * preferring to leave that to enlargeStringInfo().
232 : : */
7 tgl@sss.pgh.pa.us 233 :GNC 4691 : return nprinted;
234 : : }
235 : :
236 : : /*
237 : : * appendStringInfoString
238 : : *
239 : : * Append a null-terminated string to str.
240 : : * Like appendStringInfo(str, "%s", s) but faster.
241 : : */
242 : : void
8526 tgl@sss.pgh.pa.us 243 :CBC 11762367 : appendStringInfoString(StringInfo str, const char *s)
244 : : {
245 : 11762367 : appendBinaryStringInfo(str, s, strlen(s));
9986 246 : 11762367 : }
247 : :
248 : : /*
249 : : * appendStringInfoChar
250 : : *
251 : : * Append a single byte to str.
252 : : * Like appendStringInfo(str, "%c", ch) but much faster.
253 : : */
254 : : void
255 : 60861860 : appendStringInfoChar(StringInfo str, char ch)
256 : : {
257 : : /* Make more room if needed */
9796 258 [ + + ]: 60861860 : if (str->len + 1 >= str->maxlen)
259 : 17049 : enlargeStringInfo(str, 1);
260 : :
261 : : /* OK, append the character */
9986 262 : 60861860 : str->data[str->len] = ch;
263 : 60861860 : str->len++;
264 : 60861860 : str->data[str->len] = '\0';
265 : 60861860 : }
266 : :
267 : : /*
268 : : * appendStringInfoSpaces
269 : : *
270 : : * Append the specified number of spaces to a buffer.
271 : : */
272 : : void
6243 273 : 151806 : appendStringInfoSpaces(StringInfo str, int count)
274 : : {
275 [ + + ]: 151806 : if (count > 0)
276 : : {
277 : : /* Make more room if needed */
278 : 147348 : enlargeStringInfo(str, count);
279 : :
280 : : /* OK, append the spaces */
1315 drowley@postgresql.o 281 : 147348 : memset(&str->data[str->len], ' ', count);
282 : 147348 : str->len += count;
6243 tgl@sss.pgh.pa.us 283 : 147348 : str->data[str->len] = '\0';
284 : : }
285 : 151806 : }
286 : :
287 : : /*
288 : : * appendBinaryStringInfo
289 : : *
290 : : * Append arbitrary binary data to a StringInfo, allocating more space
291 : : * if necessary. Ensures that a trailing null byte is present.
292 : : */
293 : : void
1336 peter@eisentraut.org 294 : 23902047 : appendBinaryStringInfo(StringInfo str, const void *data, int datalen)
295 : : {
9986 tgl@sss.pgh.pa.us 296 [ - + ]: 23902047 : Assert(str != NULL);
297 : :
298 : : /* Make more room if needed */
299 : 23902047 : enlargeStringInfo(str, datalen);
300 : :
301 : : /* OK, append the data */
302 : 23902047 : memcpy(str->data + str->len, data, datalen);
303 : 23902047 : str->len += datalen;
304 : :
305 : : /*
306 : : * Keep a trailing null in place, even though it's probably useless for
307 : : * binary data. (Some callers are dealing with text but call this because
308 : : * their input isn't null-terminated.)
309 : : */
310 : 23902047 : str->data[str->len] = '\0';
11006 scrappy@hub.org 311 : 23902047 : }
312 : :
313 : : /*
314 : : * appendBinaryStringInfoNT
315 : : *
316 : : * Append arbitrary binary data to a StringInfo, allocating more space
317 : : * if necessary. Does not ensure a trailing null-byte exists.
318 : : */
319 : : void
1336 peter@eisentraut.org 320 : 18979330 : appendBinaryStringInfoNT(StringInfo str, const void *data, int datalen)
321 : : {
3242 andres@anarazel.de 322 [ - + ]: 18979330 : Assert(str != NULL);
323 : :
324 : : /* Make more room if needed */
325 : 18979330 : enlargeStringInfo(str, datalen);
326 : :
327 : : /* OK, append the data */
328 : 18979330 : memcpy(str->data + str->len, data, datalen);
329 : 18979330 : str->len += datalen;
330 : 18979330 : }
331 : :
332 : : /*
333 : : * enlargeStringInfo
334 : : *
335 : : * Make sure there is enough space for 'needed' more bytes
336 : : * ('needed' does not include the terminating null).
337 : : *
338 : : * External callers usually need not concern themselves with this, since
339 : : * all stringinfo.c routines do it automatically. However, if a caller
340 : : * knows that a StringInfo will eventually become X bytes large, it
341 : : * can save some palloc overhead by enlarging the buffer before starting
342 : : * to store data in it.
343 : : *
344 : : * NB: In the backend, because we use repalloc() to enlarge the buffer, the
345 : : * string buffer will remain allocated in the same memory context that was
346 : : * current when initStringInfo was called, even if another context is now
347 : : * current. This is the desired and indeed critical behavior!
348 : : */
349 : : void
8531 tgl@sss.pgh.pa.us 350 : 74812889 : enlargeStringInfo(StringInfo str, int needed)
351 : : {
352 : : int newlen;
353 : :
354 : : /* validate this is not a read-only StringInfo */
1036 drowley@postgresql.o 355 [ - + ]: 74812889 : Assert(str->maxlen != 0);
356 : :
357 : : /*
358 : : * Guard against out-of-range "needed" values. Without this, we can get
359 : : * an overflow or infinite loop in the following.
360 : : */
7031 tgl@sss.pgh.pa.us 361 [ - + ]: 74812889 : if (needed < 0) /* should not happen */
362 : : {
363 : : #ifndef FRONTEND
7031 tgl@sss.pgh.pa.us 364 [ # # ]:UBC 0 : elog(ERROR, "invalid string enlargement request size: %d", needed);
365 : : #else
2487 andres@anarazel.de 366 : 0 : fprintf(stderr, "invalid string enlargement request size: %d\n", needed);
367 : 0 : exit(EXIT_FAILURE);
368 : : #endif
369 : : }
3396 alvherre@alvh.no-ip. 370 [ - + ]:CBC 74812889 : if (((Size) needed) >= (MaxAllocSize - (Size) str->len))
371 : : {
372 : : #ifndef FRONTEND
7031 tgl@sss.pgh.pa.us 373 [ # # ]:UBC 0 : ereport(ERROR,
374 : : (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
375 : : errmsg("string buffer exceeds maximum allowed length (%zu bytes)", MaxAllocSize),
376 : : errdetail("Cannot enlarge string buffer containing %d bytes by %d more bytes.",
377 : : str->len, needed)));
378 : : #else
2487 andres@anarazel.de 379 : 0 : fprintf(stderr,
787 drowley@postgresql.o 380 : 0 : _("string buffer exceeds maximum allowed length (%zu bytes)\n\nCannot enlarge string buffer containing %d bytes by %d more bytes.\n"),
381 : : MaxAllocSize, str->len, needed);
2487 andres@anarazel.de 382 : 0 : exit(EXIT_FAILURE);
383 : : #endif
384 : : }
385 : :
8531 tgl@sss.pgh.pa.us 386 :CBC 74812889 : needed += str->len + 1; /* total space required now */
387 : :
388 : : /* Because of the above test, we now have needed <= MaxAllocSize */
389 : :
390 [ + + ]: 74812889 : if (needed <= str->maxlen)
391 : 74666593 : return; /* got enough space already */
392 : :
393 : : /*
394 : : * We don't want to allocate just a little more space with each append;
395 : : * for efficiency, double the buffer size each time it overflows.
396 : : * Actually, we might need to more than double it if 'needed' is big...
397 : : */
3396 alvherre@alvh.no-ip. 398 : 146296 : newlen = 2 * str->maxlen;
399 [ + + ]: 308129 : while (needed > newlen)
8531 tgl@sss.pgh.pa.us 400 : 161833 : newlen = 2 * newlen;
401 : :
402 : : /*
403 : : * Clamp to MaxAllocSize in case we went past it. Note we are assuming
404 : : * here that MaxAllocSize <= INT_MAX/2, else the above loop could
405 : : * overflow. We will still have newlen >= needed.
406 : : */
3396 alvherre@alvh.no-ip. 407 [ - + ]: 146296 : if (newlen > (int) MaxAllocSize)
3396 alvherre@alvh.no-ip. 408 :UBC 0 : newlen = (int) MaxAllocSize;
409 : :
3396 alvherre@alvh.no-ip. 410 :CBC 146296 : str->data = (char *) repalloc(str->data, newlen);
411 : :
8531 tgl@sss.pgh.pa.us 412 : 146296 : str->maxlen = newlen;
413 : : }
414 : :
415 : : /*
416 : : * destroyStringInfo
417 : : *
418 : : * Frees a StringInfo and its buffer (opposite of makeStringInfo()).
419 : : * This must only be called on palloc'd StringInfos.
420 : : */
421 : : void
894 dgustafsson@postgres 422 : 5589 : destroyStringInfo(StringInfo str)
423 : : {
424 : : /* don't allow destroys of read-only StringInfos */
425 [ - + ]: 5589 : Assert(str->maxlen != 0);
426 : :
427 : 5589 : pfree(str->data);
428 : 5589 : pfree(str);
429 : 5589 : }
|
