Eneboo - Documentación para desarrolladores
src/libpq/pqexpbuffer.h
Ir a la documentación de este archivo.
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-2005, PostgreSQL Global Development Group
00019  * Portions Copyright (c) 1994, Regents of the University of California
00020  *
00021  * $PostgreSQL: pgsql/src/interfaces/libpq/pqexpbuffer.h,v 1.15 2004/12/31 22:03:50 pgsql Exp $
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  */
00040 typedef struct PQExpBufferData
00041 {
00042         char       *data;
00043         size_t          len;
00044         size_t          maxlen;
00045 } PQExpBufferData;
00046 
00047 typedef PQExpBufferData *PQExpBuffer;
00048 
00049 /*------------------------
00050  * Initial size of the data buffer in a PQExpBuffer.
00051  * NB: this must be large enough to hold error messages that might
00052  * be returned by PQrequestCancel() or any routine in fe-auth.c.
00053  *------------------------
00054  */
00055 #define INITIAL_EXPBUFFER_SIZE  256
00056 
00057 /*------------------------
00058  * There are two ways to create a PQExpBuffer object initially:
00059  *
00060  * PQExpBuffer stringptr = createPQExpBuffer();
00061  *              Both the PQExpBufferData and the data buffer are malloc'd.
00062  *
00063  * PQExpBufferData string;
00064  * initPQExpBuffer(&string);
00065  *              The data buffer is malloc'd but the PQExpBufferData is presupplied.
00066  *              This is appropriate if the PQExpBufferData is a field of another
00067  *              struct.
00068  *-------------------------
00069  */
00070 
00071 /*------------------------
00072  * createPQExpBuffer
00073  * Create an empty 'PQExpBufferData' & return a pointer to it.
00074  */
00075 extern PQExpBuffer createPQExpBuffer(void);
00076 
00077 /*------------------------
00078  * initPQExpBuffer
00079  * Initialize a PQExpBufferData struct (with previously undefined contents)
00080  * to describe an empty string.
00081  */
00082 extern void initPQExpBuffer(PQExpBuffer str);
00083 
00084 /*------------------------
00085  * To destroy a PQExpBuffer, use either:
00086  *
00087  * destroyPQExpBuffer(str);
00088  *              free()s both the data buffer and the PQExpBufferData.
00089  *              This is the inverse of createPQExpBuffer().
00090  *
00091  * termPQExpBuffer(str)
00092  *              free()s the data buffer but not the PQExpBufferData itself.
00093  *              This is the inverse of initPQExpBuffer().
00094  *
00095  * NOTE: some routines build up a string using PQExpBuffer, and then
00096  * release the PQExpBufferData but return the data string itself to their
00097  * caller.      At that point the data string looks like a plain malloc'd
00098  * string.
00099  */
00100 extern void destroyPQExpBuffer(PQExpBuffer str);
00101 extern void termPQExpBuffer(PQExpBuffer str);
00102 
00103 /*------------------------
00104  * resetPQExpBuffer
00105  *              Reset a PQExpBuffer to empty
00106  */
00107 extern void resetPQExpBuffer(PQExpBuffer str);
00108 
00109 /*------------------------
00110  * enlargePQExpBuffer
00111  * Make sure there is enough space for 'needed' more bytes in the buffer
00112  * ('needed' does not include the terminating null).
00113  *
00114  * Returns 1 if OK, 0 if failed to enlarge buffer.
00115  */
00116 extern int      enlargePQExpBuffer(PQExpBuffer str, size_t needed);
00117 
00118 /*------------------------
00119  * printfPQExpBuffer
00120  * Format text data under the control of fmt (an sprintf-like format string)
00121  * and insert it into str.      More space is allocated to str if necessary.
00122  * This is a convenience routine that does the same thing as
00123  * resetPQExpBuffer() followed by appendPQExpBuffer().
00124  */
00125 extern void
00126 printfPQExpBuffer(PQExpBuffer str, const char *fmt,...)
00127 /* This extension allows gcc to check the format string */
00128 __attribute__((format(printf, 2, 3)));
00129 
00130 /*------------------------
00131  * appendPQExpBuffer
00132  * Format text data under the control of fmt (an sprintf-like format string)
00133  * and append it to whatever is already in str.  More space is allocated
00134  * to str if necessary.  This is sort of like a combination of sprintf and
00135  * strcat.
00136  */
00137 extern void
00138 appendPQExpBuffer(PQExpBuffer str, const char *fmt,...)
00139 /* This extension allows gcc to check the format string */
00140 __attribute__((format(printf, 2, 3)));
00141 
00142 /*------------------------
00143  * appendPQExpBufferStr
00144  * Append the given string to a PQExpBuffer, allocating more space
00145  * if necessary.
00146  */
00147 extern void appendPQExpBufferStr(PQExpBuffer str, const char *data);
00148 
00149 /*------------------------
00150  * appendPQExpBufferChar
00151  * Append a single byte to str.
00152  * Like appendPQExpBuffer(str, "%c", ch) but much faster.
00153  */
00154 extern void appendPQExpBufferChar(PQExpBuffer str, char ch);
00155 
00156 /*------------------------
00157  * appendBinaryPQExpBuffer
00158  * Append arbitrary binary data to a PQExpBuffer, allocating more space
00159  * if necessary.
00160  */
00161 extern void appendBinaryPQExpBuffer(PQExpBuffer str,
00162                                                 const char *data, size_t datalen);
00163 
00164 #endif   /* PQEXPBUFFER_H */
 Todo Clases Namespaces Archivos Funciones Variables 'typedefs' Enumeraciones Valores de enumeraciones Propiedades Amigas 'defines'