src/interfaces/libpq/pqexpbuffer.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * pqexpbuffer.h
   4  *        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 provide
  15  * a usable vsnprintf(), then a copy of our own implementation of it will
  16  * be linked into libpq.
  17  *
  18  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
  19  * Portions Copyright (c) 1994, Regents of the University of California
  20  *
  21  * src/interfaces/libpq/pqexpbuffer.h
  22  *
  23  *-------------------------------------------------------------------------
  24  */
  25 #ifndef PQEXPBUFFER_H
  26 #define PQEXPBUFFER_H
  27
  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 be
  32  *                              a terminating '\0' at data[len], although this is not very
  33  *                              useful when the string holds binary data rather than text.
  34  *              maxlen  is the allocated size in bytes of 'data', i.e. the maximum
  35  *                              string size (including the terminating '\0' char) that we can
  36  *                              currently store in 'data' without having to reallocate
  37  *                              more space.  We must always have maxlen > len.
  38  *
  39  * An exception occurs if we failed to allocate enough memory for the string
  40  * buffer.  In that case data points to a statically allocated empty string,
  41  * and len = maxlen = 0.
  42  *-------------------------
  43  */
  44 typedef struct PQExpBufferData
  45 {
  46         char       *data;
  47         size_t          len;
  48         size_t          maxlen;
  49 } PQExpBufferData;
  50
  51 typedef 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 it
  56  * 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 might
  73  * be returned by PQrequestCancel().
  74  *------------------------
  75  */
  76 #define INITIAL_EXPBUFFER_SIZE  256
  77
  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 another
  88  *              struct.
  89  *-------------------------
  90  */
  91
  92 /*------------------------
  93  * createPQExpBuffer
  94  * Create an empty 'PQExpBufferData' & return a pointer to it.
  95  */
  96 extern PQExpBuffer createPQExpBuffer(void);
  97
  98 /*------------------------
  99  * initPQExpBuffer
 100  * Initialize a PQExpBufferData struct (with previously undefined contents)
 101  * to describe an empty string.
 102  */
 103 extern 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 then
 117  * release the PQExpBufferData but return the data string itself to their
 118  * caller.  At that point the data string looks like a plain malloc'd
 119  * string.
 120  */
 121 extern void destroyPQExpBuffer(PQExpBuffer str);
 122 extern void termPQExpBuffer(PQExpBuffer str);
 123
 124 /*------------------------
 125  * resetPQExpBuffer
 126  *              Reset a PQExpBuffer to empty
 127  *
 128  * Note: if possible, a "broken" PQExpBuffer is returned to normal.
 129  */
 130 extern void resetPQExpBuffer(PQExpBuffer str);
 131
 132 /*------------------------
 133  * enlargePQExpBuffer
 134  * Make sure there is enough space for 'needed' more bytes in the buffer
 135  * ('needed' does not include the terminating null).
 136  *
 137  * Returns 1 if OK, 0 if failed to enlarge buffer.  (In the latter case
 138  * the buffer is left in "broken" state.)
 139  */
 140 extern int      enlargePQExpBuffer(PQExpBuffer str, size_t needed);
 141
 142 /*------------------------
 143  * printfPQExpBuffer
 144  * 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 as
 147  * resetPQExpBuffer() followed by appendPQExpBuffer().
 148  */
 149 extern void printfPQExpBuffer(PQExpBuffer str, const char *fmt,...) pg_attribute_printf(2, 3);
 150
 151 /*------------------------
 152  * appendPQExpBuffer
 153  * 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 allocated
 155  * to str if necessary.  This is sort of like a combination of sprintf and
 156  * strcat.
 157  */
 158 extern void appendPQExpBuffer(PQExpBuffer str, const char *fmt,...) pg_attribute_printf(2, 3);
 159
 160 /*------------------------
 161  * appendPQExpBufferVA
 162  * Attempt to format data and append it to str.  Returns true if done
 163  * (either successful or hard failure), false if need to retry.
 164  *
 165  * Caution: callers must be sure to preserve their entry-time errno
 166  * when looping, in case the fmt contains "%m".
 167  */
 168 extern bool appendPQExpBufferVA(PQExpBuffer str, const char *fmt, va_list args) pg_attribute_printf(2, 0);
 169
 170 /*------------------------
 171  * appendPQExpBufferStr
 172  * Append the given string to a PQExpBuffer, allocating more space
 173  * if necessary.
 174  */
 175 extern void appendPQExpBufferStr(PQExpBuffer str, const char *data);
 176
 177 /*------------------------
 178  * appendPQExpBufferChar
 179  * Append a single byte to str.
 180  * Like appendPQExpBuffer(str, "%c", ch) but much faster.
 181  */
 182 extern void appendPQExpBufferChar(PQExpBuffer str, char ch);
 183
 184 /*------------------------
 185  * appendBinaryPQExpBuffer
 186  * Append arbitrary binary data to a PQExpBuffer, allocating more space
 187  * if necessary.
 188  */
 189 extern void appendBinaryPQExpBuffer(PQExpBuffer str,
 190                                                                         const char *data, size_t datalen);
 191
 192 #endif                                                  /* PQEXPBUFFER_H */