| 1 |
/*------------------------------------------------------------------------- |
| 2 |
* |
| 3 |
* libpq-fe.h |
| 4 |
* This file contains definitions for structures and |
| 5 |
* externs for functions used by frontend postgres applications. |
| 6 |
* |
| 7 |
* Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group |
| 8 |
* Portions Copyright (c) 1994, Regents of the University of California |
| 9 |
* |
| 10 |
* src/interfaces/libpq/libpq-fe.h |
| 11 |
* |
| 12 |
*------------------------------------------------------------------------- |
| 13 |
*/ |
| 14 |
|
| 15 |
#ifndef LIBPQ_FE_H |
| 16 |
#define LIBPQ_FE_H |
| 17 |
|
| 18 |
#ifdef __cplusplus |
| 19 |
extern "C" |
| 20 |
{ |
| 21 |
#endif |
| 22 |
|
| 23 |
#include <stdint.h> |
| 24 |
#include <stdio.h> |
| 25 |
|
| 26 |
/* |
| 27 |
* postgres_ext.h defines the backend's externally visible types, |
| 28 |
* such as Oid. |
| 29 |
*/ |
| 30 |
#include "postgres_ext.h" |
| 31 |
|
| 32 |
/* |
| 33 |
* These symbols may be used in compile-time #ifdef tests for the availability |
| 34 |
* of v14-and-newer libpq features. |
| 35 |
*/ |
| 36 |
/* Features added in PostgreSQL v14: */ |
| 37 |
/* Indicates presence of PQenterPipelineMode and friends */ |
| 38 |
#define LIBPQ_HAS_PIPELINING 1 |
| 39 |
/* Indicates presence of PQsetTraceFlags; also new PQtrace output format */ |
| 40 |
#define LIBPQ_HAS_TRACE_FLAGS 1 |
| 41 |
|
| 42 |
/* Features added in PostgreSQL v15: */ |
| 43 |
/* Indicates that PQsslAttribute(NULL, "library") is useful */ |
| 44 |
#define LIBPQ_HAS_SSL_LIBRARY_DETECTION 1 |
| 45 |
|
| 46 |
/* Features added in PostgreSQL v17: */ |
| 47 |
/* Indicates presence of PGcancelConn typedef and associated routines */ |
| 48 |
#define LIBPQ_HAS_ASYNC_CANCEL 1 |
| 49 |
/* Indicates presence of PQchangePassword */ |
| 50 |
#define LIBPQ_HAS_CHANGE_PASSWORD 1 |
| 51 |
/* Indicates presence of PQsetChunkedRowsMode, PGRES_TUPLES_CHUNK */ |
| 52 |
#define LIBPQ_HAS_CHUNK_MODE 1 |
| 53 |
/* Indicates presence of PQclosePrepared, PQclosePortal, etc */ |
| 54 |
#define LIBPQ_HAS_CLOSE_PREPARED 1 |
| 55 |
/* Indicates presence of PQsendPipelineSync */ |
| 56 |
#define LIBPQ_HAS_SEND_PIPELINE_SYNC 1 |
| 57 |
/* Indicates presence of PQsocketPoll, PQgetCurrentTimeUSec */ |
| 58 |
#define LIBPQ_HAS_SOCKET_POLL 1 |
| 59 |
|
| 60 |
/* Features added in PostgreSQL v18: */ |
| 61 |
/* Indicates presence of PQfullProtocolVersion */ |
| 62 |
#define LIBPQ_HAS_FULL_PROTOCOL_VERSION 1 |
| 63 |
/* Indicates presence of the PQAUTHDATA_PROMPT_OAUTH_DEVICE authdata hook */ |
| 64 |
#define LIBPQ_HAS_PROMPT_OAUTH_DEVICE 1 |
| 65 |
|
| 66 |
/* |
| 67 |
* Option flags for PQcopyResult |
| 68 |
*/ |
| 69 |
#define PG_COPYRES_ATTRS 0x01 |
| 70 |
#define PG_COPYRES_TUPLES 0x02 /* Implies PG_COPYRES_ATTRS */ |
| 71 |
#define PG_COPYRES_EVENTS 0x04 |
| 72 |
#define PG_COPYRES_NOTICEHOOKS 0x08 |
| 73 |
|
| 74 |
/* Application-visible enum types */ |
| 75 |
|
| 76 |
/* |
| 77 |
* Although it is okay to add to these lists, values which become unused |
| 78 |
* should never be removed, nor should constants be redefined - that would |
| 79 |
* break compatibility with existing code. |
| 80 |
*/ |
| 81 |
|
| 82 |
typedef enum |
| 83 |
{ |
| 84 |
CONNECTION_OK, |
| 85 |
CONNECTION_BAD, |
| 86 |
/* Non-blocking mode only below here */ |
| 87 |
|
| 88 |
/* |
| 89 |
* The existence of these should never be relied upon - they should only |
| 90 |
* be used for user feedback or similar purposes. |
| 91 |
*/ |
| 92 |
CONNECTION_STARTED, /* Waiting for connection to be made. */ |
| 93 |
CONNECTION_MADE, /* Connection OK; waiting to send. */ |
| 94 |
CONNECTION_AWAITING_RESPONSE, /* Waiting for a response from the |
| 95 |
* postmaster. */ |
| 96 |
CONNECTION_AUTH_OK, /* Received authentication; waiting for |
| 97 |
* backend startup. */ |
| 98 |
CONNECTION_SETENV, /* This state is no longer used. */ |
| 99 |
CONNECTION_SSL_STARTUP, /* Performing SSL handshake. */ |
| 100 |
CONNECTION_NEEDED, /* Internal state: connect() needed. */ |
| 101 |
CONNECTION_CHECK_WRITABLE, /* Checking if session is read-write. */ |
| 102 |
CONNECTION_CONSUME, /* Consuming any extra messages. */ |
| 103 |
CONNECTION_GSS_STARTUP, /* Negotiating GSSAPI. */ |
| 104 |
CONNECTION_CHECK_TARGET, /* Internal state: checking target server |
| 105 |
* properties. */ |
| 106 |
CONNECTION_CHECK_STANDBY, /* Checking if server is in standby mode. */ |
| 107 |
CONNECTION_ALLOCATED, /* Waiting for connection attempt to be |
| 108 |
* started. */ |
| 109 |
CONNECTION_AUTHENTICATING, /* Authentication is in progress with some |
| 110 |
* external system. */ |
| 111 |
} ConnStatusType; |
| 112 |
|
| 113 |
typedef enum |
| 114 |
{ |
| 115 |
PGRES_POLLING_FAILED = 0, |
| 116 |
PGRES_POLLING_READING, /* These two indicate that one may */ |
| 117 |
PGRES_POLLING_WRITING, /* use select before polling again. */ |
| 118 |
PGRES_POLLING_OK, |
| 119 |
PGRES_POLLING_ACTIVE /* unused; keep for backwards compatibility */ |
| 120 |
} PostgresPollingStatusType; |
| 121 |
|
| 122 |
typedef enum |
| 123 |
{ |
| 124 |
PGRES_EMPTY_QUERY = 0, /* empty query string was executed */ |
| 125 |
PGRES_COMMAND_OK, /* a query command that doesn't return |
| 126 |
* anything was executed properly by the |
| 127 |
* backend */ |
| 128 |
PGRES_TUPLES_OK, /* a query command that returns tuples was |
| 129 |
* executed properly by the backend, PGresult |
| 130 |
* contains the result tuples */ |
| 131 |
PGRES_COPY_OUT, /* Copy Out data transfer in progress */ |
| 132 |
PGRES_COPY_IN, /* Copy In data transfer in progress */ |
| 133 |
PGRES_BAD_RESPONSE, /* an unexpected response was recv'd from the |
| 134 |
* backend */ |
| 135 |
PGRES_NONFATAL_ERROR, /* notice or warning message */ |
| 136 |
PGRES_FATAL_ERROR, /* query failed */ |
| 137 |
PGRES_COPY_BOTH, /* Copy In/Out data transfer in progress */ |
| 138 |
PGRES_SINGLE_TUPLE, /* single tuple from larger resultset */ |
| 139 |
PGRES_PIPELINE_SYNC, /* pipeline synchronization point */ |
| 140 |
PGRES_PIPELINE_ABORTED, /* Command didn't run because of an abort |
| 141 |
* earlier in a pipeline */ |
| 142 |
PGRES_TUPLES_CHUNK /* chunk of tuples from larger resultset */ |
| 143 |
} ExecStatusType; |
| 144 |
|
| 145 |
typedef enum |
| 146 |
{ |
| 147 |
PQTRANS_IDLE, /* connection idle */ |
| 148 |
PQTRANS_ACTIVE, /* command in progress */ |
| 149 |
PQTRANS_INTRANS, /* idle, within transaction block */ |
| 150 |
PQTRANS_INERROR, /* idle, within failed transaction */ |
| 151 |
PQTRANS_UNKNOWN /* cannot determine status */ |
| 152 |
} PGTransactionStatusType; |
| 153 |
|
| 154 |
typedef enum |
| 155 |
{ |
| 156 |
PQERRORS_TERSE, /* single-line error messages */ |
| 157 |
PQERRORS_DEFAULT, /* recommended style */ |
| 158 |
PQERRORS_VERBOSE, /* all the facts, ma'am */ |
| 159 |
PQERRORS_SQLSTATE /* only error severity and SQLSTATE code */ |
| 160 |
} PGVerbosity; |
| 161 |
|
| 162 |
typedef enum |
| 163 |
{ |
| 164 |
PQSHOW_CONTEXT_NEVER, /* never show CONTEXT field */ |
| 165 |
PQSHOW_CONTEXT_ERRORS, /* show CONTEXT for errors only (default) */ |
| 166 |
PQSHOW_CONTEXT_ALWAYS /* always show CONTEXT field */ |
| 167 |
} PGContextVisibility; |
| 168 |
|
| 169 |
/* |
| 170 |
* PGPing - The ordering of this enum should not be altered because the |
| 171 |
* values are exposed externally via pg_isready. |
| 172 |
*/ |
| 173 |
|
| 174 |
typedef enum |
| 175 |
{ |
| 176 |
PQPING_OK, /* server is accepting connections */ |
| 177 |
PQPING_REJECT, /* server is alive but rejecting connections */ |
| 178 |
PQPING_NO_RESPONSE, /* could not establish connection */ |
| 179 |
PQPING_NO_ATTEMPT /* connection not attempted (bad params) */ |
| 180 |
} PGPing; |
| 181 |
|
| 182 |
/* |
| 183 |
* PGpipelineStatus - Current status of pipeline mode |
| 184 |
*/ |
| 185 |
typedef enum |
| 186 |
{ |
| 187 |
PQ_PIPELINE_OFF, |
| 188 |
PQ_PIPELINE_ON, |
| 189 |
PQ_PIPELINE_ABORTED |
| 190 |
} PGpipelineStatus; |
| 191 |
|
| 192 |
typedef enum |
| 193 |
{ |
| 194 |
PQAUTHDATA_PROMPT_OAUTH_DEVICE, /* user must visit a device-authorization |
| 195 |
* URL */ |
| 196 |
PQAUTHDATA_OAUTH_BEARER_TOKEN, /* server requests an OAuth Bearer token */ |
| 197 |
} PGauthData; |
| 198 |
|
| 199 |
/* PGconn encapsulates a connection to the backend. |
| 200 |
* The contents of this struct are not supposed to be known to applications. |
| 201 |
*/ |
| 202 |
typedef struct pg_conn PGconn; |
| 203 |
|
| 204 |
/* PGcancelConn encapsulates a cancel connection to the backend. |
| 205 |
* The contents of this struct are not supposed to be known to applications. |
| 206 |
*/ |
| 207 |
typedef struct pg_cancel_conn PGcancelConn; |
| 208 |
|
| 209 |
/* PGresult encapsulates the result of a query (or more precisely, of a single |
| 210 |
* SQL command --- a query string given to PQsendQuery can contain multiple |
| 211 |
* commands and thus return multiple PGresult objects). |
| 212 |
* The contents of this struct are not supposed to be known to applications. |
| 213 |
*/ |
| 214 |
typedef struct pg_result PGresult; |
| 215 |
|
| 216 |
/* PGcancel encapsulates the information needed to cancel a running |
| 217 |
* query on an existing connection. |
| 218 |
* The contents of this struct are not supposed to be known to applications. |
| 219 |
*/ |
| 220 |
typedef struct pg_cancel PGcancel; |
| 221 |
|
| 222 |
/* PGnotify represents the occurrence of a NOTIFY message. |
| 223 |
* Ideally this would be an opaque typedef, but it's so simple that it's |
| 224 |
* unlikely to change. |
| 225 |
* NOTE: in Postgres 6.4 and later, the be_pid is the notifying backend's, |
| 226 |
* whereas in earlier versions it was always your own backend's PID. |
| 227 |
*/ |
| 228 |
typedef struct pgNotify |
| 229 |
{ |
| 230 |
char *relname; /* notification condition name */ |
| 231 |
int be_pid; /* process ID of notifying server process */ |
| 232 |
char *extra; /* notification parameter */ |
| 233 |
/* Fields below here are private to libpq; apps should not use 'em */ |
| 234 |
struct pgNotify *next; /* list link */ |
| 235 |
} PGnotify; |
| 236 |
|
| 237 |
/* pg_usec_time_t is like time_t, but with microsecond resolution */ |
| 238 |
typedef int64_t pg_usec_time_t; |
| 239 |
|
| 240 |
/* Function types for notice-handling callbacks */ |
| 241 |
typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res); |
| 242 |
typedef void (*PQnoticeProcessor) (void *arg, const char *message); |
| 243 |
|
| 244 |
/* Print options for PQprint() */ |
| 245 |
typedef char pqbool; |
| 246 |
|
| 247 |
typedef struct _PQprintOpt |
| 248 |
{ |
| 249 |
pqbool header; /* print output field headings and row count */ |
| 250 |
pqbool align; /* fill align the fields */ |
| 251 |
pqbool standard; /* old brain dead format */ |
| 252 |
pqbool html3; /* output html tables */ |
| 253 |
pqbool expanded; /* expand tables */ |
| 254 |
pqbool pager; /* use pager for output if needed */ |
| 255 |
char *fieldSep; /* field separator */ |
| 256 |
char *tableOpt; /* insert to HTML <table ...> */ |
| 257 |
char *caption; /* HTML <caption> */ |
| 258 |
char **fieldName; /* null terminated array of replacement field |
| 259 |
* names */ |
| 260 |
} PQprintOpt; |
| 261 |
|
| 262 |
/* ---------------- |
| 263 |
* Structure for the conninfo parameter definitions returned by PQconndefaults |
| 264 |
* or PQconninfoParse. |
| 265 |
* |
| 266 |
* All fields except "val" point at static strings which must not be altered. |
| 267 |
* "val" is either NULL or a malloc'd current-value string. PQconninfoFree() |
| 268 |
* will release both the val strings and the PQconninfoOption array itself. |
| 269 |
* ---------------- |
| 270 |
*/ |
| 271 |
typedef struct _PQconninfoOption |
| 272 |
{ |
| 273 |
char *keyword; /* The keyword of the option */ |
| 274 |
char *envvar; /* Fallback environment variable name */ |
| 275 |
char *compiled; /* Fallback compiled in default value */ |
| 276 |
char *val; /* Option's current value, or NULL */ |
| 277 |
char *label; /* Label for field in connect dialog */ |
| 278 |
char *dispchar; /* Indicates how to display this field in a |
| 279 |
* connect dialog. Values are: "" Display |
| 280 |
* entered value as is "*" Password field - |
| 281 |
* hide value "D" Debug option - don't show |
| 282 |
* by default */ |
| 283 |
int dispsize; /* Field size in characters for dialog */ |
| 284 |
} PQconninfoOption; |
| 285 |
|
| 286 |
/* ---------------- |
| 287 |
* PQArgBlock -- structure for PQfn() arguments |
| 288 |
* ---------------- |
| 289 |
*/ |
| 290 |
typedef struct |
| 291 |
{ |
| 292 |
int len; |
| 293 |
int isint; |
| 294 |
union |
| 295 |
{ |
| 296 |
int *ptr; /* can't use void (dec compiler barfs) */ |
| 297 |
int integer; |
| 298 |
} u; |
| 299 |
} PQArgBlock; |
| 300 |
|
| 301 |
/* ---------------- |
| 302 |
* PGresAttDesc -- Data about a single attribute (column) of a query result |
| 303 |
* ---------------- |
| 304 |
*/ |
| 305 |
typedef struct pgresAttDesc |
| 306 |
{ |
| 307 |
char *name; /* column name */ |
| 308 |
Oid tableid; /* source table, if known */ |
| 309 |
int columnid; /* source column, if known */ |
| 310 |
int format; /* format code for value (text/binary) */ |
| 311 |
Oid typid; /* type id */ |
| 312 |
int typlen; /* type size */ |
| 313 |
int atttypmod; /* type-specific modifier info */ |
| 314 |
} PGresAttDesc; |
| 315 |
|
| 316 |
/* ---------------- |
| 317 |
* Exported functions of libpq |
| 318 |
* ---------------- |
| 319 |
*/ |
| 320 |
|
| 321 |
/* === in fe-connect.c === */ |
| 322 |
|
| 323 |
/* make a new client connection to the backend */ |
| 324 |
/* Asynchronous (non-blocking) */ |
| 325 |
extern PGconn *PQconnectStart(const char *conninfo); |
| 326 |
extern PGconn *PQconnectStartParams(const char *const *keywords, |
| 327 |
const char *const *values, int expand_dbname); |
| 328 |
extern PostgresPollingStatusType PQconnectPoll(PGconn *conn); |
| 329 |
|
| 330 |
/* Synchronous (blocking) */ |
| 331 |
extern PGconn *PQconnectdb(const char *conninfo); |
| 332 |
extern PGconn *PQconnectdbParams(const char *const *keywords, |
| 333 |
const char *const *values, int expand_dbname); |
| 334 |
extern PGconn *PQsetdbLogin(const char *pghost, const char *pgport, |
| 335 |
const char *pgoptions, const char *pgtty, |
| 336 |
const char *dbName, |
| 337 |
const char *login, const char *pwd); |
| 338 |
|
| 339 |
#define PQsetdb(M_PGHOST,M_PGPORT,M_PGOPT,M_PGTTY,M_DBNAME) \ |
| 340 |
PQsetdbLogin(M_PGHOST, M_PGPORT, M_PGOPT, M_PGTTY, M_DBNAME, NULL, NULL) |
| 341 |
|
| 342 |
/* close the current connection and free the PGconn data structure */ |
| 343 |
extern void PQfinish(PGconn *conn); |
| 344 |
|
| 345 |
/* get info about connection options known to PQconnectdb */ |
| 346 |
extern PQconninfoOption *PQconndefaults(void); |
| 347 |
|
| 348 |
/* parse connection options in same way as PQconnectdb */ |
| 349 |
extern PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); |
| 350 |
|
| 351 |
/* return the connection options used by a live connection */ |
| 352 |
extern PQconninfoOption *PQconninfo(PGconn *conn); |
| 353 |
|
| 354 |
/* free the data structure returned by PQconndefaults() or PQconninfoParse() */ |
| 355 |
extern void PQconninfoFree(PQconninfoOption *connOptions); |
| 356 |
|
| 357 |
/* |
| 358 |
* close the current connection and reestablish a new one with the same |
| 359 |
* parameters |
| 360 |
*/ |
| 361 |
/* Asynchronous (non-blocking) */ |
| 362 |
extern int PQresetStart(PGconn *conn); |
| 363 |
extern PostgresPollingStatusType PQresetPoll(PGconn *conn); |
| 364 |
|
| 365 |
/* Synchronous (blocking) */ |
| 366 |
extern void PQreset(PGconn *conn); |
| 367 |
|
| 368 |
/* Create a PGcancelConn that's used to cancel a query on the given PGconn */ |
| 369 |
extern PGcancelConn *PQcancelCreate(PGconn *conn); |
| 370 |
|
| 371 |
/* issue a cancel request in a non-blocking manner */ |
| 372 |
extern int PQcancelStart(PGcancelConn *cancelConn); |
| 373 |
|
| 374 |
/* issue a blocking cancel request */ |
| 375 |
extern int PQcancelBlocking(PGcancelConn *cancelConn); |
| 376 |
|
| 377 |
/* poll a non-blocking cancel request */ |
| 378 |
extern PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn); |
| 379 |
extern ConnStatusType PQcancelStatus(const PGcancelConn *cancelConn); |
| 380 |
extern int PQcancelSocket(const PGcancelConn *cancelConn); |
| 381 |
extern char *PQcancelErrorMessage(const PGcancelConn *cancelConn); |
| 382 |
extern void PQcancelReset(PGcancelConn *cancelConn); |
| 383 |
extern void PQcancelFinish(PGcancelConn *cancelConn); |
| 384 |
|
| 385 |
|
| 386 |
/* request a cancel structure */ |
| 387 |
extern PGcancel *PQgetCancel(PGconn *conn); |
| 388 |
|
| 389 |
/* free a cancel structure */ |
| 390 |
extern void PQfreeCancel(PGcancel *cancel); |
| 391 |
|
| 392 |
/* deprecated version of PQcancelBlocking, but one which is signal-safe */ |
| 393 |
extern int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); |
| 394 |
|
| 395 |
/* deprecated version of PQcancel; not thread-safe */ |
| 396 |
extern int PQrequestCancel(PGconn *conn); |
| 397 |
|
| 398 |
/* Accessor functions for PGconn objects */ |
| 399 |
extern char *PQdb(const PGconn *conn); |
| 400 |
extern char *PQuser(const PGconn *conn); |
| 401 |
extern char *PQpass(const PGconn *conn); |
| 402 |
extern char *PQhost(const PGconn *conn); |
| 403 |
extern char *PQhostaddr(const PGconn *conn); |
| 404 |
extern char *PQport(const PGconn *conn); |
| 405 |
extern char *PQtty(const PGconn *conn); |
| 406 |
extern char *PQoptions(const PGconn *conn); |
| 407 |
extern ConnStatusType PQstatus(const PGconn *conn); |
| 408 |
extern PGTransactionStatusType PQtransactionStatus(const PGconn *conn); |
| 409 |
extern const char *PQparameterStatus(const PGconn *conn, |
| 410 |
const char *paramName); |
| 411 |
extern int PQprotocolVersion(const PGconn *conn); |
| 412 |
extern int PQfullProtocolVersion(const PGconn *conn); |
| 413 |
extern int PQserverVersion(const PGconn *conn); |
| 414 |
extern char *PQerrorMessage(const PGconn *conn); |
| 415 |
extern int PQsocket(const PGconn *conn); |
| 416 |
extern int PQbackendPID(const PGconn *conn); |
| 417 |
extern PGpipelineStatus PQpipelineStatus(const PGconn *conn); |
| 418 |
extern int PQconnectionNeedsPassword(const PGconn *conn); |
| 419 |
extern int PQconnectionUsedPassword(const PGconn *conn); |
| 420 |
extern int PQconnectionUsedGSSAPI(const PGconn *conn); |
| 421 |
extern int PQclientEncoding(const PGconn *conn); |
| 422 |
extern int PQsetClientEncoding(PGconn *conn, const char *encoding); |
| 423 |
|
| 424 |
/* SSL information functions */ |
| 425 |
extern int PQsslInUse(PGconn *conn); |
| 426 |
extern void *PQsslStruct(PGconn *conn, const char *struct_name); |
| 427 |
extern const char *PQsslAttribute(PGconn *conn, const char *attribute_name); |
| 428 |
extern const char *const *PQsslAttributeNames(PGconn *conn); |
| 429 |
|
| 430 |
/* Get the OpenSSL structure associated with a connection. Returns NULL for |
| 431 |
* unencrypted connections or if any other TLS library is in use. */ |
| 432 |
extern void *PQgetssl(PGconn *conn); |
| 433 |
|
| 434 |
/* Tell libpq whether it needs to initialize OpenSSL */ |
| 435 |
extern void PQinitSSL(int do_init); |
| 436 |
|
| 437 |
/* More detailed way to tell libpq whether it needs to initialize OpenSSL */ |
| 438 |
extern void PQinitOpenSSL(int do_ssl, int do_crypto); |
| 439 |
|
| 440 |
/* Return true if GSSAPI encryption is in use */ |
| 441 |
extern int PQgssEncInUse(PGconn *conn); |
| 442 |
|
| 443 |
/* Returns GSSAPI context if GSSAPI is in use */ |
| 444 |
extern void *PQgetgssctx(PGconn *conn); |
| 445 |
|
| 446 |
/* Set verbosity for PQerrorMessage and PQresultErrorMessage */ |
| 447 |
extern PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); |
| 448 |
|
| 449 |
/* Set CONTEXT visibility for PQerrorMessage and PQresultErrorMessage */ |
| 450 |
extern PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, |
| 451 |
PGContextVisibility show_context); |
| 452 |
|
| 453 |
/* Override default notice handling routines */ |
| 454 |
extern PQnoticeReceiver PQsetNoticeReceiver(PGconn *conn, |
| 455 |
PQnoticeReceiver proc, |
| 456 |
void *arg); |
| 457 |
extern PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn, |
| 458 |
PQnoticeProcessor proc, |
| 459 |
void *arg); |
| 460 |
|
| 461 |
/* |
| 462 |
* Used to set callback that prevents concurrent access to |
| 463 |
* non-thread safe functions that libpq needs. |
| 464 |
* The default implementation uses a libpq internal mutex. |
| 465 |
* Only required for multithreaded apps that use kerberos |
| 466 |
* both within their app and for postgresql connections. |
| 467 |
*/ |
| 468 |
typedef void (*pgthreadlock_t) (int acquire); |
| 469 |
|
| 470 |
extern pgthreadlock_t PQregisterThreadLock(pgthreadlock_t newhandler); |
| 471 |
|
| 472 |
/* === in fe-trace.c === */ |
| 473 |
extern void PQtrace(PGconn *conn, FILE *debug_port); |
| 474 |
extern void PQuntrace(PGconn *conn); |
| 475 |
|
| 476 |
/* flags controlling trace output: */ |
| 477 |
/* omit timestamps from each line */ |
| 478 |
#define PQTRACE_SUPPRESS_TIMESTAMPS (1<<0) |
| 479 |
/* redact portions of some messages, for testing frameworks */ |
| 480 |
#define PQTRACE_REGRESS_MODE (1<<1) |
| 481 |
extern void PQsetTraceFlags(PGconn *conn, int flags); |
| 482 |
|
| 483 |
/* === in fe-exec.c === */ |
| 484 |
|
| 485 |
/* Simple synchronous query */ |
| 486 |
extern PGresult *PQexec(PGconn *conn, const char *query); |
| 487 |
extern PGresult *PQexecParams(PGconn *conn, |
| 488 |
const char *command, |
| 489 |
int nParams, |
| 490 |
const Oid *paramTypes, |
| 491 |
const char *const *paramValues, |
| 492 |
const int *paramLengths, |
| 493 |
const int *paramFormats, |
| 494 |
int resultFormat); |
| 495 |
extern PGresult *PQprepare(PGconn *conn, const char *stmtName, |
| 496 |
const char *query, int nParams, |
| 497 |
const Oid *paramTypes); |
| 498 |
extern PGresult *PQexecPrepared(PGconn *conn, |
| 499 |
const char *stmtName, |
| 500 |
int nParams, |
| 501 |
const char *const *paramValues, |
| 502 |
const int *paramLengths, |
| 503 |
const int *paramFormats, |
| 504 |
int resultFormat); |
| 505 |
|
| 506 |
/* Interface for multiple-result or asynchronous queries */ |
| 507 |
#define PQ_QUERY_PARAM_MAX_LIMIT 65535 |
| 508 |
|
| 509 |
extern int PQsendQuery(PGconn *conn, const char *query); |
| 510 |
extern int PQsendQueryParams(PGconn *conn, |
| 511 |
const char *command, |
| 512 |
int nParams, |
| 513 |
const Oid *paramTypes, |
| 514 |
const char *const *paramValues, |
| 515 |
const int *paramLengths, |
| 516 |
const int *paramFormats, |
| 517 |
int resultFormat); |
| 518 |
extern int PQsendPrepare(PGconn *conn, const char *stmtName, |
| 519 |
const char *query, int nParams, |
| 520 |
const Oid *paramTypes); |
| 521 |
extern int PQsendQueryPrepared(PGconn *conn, |
| 522 |
const char *stmtName, |
| 523 |
int nParams, |
| 524 |
const char *const *paramValues, |
| 525 |
const int *paramLengths, |
| 526 |
const int *paramFormats, |
| 527 |
int resultFormat); |
| 528 |
extern int PQsetSingleRowMode(PGconn *conn); |
| 529 |
extern int PQsetChunkedRowsMode(PGconn *conn, int chunkSize); |
| 530 |
extern PGresult *PQgetResult(PGconn *conn); |
| 531 |
|
| 532 |
/* Routines for managing an asynchronous query */ |
| 533 |
extern int PQisBusy(PGconn *conn); |
| 534 |
extern int PQconsumeInput(PGconn *conn); |
| 535 |
|
| 536 |
/* Routines for pipeline mode management */ |
| 537 |
extern int PQenterPipelineMode(PGconn *conn); |
| 538 |
extern int PQexitPipelineMode(PGconn *conn); |
| 539 |
extern int PQpipelineSync(PGconn *conn); |
| 540 |
extern int PQsendFlushRequest(PGconn *conn); |
| 541 |
extern int PQsendPipelineSync(PGconn *conn); |
| 542 |
|
| 543 |
/* LISTEN/NOTIFY support */ |
| 544 |
extern PGnotify *PQnotifies(PGconn *conn); |
| 545 |
|
| 546 |
/* Routines for copy in/out */ |
| 547 |
extern int PQputCopyData(PGconn *conn, const char *buffer, int nbytes); |
| 548 |
extern int PQputCopyEnd(PGconn *conn, const char *errormsg); |
| 549 |
extern int PQgetCopyData(PGconn *conn, char **buffer, int async); |
| 550 |
|
| 551 |
/* Deprecated routines for copy in/out */ |
| 552 |
extern int PQgetline(PGconn *conn, char *buffer, int length); |
| 553 |
extern int PQputline(PGconn *conn, const char *string); |
| 554 |
extern int PQgetlineAsync(PGconn *conn, char *buffer, int bufsize); |
| 555 |
extern int PQputnbytes(PGconn *conn, const char *buffer, int nbytes); |
| 556 |
extern int PQendcopy(PGconn *conn); |
| 557 |
|
| 558 |
/* Set blocking/nonblocking connection to the backend */ |
| 559 |
extern int PQsetnonblocking(PGconn *conn, int arg); |
| 560 |
extern int PQisnonblocking(const PGconn *conn); |
| 561 |
extern int PQisthreadsafe(void); |
| 562 |
extern PGPing PQping(const char *conninfo); |
| 563 |
extern PGPing PQpingParams(const char *const *keywords, |
| 564 |
const char *const *values, int expand_dbname); |
| 565 |
|
| 566 |
/* Force the write buffer to be written (or at least try) */ |
| 567 |
extern int PQflush(PGconn *conn); |
| 568 |
|
| 569 |
/* |
| 570 |
* "Fast path" interface --- not really recommended for application |
| 571 |
* use |
| 572 |
*/ |
| 573 |
extern PGresult *PQfn(PGconn *conn, |
| 574 |
int fnid, |
| 575 |
int *result_buf, |
| 576 |
int *result_len, |
| 577 |
int result_is_int, |
| 578 |
const PQArgBlock *args, |
| 579 |
int nargs); |
| 580 |
|
| 581 |
/* Accessor functions for PGresult objects */ |
| 582 |
extern ExecStatusType PQresultStatus(const PGresult *res); |
| 583 |
extern char *PQresStatus(ExecStatusType status); |
| 584 |
extern char *PQresultErrorMessage(const PGresult *res); |
| 585 |
extern char *PQresultVerboseErrorMessage(const PGresult *res, |
| 586 |
PGVerbosity verbosity, |
| 587 |
PGContextVisibility show_context); |
| 588 |
extern char *PQresultErrorField(const PGresult *res, int fieldcode); |
| 589 |
extern int PQntuples(const PGresult *res); |
| 590 |
extern int PQnfields(const PGresult *res); |
| 591 |
extern int PQbinaryTuples(const PGresult *res); |
| 592 |
extern char *PQfname(const PGresult *res, int field_num); |
| 593 |
extern int PQfnumber(const PGresult *res, const char *field_name); |
| 594 |
extern Oid PQftable(const PGresult *res, int field_num); |
| 595 |
extern int PQftablecol(const PGresult *res, int field_num); |
| 596 |
extern int PQfformat(const PGresult *res, int field_num); |
| 597 |
extern Oid PQftype(const PGresult *res, int field_num); |
| 598 |
extern int PQfsize(const PGresult *res, int field_num); |
| 599 |
extern int PQfmod(const PGresult *res, int field_num); |
| 600 |
extern char *PQcmdStatus(PGresult *res); |
| 601 |
extern char *PQoidStatus(const PGresult *res); /* old and ugly */ |
| 602 |
extern Oid PQoidValue(const PGresult *res); /* new and improved */ |
| 603 |
extern char *PQcmdTuples(PGresult *res); |
| 604 |
extern char *PQgetvalue(const PGresult *res, int tup_num, int field_num); |
| 605 |
extern int PQgetlength(const PGresult *res, int tup_num, int field_num); |
| 606 |
extern int PQgetisnull(const PGresult *res, int tup_num, int field_num); |
| 607 |
extern int PQnparams(const PGresult *res); |
| 608 |
extern Oid PQparamtype(const PGresult *res, int param_num); |
| 609 |
|
| 610 |
/* Describe prepared statements and portals */ |
| 611 |
extern PGresult *PQdescribePrepared(PGconn *conn, const char *stmt); |
| 612 |
extern PGresult *PQdescribePortal(PGconn *conn, const char *portal); |
| 613 |
extern int PQsendDescribePrepared(PGconn *conn, const char *stmt); |
| 614 |
extern int PQsendDescribePortal(PGconn *conn, const char *portal); |
| 615 |
|
| 616 |
/* Close prepared statements and portals */ |
| 617 |
extern PGresult *PQclosePrepared(PGconn *conn, const char *stmt); |
| 618 |
extern PGresult *PQclosePortal(PGconn *conn, const char *portal); |
| 619 |
extern int PQsendClosePrepared(PGconn *conn, const char *stmt); |
| 620 |
extern int PQsendClosePortal(PGconn *conn, const char *portal); |
| 621 |
|
| 622 |
/* Delete a PGresult */ |
| 623 |
extern void PQclear(PGresult *res); |
| 624 |
|
| 625 |
/* For freeing other alloc'd results, such as PGnotify structs */ |
| 626 |
extern void PQfreemem(void *ptr); |
| 627 |
|
| 628 |
/* Exists for backward compatibility. bjm 2003-03-24 */ |
| 629 |
#define PQfreeNotify(ptr) PQfreemem(ptr) |
| 630 |
|
| 631 |
/* Error when no password was given. */ |
| 632 |
/* Note: depending on this is deprecated; use PQconnectionNeedsPassword(). */ |
| 633 |
#define PQnoPasswordSupplied "fe_sendauth: no password supplied\n" |
| 634 |
|
| 635 |
/* Create and manipulate PGresults */ |
| 636 |
extern PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); |
| 637 |
extern PGresult *PQcopyResult(const PGresult *src, int flags); |
| 638 |
extern int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); |
| 639 |
extern void *PQresultAlloc(PGresult *res, size_t nBytes); |
| 640 |
extern size_t PQresultMemorySize(const PGresult *res); |
| 641 |
extern int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); |
| 642 |
|
| 643 |
/* Quoting strings before inclusion in queries. */ |
| 644 |
extern size_t PQescapeStringConn(PGconn *conn, |
| 645 |
char *to, const char *from, size_t length, |
| 646 |
int *error); |
| 647 |
extern char *PQescapeLiteral(PGconn *conn, const char *str, size_t len); |
| 648 |
extern char *PQescapeIdentifier(PGconn *conn, const char *str, size_t len); |
| 649 |
extern unsigned char *PQescapeByteaConn(PGconn *conn, |
| 650 |
const unsigned char *from, size_t from_length, |
| 651 |
size_t *to_length); |
| 652 |
extern unsigned char *PQunescapeBytea(const unsigned char *strtext, |
| 653 |
size_t *retbuflen); |
| 654 |
|
| 655 |
/* These forms are deprecated! */ |
| 656 |
extern size_t PQescapeString(char *to, const char *from, size_t length); |
| 657 |
extern unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, |
| 658 |
size_t *to_length); |
| 659 |
|
| 660 |
|
| 661 |
|
| 662 |
/* === in fe-print.c === */ |
| 663 |
|
| 664 |
extern void PQprint(FILE *fout, /* output stream */ |
| 665 |
const PGresult *res, |
| 666 |
const PQprintOpt *po); /* option structure */ |
| 667 |
|
| 668 |
/* |
| 669 |
* really old printing routines |
| 670 |
*/ |
| 671 |
extern void PQdisplayTuples(const PGresult *res, |
| 672 |
FILE *fp, /* where to send the output */ |
| 673 |
int fillAlign, /* pad the fields with spaces */ |
| 674 |
const char *fieldSep, /* field separator */ |
| 675 |
int printHeader, /* display headers? */ |
| 676 |
int quiet); |
| 677 |
|
| 678 |
extern void PQprintTuples(const PGresult *res, |
| 679 |
FILE *fout, /* output stream */ |
| 680 |
int PrintAttNames, /* print attribute names */ |
| 681 |
int TerseOutput, /* delimiter bars */ |
| 682 |
int colWidth); /* width of column, if 0, use |
| 683 |
* variable width */ |
| 684 |
|
| 685 |
|
| 686 |
/* === in fe-lobj.c === */ |
| 687 |
|
| 688 |
/* Large-object access routines */ |
| 689 |
extern int lo_open(PGconn *conn, Oid lobjId, int mode); |
| 690 |
extern int lo_close(PGconn *conn, int fd); |
| 691 |
extern int lo_read(PGconn *conn, int fd, char *buf, size_t len); |
| 692 |
extern int lo_write(PGconn *conn, int fd, const char *buf, size_t len); |
| 693 |
extern int lo_lseek(PGconn *conn, int fd, int offset, int whence); |
| 694 |
extern int64_t lo_lseek64(PGconn *conn, int fd, int64_t offset, int whence); |
| 695 |
extern Oid lo_creat(PGconn *conn, int mode); |
| 696 |
extern Oid lo_create(PGconn *conn, Oid lobjId); |
| 697 |
extern int lo_tell(PGconn *conn, int fd); |
| 698 |
extern int64_t lo_tell64(PGconn *conn, int fd); |
| 699 |
extern int lo_truncate(PGconn *conn, int fd, size_t len); |
| 700 |
extern int lo_truncate64(PGconn *conn, int fd, int64_t len); |
| 701 |
extern int lo_unlink(PGconn *conn, Oid lobjId); |
| 702 |
extern Oid lo_import(PGconn *conn, const char *filename); |
| 703 |
extern Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId); |
| 704 |
extern int lo_export(PGconn *conn, Oid lobjId, const char *filename); |
| 705 |
|
| 706 |
/* === in fe-misc.c === */ |
| 707 |
|
| 708 |
/* Get the version of the libpq library in use */ |
| 709 |
extern int PQlibVersion(void); |
| 710 |
|
| 711 |
/* Poll a socket for reading and/or writing with an optional timeout */ |
| 712 |
extern int PQsocketPoll(int sock, int forRead, int forWrite, |
| 713 |
pg_usec_time_t end_time); |
| 714 |
|
| 715 |
/* Get current time in the form PQsocketPoll wants */ |
| 716 |
extern pg_usec_time_t PQgetCurrentTimeUSec(void); |
| 717 |
|
| 718 |
/* Determine length of multibyte encoded char at *s */ |
| 719 |
extern int PQmblen(const char *s, int encoding); |
| 720 |
|
| 721 |
/* Same, but not more than the distance to the end of string s */ |
| 722 |
extern int PQmblenBounded(const char *s, int encoding); |
| 723 |
|
| 724 |
/* Determine display length of multibyte encoded char at *s */ |
| 725 |
extern int PQdsplen(const char *s, int encoding); |
| 726 |
|
| 727 |
/* Get encoding id from environment variable PGCLIENTENCODING */ |
| 728 |
extern int PQenv2encoding(void); |
| 729 |
|
| 730 |
/* === in fe-auth.c === */ |
| 731 |
|
| 732 |
typedef struct _PGpromptOAuthDevice |
| 733 |
{ |
| 734 |
const char *verification_uri; /* verification URI to visit */ |
| 735 |
const char *user_code; /* user code to enter */ |
| 736 |
const char *verification_uri_complete; /* optional combination of URI and |
| 737 |
* code, or NULL */ |
| 738 |
int expires_in; /* seconds until user code expires */ |
| 739 |
} PGpromptOAuthDevice; |
| 740 |
|
| 741 |
/* |
| 742 |
* For PGoauthBearerRequest.async(). This macro just allows clients to avoid |
| 743 |
* depending on libpq-int.h or Winsock for the "socket" type; it's undefined |
| 744 |
* immediately below. |
| 745 |
*/ |
| 746 |
#ifdef _WIN32 |
| 747 |
#define PQ_SOCKTYPE uintptr_t /* avoids depending on winsock2.h for SOCKET */ |
| 748 |
#else |
| 749 |
#define PQ_SOCKTYPE int |
| 750 |
#endif |
| 751 |
|
| 752 |
typedef struct PGoauthBearerRequest |
| 753 |
{ |
| 754 |
/* Hook inputs (constant across all calls) */ |
| 755 |
const char *openid_configuration; /* OIDC discovery URI */ |
| 756 |
const char *scope; /* required scope(s), or NULL */ |
| 757 |
|
| 758 |
/* Hook outputs */ |
| 759 |
|
| 760 |
/*--------- |
| 761 |
* Callback implementing a custom asynchronous OAuth flow. |
| 762 |
* |
| 763 |
* The callback may return |
| 764 |
* - PGRES_POLLING_READING/WRITING, to indicate that a socket descriptor |
| 765 |
* has been stored in *altsock and libpq should wait until it is |
| 766 |
* readable or writable before calling back; |
| 767 |
* - PGRES_POLLING_OK, to indicate that the flow is complete and |
| 768 |
* request->token has been set; or |
| 769 |
* - PGRES_POLLING_FAILED, to indicate that token retrieval has failed. |
| 770 |
* |
| 771 |
* This callback is optional. If the token can be obtained without |
| 772 |
* blocking during the original call to the PQAUTHDATA_OAUTH_BEARER_TOKEN |
| 773 |
* hook, it may be returned directly, but one of request->async or |
| 774 |
* request->token must be set by the hook. |
| 775 |
* |
| 776 |
* The (PQ_SOCKTYPE *) in the signature is a placeholder for the platform's |
| 777 |
* native socket type: (SOCKET *) on Windows, and (int *) everywhere else. |
| 778 |
*/ |
| 779 |
PostgresPollingStatusType (*async) (PGconn *conn, |
| 780 |
struct PGoauthBearerRequest *request, |
| 781 |
PQ_SOCKTYPE * altsock); |
| 782 |
|
| 783 |
/* |
| 784 |
* Callback to clean up custom allocations. A hook implementation may use |
| 785 |
* this to free request->token and any resources in request->user. |
| 786 |
* |
| 787 |
* This is technically optional, but highly recommended, because there is |
| 788 |
* no other indication as to when it is safe to free the token. |
| 789 |
*/ |
| 790 |
void (*cleanup) (PGconn *conn, struct PGoauthBearerRequest *request); |
| 791 |
|
| 792 |
/* |
| 793 |
* The hook should set this to the Bearer token contents for the |
| 794 |
* connection, once the flow is completed. The token contents must remain |
| 795 |
* available to libpq until the hook's cleanup callback is called. |
| 796 |
*/ |
| 797 |
char *token; |
| 798 |
|
| 799 |
/* |
| 800 |
* Hook-defined data. libpq will not modify this pointer across calls to |
| 801 |
* the async callback, so it can be used to keep track of |
| 802 |
* application-specific state. Resources allocated here should be freed by |
| 803 |
* the cleanup callback. |
| 804 |
*/ |
| 805 |
void *user; |
| 806 |
} PGoauthBearerRequest; |
| 807 |
|
| 808 |
#undef PQ_SOCKTYPE |
| 809 |
|
| 810 |
extern char *PQencryptPassword(const char *passwd, const char *user); |
| 811 |
extern char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm); |
| 812 |
extern PGresult *PQchangePassword(PGconn *conn, const char *user, const char *passwd); |
| 813 |
|
| 814 |
typedef int (*PQauthDataHook_type) (PGauthData type, PGconn *conn, void *data); |
| 815 |
extern void PQsetAuthDataHook(PQauthDataHook_type hook); |
| 816 |
extern PQauthDataHook_type PQgetAuthDataHook(void); |
| 817 |
extern int PQdefaultAuthDataHook(PGauthData type, PGconn *conn, void *data); |
| 818 |
|
| 819 |
/* === in encnames.c === */ |
| 820 |
|
| 821 |
extern int pg_char_to_encoding(const char *name); |
| 822 |
extern const char *pg_encoding_to_char(int encoding); |
| 823 |
extern int pg_valid_server_encoding_id(int encoding); |
| 824 |
|
| 825 |
/* === in fe-secure-openssl.c === */ |
| 826 |
|
| 827 |
/* Support for overriding sslpassword handling with a callback */ |
| 828 |
typedef int (*PQsslKeyPassHook_OpenSSL_type) (char *buf, int size, PGconn *conn); |
| 829 |
extern PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); |
| 830 |
extern void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); |
| 831 |
extern int PQdefaultSSLKeyPassHook_OpenSSL(char *buf, int size, PGconn *conn); |
| 832 |
|
| 833 |
#ifdef __cplusplus |
| 834 |
} |
| 835 |
#endif |
| 836 |
|
| 837 |
#endif /* LIBPQ_FE_H */ |