1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
/*-------------------------------------------------------------------------
*
* pqexpbuffer.h
* Declarations/definitions for "PQExpBuffer" functions.
*
* PQExpBuffer provides an indefinitely-extensible string data type.
* It can be used to buffer either ordinary C strings (null-terminated text)
* or arbitrary binary data. All storage is allocated with malloc().
*
* This module is essentially the same as the backend's StringInfo data type,
* but it is intended for use in frontend libpq and client applications.
* Thus, it does not rely on palloc() nor elog().
*
* It does rely on vsnprintf(); if configure finds that libc doesn't provide
* a usable vsnprintf(), then a copy of our own implementation of it will
* be linked into libpq.
*
* Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/interfaces/libpq/pqexpbuffer.h
*
*-------------------------------------------------------------------------
*/
#ifndef PQEXPBUFFER_H
#define PQEXPBUFFER_H
/*-------------------------
* PQExpBufferData holds information about an extensible string.
* data is the current buffer for the string (allocated with malloc).
* len is the current string length. There is guaranteed to be
* a terminating '\0' at data[len], although this is not very
* useful when the string holds binary data rather than text.
* maxlen is the allocated size in bytes of 'data', i.e. the maximum
* string size (including the terminating '\0' char) that we can
* currently store in 'data' without having to reallocate
* more space. We must always have maxlen > len.
*
* An exception occurs if we failed to allocate enough memory for the string
* buffer. In that case data points to a statically allocated empty string,
* and len = maxlen = 0.
*-------------------------
*/
typedef struct PQExpBufferData
{
char *data;
size_t len;
size_t maxlen;
} PQExpBufferData;
typedef PQExpBufferData *PQExpBuffer;
/*------------------------
* Test for a broken (out of memory) PQExpBuffer.
* When a buffer is "broken", all operations except resetting or deleting it
* are no-ops.
*------------------------
*/
#define PQExpBufferBroken(str) \
((str) == NULL || (str)->maxlen == 0)
/*------------------------
* Same, but for use when using a static or local PQExpBufferData struct.
* For that, a null-pointer test is useless and may draw compiler warnings.
*------------------------
*/
#define PQExpBufferDataBroken(buf) \
((buf).maxlen == 0)
/*------------------------
* Initial size of the data buffer in a PQExpBuffer.
* NB: this must be large enough to hold error messages that might
* be returned by PQrequestCancel().
*------------------------
*/
#define INITIAL_EXPBUFFER_SIZE 256
/*------------------------
* There are two ways to create a PQExpBuffer object initially:
*
* PQExpBuffer stringptr = createPQExpBuffer();
* Both the PQExpBufferData and the data buffer are malloc'd.
*
* PQExpBufferData string;
* initPQExpBuffer(&string);
* The data buffer is malloc'd but the PQExpBufferData is presupplied.
* This is appropriate if the PQExpBufferData is a field of another
* struct.
*-------------------------
*/
/*------------------------
* createPQExpBuffer
* Create an empty 'PQExpBufferData' & return a pointer to it.
*/
extern PQExpBuffer createPQExpBuffer(void);
/*------------------------
* initPQExpBuffer
* Initialize a PQExpBufferData struct (with previously undefined contents)
* to describe an empty string.
*/
extern void initPQExpBuffer(PQExpBuffer str);
/*------------------------
* To destroy a PQExpBuffer, use either:
*
* destroyPQExpBuffer(str);
* free()s both the data buffer and the PQExpBufferData.
* This is the inverse of createPQExpBuffer().
*
* termPQExpBuffer(str)
* free()s the data buffer but not the PQExpBufferData itself.
* This is the inverse of initPQExpBuffer().
*
* NOTE: some routines build up a string using PQExpBuffer, and then
* release the PQExpBufferData but return the data string itself to their
* caller. At that point the data string looks like a plain malloc'd
* string.
*/
extern void destroyPQExpBuffer(PQExpBuffer str);
extern void termPQExpBuffer(PQExpBuffer str);
/*------------------------
* resetPQExpBuffer
* Reset a PQExpBuffer to empty
*
* Note: if possible, a "broken" PQExpBuffer is returned to normal.
*/
extern void resetPQExpBuffer(PQExpBuffer str);
/*------------------------
* enlargePQExpBuffer
* Make sure there is enough space for 'needed' more bytes in the buffer
* ('needed' does not include the terminating null).
*
* Returns 1 if OK, 0 if failed to enlarge buffer. (In the latter case
* the buffer is left in "broken" state.)
*/
extern int enlargePQExpBuffer(PQExpBuffer str, size_t needed);
/*------------------------
* printfPQExpBuffer
* Format text data under the control of fmt (an sprintf-like format string)
* and insert it into str. More space is allocated to str if necessary.
* This is a convenience routine that does the same thing as
* resetPQExpBuffer() followed by appendPQExpBuffer().
*/
extern void printfPQExpBuffer(PQExpBuffer str, const char *fmt,...) pg_attribute_printf(2, 3);
/*------------------------
* appendPQExpBuffer
* Format text data under the control of fmt (an sprintf-like format string)
* and append it to whatever is already in str. More space is allocated
* to str if necessary. This is sort of like a combination of sprintf and
* strcat.
*/
extern void appendPQExpBuffer(PQExpBuffer str, const char *fmt,...) pg_attribute_printf(2, 3);
/*------------------------
* appendPQExpBufferStr
* Append the given string to a PQExpBuffer, allocating more space
* if necessary.
*/
extern void appendPQExpBufferStr(PQExpBuffer str, const char *data);
/*------------------------
* appendPQExpBufferChar
* Append a single byte to str.
* Like appendPQExpBuffer(str, "%c", ch) but much faster.
*/
extern void appendPQExpBufferChar(PQExpBuffer str, char ch);
/*------------------------
* appendBinaryPQExpBuffer
* Append arbitrary binary data to a PQExpBuffer, allocating more space
* if necessary.
*/
extern void appendBinaryPQExpBuffer(PQExpBuffer str,
const char *data, size_t datalen);
#endif /* PQEXPBUFFER_H */
|
