Header And Logo

PostgreSQL
| The world's most advanced open source database.

pqexpbuffer.h

Go to the documentation of this file.
00001 /*-------------------------------------------------------------------------
00002  *
00003  * pqexpbuffer.h
00004  *    Declarations/definitions for "PQExpBuffer" functions.
00005  *
00006  * PQExpBuffer provides an indefinitely-extensible string data type.
00007  * It can be used to buffer either ordinary C strings (null-terminated text)
00008  * or arbitrary binary data.  All storage is allocated with malloc().
00009  *
00010  * This module is essentially the same as the backend's StringInfo data type,
00011  * but it is intended for use in frontend libpq and client applications.
00012  * Thus, it does not rely on palloc() nor elog().
00013  *
00014  * It does rely on vsnprintf(); if configure finds that libc doesn't provide
00015  * a usable vsnprintf(), then a copy of our own implementation of it will
00016  * be linked into libpq.
00017  *
00018  * Portions Copyright (c) 1996-2013, PostgreSQL Global Development Group
00019  * Portions Copyright (c) 1994, Regents of the University of California
00020  *
00021  * src/interfaces/libpq/pqexpbuffer.h
00022  *
00023  *-------------------------------------------------------------------------
00024  */
00025 #ifndef PQEXPBUFFER_H
00026 #define PQEXPBUFFER_H
00027 
00028 /*-------------------------
00029  * PQExpBufferData holds information about an extensible string.
00030  *      data    is the current buffer for the string (allocated with malloc).
00031  *      len     is the current string length.  There is guaranteed to be
00032  *              a terminating '\0' at data[len], although this is not very
00033  *              useful when the string holds binary data rather than text.
00034  *      maxlen  is the allocated size in bytes of 'data', i.e. the maximum
00035  *              string size (including the terminating '\0' char) that we can
00036  *              currently store in 'data' without having to reallocate
00037  *              more space.  We must always have maxlen > len.
00038  *
00039  * An exception occurs if we failed to allocate enough memory for the string
00040  * buffer.  In that case data points to a statically allocated empty string,
00041  * and len = maxlen = 0.
00042  *-------------------------
00043  */
00044 typedef struct PQExpBufferData
00045 {
00046     char       *data;
00047     size_t      len;
00048     size_t      maxlen;
00049 } PQExpBufferData;
00050 
00051 typedef PQExpBufferData *PQExpBuffer;
00052 
00053 /*------------------------
00054  * Test for a broken (out of memory) PQExpBuffer.
00055  * When a buffer is "broken", all operations except resetting or deleting it
00056  * are no-ops.
00057  *------------------------
00058  */
00059 #define PQExpBufferBroken(str)  \
00060     ((str) == NULL || (str)->maxlen == 0)
00061 
00062 /*------------------------
00063  * Same, but for use when using a static or local PQExpBufferData struct.
00064  * For that, a null-pointer test is useless and may draw compiler warnings.
00065  *------------------------
00066  */
00067 #define PQExpBufferDataBroken(buf)  \
00068     ((buf).maxlen == 0)
00069 
00070 /*------------------------
00071  * Initial size of the data buffer in a PQExpBuffer.
00072  * NB: this must be large enough to hold error messages that might
00073  * be returned by PQrequestCancel().
00074  *------------------------
00075  */
00076 #define INITIAL_EXPBUFFER_SIZE  256
00077 
00078 /*------------------------
00079  * There are two ways to create a PQExpBuffer object initially:
00080  *
00081  * PQExpBuffer stringptr = createPQExpBuffer();
00082  *      Both the PQExpBufferData and the data buffer are malloc'd.
00083  *
00084  * PQExpBufferData string;
00085  * initPQExpBuffer(&string);
00086  *      The data buffer is malloc'd but the PQExpBufferData is presupplied.
00087  *      This is appropriate if the PQExpBufferData is a field of another
00088  *      struct.
00089  *-------------------------
00090  */
00091 
00092 /*------------------------
00093  * createPQExpBuffer
00094  * Create an empty 'PQExpBufferData' & return a pointer to it.
00095  */
00096 extern PQExpBuffer createPQExpBuffer(void);
00097 
00098 /*------------------------
00099  * initPQExpBuffer
00100  * Initialize a PQExpBufferData struct (with previously undefined contents)
00101  * to describe an empty string.
00102  */
00103 extern void initPQExpBuffer(PQExpBuffer str);
00104 
00105 /*------------------------
00106  * To destroy a PQExpBuffer, use either:
00107  *
00108  * destroyPQExpBuffer(str);
00109  *      free()s both the data buffer and the PQExpBufferData.
00110  *      This is the inverse of createPQExpBuffer().
00111  *
00112  * termPQExpBuffer(str)
00113  *      free()s the data buffer but not the PQExpBufferData itself.
00114  *      This is the inverse of initPQExpBuffer().
00115  *
00116  * NOTE: some routines build up a string using PQExpBuffer, and then
00117  * release the PQExpBufferData but return the data string itself to their
00118  * caller.  At that point the data string looks like a plain malloc'd
00119  * string.
00120  */
00121 extern void destroyPQExpBuffer(PQExpBuffer str);
00122 extern void termPQExpBuffer(PQExpBuffer str);
00123 
00124 /*------------------------
00125  * resetPQExpBuffer
00126  *      Reset a PQExpBuffer to empty
00127  *
00128  * Note: if possible, a "broken" PQExpBuffer is returned to normal.
00129  */
00130 extern void resetPQExpBuffer(PQExpBuffer str);
00131 
00132 /*------------------------
00133  * enlargePQExpBuffer
00134  * Make sure there is enough space for 'needed' more bytes in the buffer
00135  * ('needed' does not include the terminating null).
00136  *
00137  * Returns 1 if OK, 0 if failed to enlarge buffer.  (In the latter case
00138  * the buffer is left in "broken" state.)
00139  */
00140 extern int  enlargePQExpBuffer(PQExpBuffer str, size_t needed);
00141 
00142 /*------------------------
00143  * printfPQExpBuffer
00144  * Format text data under the control of fmt (an sprintf-like format string)
00145  * and insert it into str.  More space is allocated to str if necessary.
00146  * This is a convenience routine that does the same thing as
00147  * resetPQExpBuffer() followed by appendPQExpBuffer().
00148  */
00149 extern void
00150 printfPQExpBuffer(PQExpBuffer str, const char *fmt,...)
00151 /* This extension allows gcc to check the format string */
00152 __attribute__((format(PG_PRINTF_ATTRIBUTE, 2, 3)));
00153 
00154 /*------------------------
00155  * appendPQExpBuffer
00156  * Format text data under the control of fmt (an sprintf-like format string)
00157  * and append it to whatever is already in str.  More space is allocated
00158  * to str if necessary.  This is sort of like a combination of sprintf and
00159  * strcat.
00160  */
00161 extern void
00162 appendPQExpBuffer(PQExpBuffer str, const char *fmt,...)
00163 /* This extension allows gcc to check the format string */
00164 __attribute__((format(PG_PRINTF_ATTRIBUTE, 2, 3)));
00165 
00166 /*------------------------
00167  * appendPQExpBufferStr
00168  * Append the given string to a PQExpBuffer, allocating more space
00169  * if necessary.
00170  */
00171 extern void appendPQExpBufferStr(PQExpBuffer str, const char *data);
00172 
00173 /*------------------------
00174  * appendPQExpBufferChar
00175  * Append a single byte to str.
00176  * Like appendPQExpBuffer(str, "%c", ch) but much faster.
00177  */
00178 extern void appendPQExpBufferChar(PQExpBuffer str, char ch);
00179 
00180 /*------------------------
00181  * appendBinaryPQExpBuffer
00182  * Append arbitrary binary data to a PQExpBuffer, allocating more space
00183  * if necessary.
00184  */
00185 extern void appendBinaryPQExpBuffer(PQExpBuffer str,
00186                         const char *data, size_t datalen);
00187 
00188 #endif   /* PQEXPBUFFER_H */