Debian Codegraph @

src/interfaces/libpq/libpq-fe.h

raw
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 */