codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * pqexpbuffer.h4 *	  Declarations/definitions for "PQExpBuffer" functions.5 *6 * PQExpBuffer provides an indefinitely-extensible string data type.7 * It can be used to buffer either ordinary C strings (null-terminated text)8 * or arbitrary binary data.  All storage is allocated with malloc().9 *10 * This module is essentially the same as the backend's StringInfo data type,11 * but it is intended for use in frontend libpq and client applications.12 * Thus, it does not rely on palloc() nor elog().13 *14 * It does rely on vsnprintf(); if configure finds that libc doesn't provide15 * a usable vsnprintf(), then a copy of our own implementation of it will16 * be linked into libpq.17 *18 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group19 * Portions Copyright (c) 1994, Regents of the University of California20 *21 * src/interfaces/libpq/pqexpbuffer.h22 *23 *-------------------------------------------------------------------------24 */25#ifndef PQEXPBUFFER_H26#define PQEXPBUFFER_H27 28/*-------------------------29 * PQExpBufferData holds information about an extensible string.30 *		data	is the current buffer for the string (allocated with malloc).31 *		len		is the current string length.  There is guaranteed to be32 *				a terminating '\0' at data[len], although this is not very33 *				useful when the string holds binary data rather than text.34 *		maxlen	is the allocated size in bytes of 'data', i.e. the maximum35 *				string size (including the terminating '\0' char) that we can36 *				currently store in 'data' without having to reallocate37 *				more space.  We must always have maxlen > len.38 *39 * An exception occurs if we failed to allocate enough memory for the string40 * buffer.  In that case data points to a statically allocated empty string,41 * and len = maxlen = 0.42 *-------------------------43 */44typedef struct PQExpBufferData45{46	char	   *data;47	size_t		len;48	size_t		maxlen;49} PQExpBufferData;50 51typedef PQExpBufferData *PQExpBuffer;52 53/*------------------------54 * Test for a broken (out of memory) PQExpBuffer.55 * When a buffer is "broken", all operations except resetting or deleting it56 * are no-ops.57 *------------------------58 */59#define PQExpBufferBroken(str)	\60	((str) == NULL || (str)->maxlen == 0)61 62/*------------------------63 * Same, but for use when using a static or local PQExpBufferData struct.64 * For that, a null-pointer test is useless and may draw compiler warnings.65 *------------------------66 */67#define PQExpBufferDataBroken(buf)	\68	((buf).maxlen == 0)69 70/*------------------------71 * Initial size of the data buffer in a PQExpBuffer.72 * NB: this must be large enough to hold error messages that might73 * be returned by PQrequestCancel().74 *------------------------75 */76#define INITIAL_EXPBUFFER_SIZE	25677 78/*------------------------79 * There are two ways to create a PQExpBuffer object initially:80 *81 * PQExpBuffer stringptr = createPQExpBuffer();82 *		Both the PQExpBufferData and the data buffer are malloc'd.83 *84 * PQExpBufferData string;85 * initPQExpBuffer(&string);86 *		The data buffer is malloc'd but the PQExpBufferData is presupplied.87 *		This is appropriate if the PQExpBufferData is a field of another88 *		struct.89 *-------------------------90 */91 92/*------------------------93 * createPQExpBuffer94 * Create an empty 'PQExpBufferData' & return a pointer to it.95 */96extern PQExpBuffer createPQExpBuffer(void);97 98/*------------------------99 * initPQExpBuffer100 * Initialize a PQExpBufferData struct (with previously undefined contents)101 * to describe an empty string.102 */103extern void initPQExpBuffer(PQExpBuffer str);104 105/*------------------------106 * To destroy a PQExpBuffer, use either:107 *108 * destroyPQExpBuffer(str);109 *		free()s both the data buffer and the PQExpBufferData.110 *		This is the inverse of createPQExpBuffer().111 *112 * termPQExpBuffer(str)113 *		free()s the data buffer but not the PQExpBufferData itself.114 *		This is the inverse of initPQExpBuffer().115 *116 * NOTE: some routines build up a string using PQExpBuffer, and then117 * release the PQExpBufferData but return the data string itself to their118 * caller.  At that point the data string looks like a plain malloc'd119 * string.120 */121extern void destroyPQExpBuffer(PQExpBuffer str);122extern void termPQExpBuffer(PQExpBuffer str);123 124/*------------------------125 * resetPQExpBuffer126 *		Reset a PQExpBuffer to empty127 *128 * Note: if possible, a "broken" PQExpBuffer is returned to normal.129 */130extern void resetPQExpBuffer(PQExpBuffer str);131 132/*------------------------133 * enlargePQExpBuffer134 * Make sure there is enough space for 'needed' more bytes in the buffer135 * ('needed' does not include the terminating null).136 *137 * Returns 1 if OK, 0 if failed to enlarge buffer.  (In the latter case138 * the buffer is left in "broken" state.)139 */140extern int	enlargePQExpBuffer(PQExpBuffer str, size_t needed);141 142/*------------------------143 * printfPQExpBuffer144 * Format text data under the control of fmt (an sprintf-like format string)145 * and insert it into str.  More space is allocated to str if necessary.146 * This is a convenience routine that does the same thing as147 * resetPQExpBuffer() followed by appendPQExpBuffer().148 */149extern void printfPQExpBuffer(PQExpBuffer str, const char *fmt,...) pg_attribute_printf(2, 3);150 151/*------------------------152 * appendPQExpBuffer153 * Format text data under the control of fmt (an sprintf-like format string)154 * and append it to whatever is already in str.  More space is allocated155 * to str if necessary.  This is sort of like a combination of sprintf and156 * strcat.157 */158extern void appendPQExpBuffer(PQExpBuffer str, const char *fmt,...) pg_attribute_printf(2, 3);159 160/*------------------------161 * appendPQExpBufferVA162 * Attempt to format data and append it to str.  Returns true if done163 * (either successful or hard failure), false if need to retry.164 *165 * Caution: callers must be sure to preserve their entry-time errno166 * when looping, in case the fmt contains "%m".167 */168extern bool appendPQExpBufferVA(PQExpBuffer str, const char *fmt, va_list args) pg_attribute_printf(2, 0);169 170/*------------------------171 * appendPQExpBufferStr172 * Append the given string to a PQExpBuffer, allocating more space173 * if necessary.174 */175extern void appendPQExpBufferStr(PQExpBuffer str, const char *data);176 177/*------------------------178 * appendPQExpBufferChar179 * Append a single byte to str.180 * Like appendPQExpBuffer(str, "%c", ch) but much faster.181 */182extern void appendPQExpBufferChar(PQExpBuffer str, char ch);183 184/*------------------------185 * appendBinaryPQExpBuffer186 * Append arbitrary binary data to a PQExpBuffer, allocating more space187 * if necessary.188 */189extern void appendBinaryPQExpBuffer(PQExpBuffer str,190									const char *data, size_t datalen);191 192#endif							/* PQEXPBUFFER_H */193