libpq-int.h 10.8 KB
Newer Older
1 2
/*-------------------------------------------------------------------------
 *
3
 * libpq-int.h
4 5 6
 *	  This file contains internal definitions meant to be used only by
 *	  the frontend libpq library, not by applications that call it.
 *
7 8 9 10 11
 *	  An application can include this file if it wants to bypass the
 *	  official API defined by libpq-fe.h, but code that does so is much
 *	  more likely to break across PostgreSQL releases than code that uses
 *	  only the official API.
 *
12 13
 * Copyright (c) 1994, Regents of the University of California
 *
14
 * $Id: libpq-int.h,v 1.17 2000/01/18 06:09:24 momjian Exp $
15 16 17 18 19 20 21 22 23
 *
 *-------------------------------------------------------------------------
 */

#ifndef LIBPQ_INT_H
#define LIBPQ_INT_H

/* We assume libpq-fe.h has already been included. */

24
/* include stuff common to fe and be */
25
#include "libpq/pqcomm.h"
26
#include "lib/dllist.h"
27 28 29
/* include stuff found in fe only */
#include "pqexpbuffer.h"

30
#ifdef USE_SSL
31 32
#include <openssl/ssl.h>
#include <openssl/err.h>
33 34
#endif

35 36 37 38 39
/* libpq supports this version of the frontend/backend protocol.
 *
 * NB: we used to use PG_PROTOCOL_LATEST from the backend pqcomm.h file,
 * but that's not really the right thing: just recompiling libpq
 * against a more recent backend isn't going to magically update it
40
 * for most sorts of protocol changes.	So, when you change libpq
41 42 43 44 45 46 47
 * to support a different protocol revision, you have to change this
 * constant too.  PG_PROTOCOL_EARLIEST and PG_PROTOCOL_LATEST in
 * pqcomm.h describe what the backend knows, not what libpq knows.
 */

#define PG_PROTOCOL_LIBPQ	PG_PROTOCOL(2,0)

48 49 50 51 52 53
/*
 * POSTGRES backend dependent Constants.
 */

#define CMDSTATUS_LEN 40

54 55
/*
 * PGresult and the subsidiary types PGresAttDesc, PGresAttValue
56 57 58 59 60
 * represent the result of a query (or more precisely, of a single SQL
 * command --- a query string given to PQexec can contain multiple commands).
 * Note we assume that a single command can return at most one tuple group,
 * hence there is no need for multiple descriptor sets.
 */
61 62 63 64

/* Subsidiary-storage management structure for PGresult.
 * See space management routines in fe-exec.c for details.
 * Note that space[k] refers to the k'th byte starting from the physical
65
 * head of the block --- it's a union, not a struct!
66
 */
Bruce Momjian's avatar
Bruce Momjian committed
67
typedef union pgresult_data PGresult_data;
68

Bruce Momjian's avatar
Bruce Momjian committed
69 70 71 72 73
union pgresult_data
{
	PGresult_data *next;		/* link to next block, or NULL */
	char		space[1];		/* dummy for accessing block as bytes */
};
74 75 76

/* Data about a single attribute (column) of a query result */

Bruce Momjian's avatar
Bruce Momjian committed
77 78 79 80 81 82 83
typedef struct pgresAttDesc
{
	char	   *name;			/* type name */
	Oid			typid;			/* type id */
	int			typlen;			/* type size */
	int			atttypmod;		/* type-specific modifier info */
} PGresAttDesc;
84

85 86 87 88 89 90 91 92 93 94 95 96 97 98
/* Data for a single attribute of a single tuple */

/* We use char* for Attribute values.
   The value pointer always points to a null-terminated area; we add a
   null (zero) byte after whatever the backend sends us.  This is only
   particularly useful for ASCII tuples ... with a binary value, the
   value might have embedded nulls, so the application can't use C string
   operators on it.  But we add a null anyway for consistency.
   Note that the value itself does not contain a length word.

   A NULL attribute is a special case in two ways: its len field is NULL_LEN
   and its value field points to null_field in the owning PGresult.  All the
   NULL attributes in a query result point to the same place (there's no need
   to store a null string separately for each one).
99 100 101 102
 */

#define NULL_LEN		(-1)	/* pg_result len for NULL value */

Bruce Momjian's avatar
Bruce Momjian committed
103 104 105 106 107 108 109 110 111 112 113 114 115
typedef struct pgresAttValue
{
	int			len;			/* length in bytes of the value */
	char	   *value;			/* actual value, plus terminating zero
								 * byte */
} PGresAttValue;

struct pg_result
{
	int			ntups;
	int			numAttributes;
	PGresAttDesc *attDescs;
	PGresAttValue **tuples;		/* each PGresTuple is an array of
116
								 * PGresAttValue's */
Bruce Momjian's avatar
Bruce Momjian committed
117 118 119
	int			tupArrSize;		/* size of tuples array allocated */
	ExecStatusType resultStatus;
	char		cmdStatus[CMDSTATUS_LEN];		/* cmd status from the
120
												 * last query */
Bruce Momjian's avatar
Bruce Momjian committed
121
	int			binary;			/* binary tuple values if binary == 1,
122
								 * otherwise ASCII */
Bruce Momjian's avatar
Bruce Momjian committed
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
	PGconn	   *conn;			/* connection we did the query on, if any */
	char	   *errMsg;			/* error message, or NULL if no error */

	/* All NULL attributes in the query result point to this null string */
	char		null_field[1];

	/*
	 * Space management information.  Note that attDescs and errMsg, if
	 * not null, point into allocated blocks.  But tuples points to a
	 * separately malloc'd block, so that we can realloc it.
	 */
	PGresult_data *curBlock;	/* most recently allocated block */
	int			curOffset;		/* start offset of free space in block */
	int			spaceLeft;		/* number of free bytes remaining in block */
};
138 139

/* PGAsyncStatusType defines the state of the query-execution state machine */
Bruce Momjian's avatar
Bruce Momjian committed
140 141 142 143 144 145 146
typedef enum
{
	PGASYNC_IDLE,				/* nothing's happening, dude */
	PGASYNC_BUSY,				/* query in progress */
	PGASYNC_READY,				/* result ready for PQgetResult */
	PGASYNC_COPY_IN,			/* Copy In data transfer in progress */
	PGASYNC_COPY_OUT			/* Copy Out data transfer in progress */
147
} PGAsyncStatusType;
148 149

/* large-object-access data ... allocated only if large-object code is used. */
Bruce Momjian's avatar
Bruce Momjian committed
150 151 152 153 154 155 156 157 158 159 160
typedef struct pgLobjfuncs
{
	Oid			fn_lo_open;		/* OID of backend function lo_open		*/
	Oid			fn_lo_close;	/* OID of backend function lo_close		*/
	Oid			fn_lo_creat;	/* OID of backend function lo_creat		*/
	Oid			fn_lo_unlink;	/* OID of backend function lo_unlink	*/
	Oid			fn_lo_lseek;	/* OID of backend function lo_lseek		*/
	Oid			fn_lo_tell;		/* OID of backend function lo_tell		*/
	Oid			fn_lo_read;		/* OID of backend function LOread		*/
	Oid			fn_lo_write;	/* OID of backend function LOwrite		*/
} PGlobjfuncs;
161 162 163 164

/* PGconn stores all the state data associated with a single connection
 * to a backend.
 */
Bruce Momjian's avatar
Bruce Momjian committed
165 166 167 168
struct pg_conn
{
	/* Saved values of connection options */
	char	   *pghost;			/* the machine on which the server is
169
								 * running */
170 171 172 173
	char	   *pghostaddr;		/* the IPv4 address of the machine on
								 * which the server is running, in
								 * IPv4 numbers-and-dots notation. Takes
								 * precedence over above. */
Bruce Momjian's avatar
Bruce Momjian committed
174 175
	char	   *pgport;			/* the server's communication port */
	char	   *pgtty;			/* tty on which the backend messages is
176
								 * displayed (NOT ACTUALLY USED???) */
Bruce Momjian's avatar
Bruce Momjian committed
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216
	char	   *pgoptions;		/* options to start the backend with */
	char	   *dbName;			/* database name */
	char	   *pguser;			/* Postgres username and password, if any */
	char	   *pgpass;

	/* Optional file to write trace info to */
	FILE	   *Pfdebug;

	/* Callback procedure for notice/error message processing */
	PQnoticeProcessor noticeHook;
	void	   *noticeArg;

	/* Status indicators */
	ConnStatusType status;
	PGAsyncStatusType asyncStatus;
	Dllist	   *notifyList;		/* Notify msgs not yet handed to
								 * application */

	/* Connection data */
	int			sock;			/* Unix FD for socket, -1 if not connected */
	SockAddr	laddr;			/* Local address */
	SockAddr	raddr;			/* Remote address */
	int			raddr_len;		/* Length of remote address */

	/* Miscellaneous stuff */
	int			be_pid;			/* PID of backend --- needed for cancels */
	int			be_key;			/* key of backend --- needed for cancels */
	char		salt[2];		/* password salt received from backend */
	PGlobjfuncs *lobjfuncs;		/* private state for large-object access
								 * fns */

	/* Buffer for data received from backend and not yet processed */
	char	   *inBuffer;		/* currently allocated buffer */
	int			inBufSize;		/* allocated size of buffer */
	int			inStart;		/* offset to first unconsumed data in
								 * buffer */
	int			inCursor;		/* next byte to tentatively consume */
	int			inEnd;			/* offset to first position after avail
								 * data */

217 218 219
	int			nonblocking;	/* whether this connection is using a blocking
								 * socket to the backend or not */

Bruce Momjian's avatar
Bruce Momjian committed
220 221 222 223 224 225 226 227 228
	/* Buffer for data not yet sent to backend */
	char	   *outBuffer;		/* currently allocated buffer */
	int			outBufSize;		/* allocated size of buffer */
	int			outCount;		/* number of chars waiting in buffer */

	/* Status for asynchronous result construction */
	PGresult   *result;			/* result being constructed */
	PGresAttValue *curTuple;	/* tuple currently being read */

229 230 231
	/* Handle for setenv request.  Used during connection only. */
	PGsetenvHandle setenv_handle;

232
#ifdef USE_SSL
233 234
	bool allow_ssl_try;			/* Allowed to try SSL negotiation */
	SSL *ssl;					/* SSL status, if have SSL connection */
235 236
#endif

237 238 239 240 241
	/* Buffer for current error message */
	PQExpBufferData	errorMessage;	/* expansible string */

	/* Buffer for receiving various parts of messages */
	PQExpBufferData	workBuffer;	/* expansible string */
Tatsuo Ishii's avatar
Tatsuo Ishii committed
242 243

	int client_encoding;		/* encoding id */
Bruce Momjian's avatar
Bruce Momjian committed
244
};
245

246 247 248 249 250 251 252 253 254 255 256
/* ----------------
 * Internal functions of libpq
 * Functions declared here need to be visible across files of libpq,
 * but are not intended to be called by applications.  We use the
 * convention "pqXXX" for internal functions, vs. the "PQxxx" names
 * used for application-visible routines.
 * ----------------
 */

/* === in fe-connect.c === */

257
extern int	pqPacketSend(PGconn *conn, const char *buf, size_t len);
258 259 260

/* === in fe-exec.c === */

261
extern void pqSetResultError(PGresult *res, const char *msg);
Bruce Momjian's avatar
Bruce Momjian committed
262
extern void *pqResultAlloc(PGresult *res, size_t nBytes, bool isBinary);
Bruce Momjian's avatar
Bruce Momjian committed
263
extern char *pqResultStrdup(PGresult *res, const char *str);
264
extern void pqClearAsyncResult(PGconn *conn);
265 266 267

/* === in fe-misc.c === */

268 269 270 271 272 273
 /*
  * "Get" and "Put" routines return 0 if successful, EOF if not. Note that
  * for Get, EOF merely means the buffer is exhausted, not that there is
  * necessarily any error.
  */
extern int	pqGetc(char *result, PGconn *conn);
274
extern int	pqGets(PQExpBuffer buf, PGconn *conn);
275
extern int	pqPuts(const char *s, PGconn *conn);
Bruce Momjian's avatar
Bruce Momjian committed
276 277 278 279
extern int	pqGetnchar(char *s, size_t len, PGconn *conn);
extern int	pqPutnchar(const char *s, size_t len, PGconn *conn);
extern int	pqGetInt(int *result, size_t bytes, PGconn *conn);
extern int	pqPutInt(int value, size_t bytes, PGconn *conn);
280 281 282
extern int	pqReadData(PGconn *conn);
extern int	pqFlush(PGconn *conn);
extern int	pqWait(int forRead, int forWrite, PGconn *conn);
283 284
extern int	pqReadReady(PGconn *conn);
extern int	pqWriteReady(PGconn *conn);
285 286 287 288 289 290 291 292 293 294 295 296 297 298

/* bits in a byte */
#define BYTELEN 8

/* fall back options if they are not specified by arguments or defined
   by environment variables */
#define DefaultHost		"localhost"
#define DefaultTty		""
#define DefaultOption	""
#define DefaultAuthtype		  ""
#define DefaultPassword		  ""

/* supply an implementation of strerror() macro if system doesn't have it */
#ifndef strerror
299
#if defined(sun) && defined(__sparc__) && !defined(__SVR4)
300
extern char *sys_errlist[];
301

302
#define strerror(A) (sys_errlist[(A)])
303 304
#endif	 /* sunos4 */
#endif	 /* !strerror */
305

306 307 308 309 310 311
/* 
 * this is so that we can check is a connection is non-blocking internally
 * without the overhead of a function call
 */
#define pqIsnonblocking(conn)	(conn->nonblocking)

312
#endif	 /* LIBPQ_INT_H */