granicus.if.org Git - postgresql/blob - src/interfaces/libpq/libpq-int.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * libpq-int.h
   4  *        This file contains internal definitions meant to be used only by
   5  *        the frontend libpq library, not by applications that call it.
   6  *
   7  *        An application can include this file if it wants to bypass the
   8  *        official API defined by libpq-fe.h, but code that does so is much
   9  *        more likely to break across PostgreSQL releases than code that uses
  10  *        only the official API.
  11  *
  12  * Copyright (c) 1994, Regents of the University of California
  13  *
  14  * $Id: libpq-int.h,v 1.7 1999/05/03 19:10:42 momjian Exp $
  15  *
  16  *-------------------------------------------------------------------------
  17  */
  18
  19 #ifndef LIBPQ_INT_H
  20 #define LIBPQ_INT_H
  21
  22 /* We assume libpq-fe.h has already been included. */
  23
  24 /* ----------------
  25  *              include stuff common to fe and be
  26  * ----------------
  27  */
  28 #include "libpq/pqcomm.h"
  29 #include "lib/dllist.h"
  30
  31 /* libpq supports this version of the frontend/backend protocol.
  32  *
  33  * NB: we used to use PG_PROTOCOL_LATEST from the backend pqcomm.h file,
  34  * but that's not really the right thing: just recompiling libpq
  35  * against a more recent backend isn't going to magically update it
  36  * for most sorts of protocol changes.  So, when you change libpq
  37  * to support a different protocol revision, you have to change this
  38  * constant too.  PG_PROTOCOL_EARLIEST and PG_PROTOCOL_LATEST in
  39  * pqcomm.h describe what the backend knows, not what libpq knows.
  40  */
  41
  42 #define PG_PROTOCOL_LIBPQ       PG_PROTOCOL(2,0)
  43
  44 /*
  45  * POSTGRES backend dependent Constants.
  46  */
  47
  48 /* ERROR_MSG_LENGTH should really be the same as ELOG_MAXLEN in utils/elog.h*/
  49 #define ERROR_MSG_LENGTH 4096
  50 #define CMDSTATUS_LEN 40
  51
  52 /*
  53  * PGresult and the subsidiary types PGresAttDesc, PGresAttValue
  54  * represent the result of a query (or more precisely, of a single SQL
  55  * command --- a query string given to PQexec can contain multiple commands).
  56  * Note we assume that a single command can return at most one tuple group,
  57  * hence there is no need for multiple descriptor sets.
  58  */
  59
  60 /* Subsidiary-storage management structure for PGresult.
  61  * See space management routines in fe-exec.c for details.
  62  * Note that space[k] refers to the k'th byte starting from the physical
  63  * head of the block.
  64  */
  65         typedef union pgresult_data PGresult_data;
  66
  67         union pgresult_data
  68         {
  69                 PGresult_data  *next;   /* link to next block, or NULL */
  70                 char                    space[1]; /* dummy for accessing block as bytes */
  71         };
  72
  73 /* Data about a single attribute (column) of a query result */
  74
  75         typedef struct pgresAttDesc
  76         {
  77                 char       *name;               /* type name */
  78                 Oid                     typid;          /* type id */
  79                 int                     typlen;         /* type size */
  80                 int                     atttypmod;      /* type-specific modifier info */
  81         } PGresAttDesc;
  82
  83 /* Data for a single attribute of a single tuple */
  84
  85 /* We use char* for Attribute values.
  86    The value pointer always points to a null-terminated area; we add a
  87    null (zero) byte after whatever the backend sends us.  This is only
  88    particularly useful for ASCII tuples ... with a binary value, the
  89    value might have embedded nulls, so the application can't use C string
  90    operators on it.  But we add a null anyway for consistency.
  91    Note that the value itself does not contain a length word.
  92
  93    A NULL attribute is a special case in two ways: its len field is NULL_LEN
  94    and its value field points to null_field in the owning PGresult.  All the
  95    NULL attributes in a query result point to the same place (there's no need
  96    to store a null string separately for each one).
  97  */
  98
  99 #define NULL_LEN                (-1)    /* pg_result len for NULL value */
 100
 101         typedef struct pgresAttValue
 102         {
 103                 int                     len;            /* length in bytes of the value */
 104                 char       *value;              /* actual value, plus terminating zero byte */
 105         } PGresAttValue;
 106
 107         struct pg_result
 108         {
 109                 int                     ntups;
 110                 int                     numAttributes;
 111                 PGresAttDesc *attDescs;
 112                 PGresAttValue **tuples; /* each PGresTuple is an array of
 113                                                                  * PGresAttValue's */
 114                 int                     tupArrSize; /* size of tuples array allocated */
 115                 ExecStatusType resultStatus;
 116                 char            cmdStatus[CMDSTATUS_LEN];       /* cmd status from the
 117                                                                                                  * last insert query */
 118                 int                     binary;         /* binary tuple values if binary == 1,
 119                                                                  * otherwise ASCII */
 120                 PGconn          *conn;          /* connection we did the query on, if any */
 121                 char            *errMsg;        /* error message, or NULL if no error */
 122
 123                 /* All NULL attributes in the query result point to this null string */
 124                 char            null_field[1];
 125
 126                 /* Space management information.  Note that attDescs and errMsg,
 127                  * if not null, point into allocated blocks.  But tuples points
 128                  * to a separately malloc'd block, so that we can realloc it.
 129                  */
 130                 PGresult_data *curBlock; /* most recently allocated block */
 131                 int                     curOffset;      /* start offset of free space in block */
 132                 int                     spaceLeft;      /* number of free bytes remaining in block */
 133         };
 134
 135 /* PGAsyncStatusType defines the state of the query-execution state machine */
 136         typedef enum
 137         {
 138                 PGASYNC_IDLE,                   /* nothing's happening, dude */
 139                 PGASYNC_BUSY,                   /* query in progress */
 140                 PGASYNC_READY,                  /* result ready for PQgetResult */
 141                 PGASYNC_COPY_IN,                /* Copy In data transfer in progress */
 142                 PGASYNC_COPY_OUT                /* Copy Out data transfer in progress */
 143         } PGAsyncStatusType;
 144
 145 /* large-object-access data ... allocated only if large-object code is used. */
 146         typedef struct pgLobjfuncs
 147         {
 148                 Oid                     fn_lo_open; /* OID of backend function lo_open          */
 149                 Oid                     fn_lo_close;/* OID of backend function lo_close         */
 150                 Oid                     fn_lo_creat;/* OID of backend function lo_creat         */
 151                 Oid                     fn_lo_unlink;           /* OID of backend function
 152                                                                                  * lo_unlink    */
 153                 Oid                     fn_lo_lseek;/* OID of backend function lo_lseek         */
 154                 Oid                     fn_lo_tell; /* OID of backend function lo_tell          */
 155                 Oid                     fn_lo_read; /* OID of backend function LOread           */
 156                 Oid                     fn_lo_write;/* OID of backend function LOwrite          */
 157         } PGlobjfuncs;
 158
 159 /* PGconn stores all the state data associated with a single connection
 160  * to a backend.
 161  */
 162         struct pg_conn
 163         {
 164                 /* Saved values of connection options */
 165                 char       *pghost;             /* the machine on which the server is
 166                                                                  * running */
 167                 char       *pgport;             /* the server's communication port */
 168                 char       *pgtty;              /* tty on which the backend messages is
 169                                                                  * displayed (NOT ACTUALLY USED???) */
 170                 char       *pgoptions;  /* options to start the backend with */
 171                 char       *dbName;             /* database name */
 172                 char       *pguser;             /* Postgres username and password, if any */
 173                 char       *pgpass;
 174
 175                 /* Optional file to write trace info to */
 176                 FILE       *Pfdebug;
 177
 178                 /* Callback procedure for notice/error message processing */
 179                 PQnoticeProcessor       noticeHook;
 180                 void       *noticeArg;
 181
 182                 /* Status indicators */
 183                 ConnStatusType          status;
 184                 PGAsyncStatusType       asyncStatus;
 185                 Dllist     *notifyList; /* Notify msgs not yet handed to application */
 186
 187                 /* Connection data */
 188                 int                     sock;           /* Unix FD for socket, -1 if not connected */
 189                 SockAddr        laddr;          /* Local address */
 190                 SockAddr        raddr;          /* Remote address */
 191                 int                     raddr_len;      /* Length of remote address */
 192
 193                 /* Miscellaneous stuff */
 194                 int                     be_pid;         /* PID of backend --- needed for cancels */
 195                 int                     be_key;         /* key of backend --- needed for cancels */
 196                 char            salt[2];        /* password salt received from backend */
 197                 PGlobjfuncs *lobjfuncs; /* private state for large-object access fns */
 198
 199                 /* Buffer for data received from backend and not yet processed */
 200                 char            *inBuffer;      /* currently allocated buffer */
 201                 int                     inBufSize;      /* allocated size of buffer */
 202                 int                     inStart;        /* offset to first unconsumed data in buffer */
 203                 int                     inCursor;       /* next byte to tentatively consume */
 204                 int                     inEnd;          /* offset to first position after avail data */
 205
 206                 /* Buffer for data not yet sent to backend */
 207                 char            *outBuffer;     /* currently allocated buffer */
 208                 int                     outBufSize;     /* allocated size of buffer */
 209                 int                     outCount;       /* number of chars waiting in buffer */
 210
 211                 /* Status for asynchronous result construction */
 212                 PGresult                *result;        /* result being constructed */
 213                 PGresAttValue   *curTuple;      /* tuple currently being read */
 214
 215                 /* Message space.  Placed last for code-size reasons. */
 216                 char            errorMessage[ERROR_MSG_LENGTH];
 217         };
 218
 219 /* ----------------
 220  * Internal functions of libpq
 221  * Functions declared here need to be visible across files of libpq,
 222  * but are not intended to be called by applications.  We use the
 223  * convention "pqXXX" for internal functions, vs. the "PQxxx" names
 224  * used for application-visible routines.
 225  * ----------------
 226  */
 227
 228 /* === in fe-connect.c === */
 229
 230 extern int      pqPacketSend(PGconn *conn, const char *buf, size_t len);
 231
 232 /* === in fe-exec.c === */
 233
 234 extern void pqSetResultError(PGresult *res, const char *msg);
 235 extern void * pqResultAlloc(PGresult *res, int nBytes, int isBinary);
 236 extern char * pqResultStrdup(PGresult *res, const char *str);
 237 extern void pqClearAsyncResult(PGconn *conn);
 238
 239 /* === in fe-misc.c === */
 240
 241  /*
 242   * "Get" and "Put" routines return 0 if successful, EOF if not. Note that
 243   * for Get, EOF merely means the buffer is exhausted, not that there is
 244   * necessarily any error.
 245   */
 246 extern int      pqGetc(char *result, PGconn *conn);
 247 extern int      pqGets(char *s, int maxlen, PGconn *conn);
 248 extern int      pqPuts(const char *s, PGconn *conn);
 249 extern int      pqGetnchar(char *s, int len, PGconn *conn);
 250 extern int      pqPutnchar(const char *s, int len, PGconn *conn);
 251 extern int      pqGetInt(int *result, int bytes, PGconn *conn);
 252 extern int      pqPutInt(int value, int bytes, PGconn *conn);
 253 extern int      pqReadData(PGconn *conn);
 254 extern int      pqFlush(PGconn *conn);
 255 extern int      pqWait(int forRead, int forWrite, PGconn *conn);
 256
 257 /* max length of message to send  */
 258 #define MAX_MESSAGE_LEN MAX_QUERY_SIZE
 259
 260 /* maximum number of fields in a tuple */
 261 #define MAX_FIELDS 512
 262
 263 /* bits in a byte */
 264 #define BYTELEN 8
 265
 266 /* fall back options if they are not specified by arguments or defined
 267    by environment variables */
 268 #define DefaultHost             "localhost"
 269 #define DefaultTty              ""
 270 #define DefaultOption   ""
 271 #define DefaultAuthtype           ""
 272 #define DefaultPassword           ""
 273
 274 /* supply an implementation of strerror() macro if system doesn't have it */
 275 #ifndef strerror
 276 #if defined(sun) && defined(sparc) && !defined(__SVR4)
 277 extern char *sys_errlist[];
 278
 279 #define strerror(A) (sys_errlist[(A)])
 280 #endif   /* sunos4 */
 281 #endif   /* !strerror */
 282
 283 #endif   /* LIBPQ_INT_H */