src/interfaces/libpq/libpq-fe.h

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