libpq-fe.h

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * libpq-fe.h
 *    This file contains definitions for structures and
 *    externs for functions used by frontend postgres applications.
 *
 * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/interfaces/libpq/libpq-fe.h
 *
 *-------------------------------------------------------------------------
 */
 
#ifndef LIBPQ_FE_H
#define LIBPQ_FE_H
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#include <stdint.h>
#include <stdio.h>
 
/*
 * postgres_ext.h defines the backend's externally visible types,
 * such as Oid.
 */
#include "postgres_ext.h"
 
/*
 * These symbols may be used in compile-time #ifdef tests for the availability
 * of v14-and-newer libpq features.
 */
/* Features added in PostgreSQL v14: */
/* Indicates presence of PQenterPipelineMode and friends */
#define LIBPQ_HAS_PIPELINING 1
/* Indicates presence of PQsetTraceFlags; also new PQtrace output format */
#define LIBPQ_HAS_TRACE_FLAGS 1
 
/* Features added in PostgreSQL v15: */
/* Indicates that PQsslAttribute(NULL, "library") is useful */
#define LIBPQ_HAS_SSL_LIBRARY_DETECTION 1
 
/* Features added in PostgreSQL v17: */
/* Indicates presence of PGcancelConn typedef and associated routines */
#define LIBPQ_HAS_ASYNC_CANCEL 1
/* Indicates presence of PQchangePassword */
#define LIBPQ_HAS_CHANGE_PASSWORD 1
/* Indicates presence of PQsetChunkedRowsMode, PGRES_TUPLES_CHUNK */
#define LIBPQ_HAS_CHUNK_MODE 1
/* Indicates presence of PQclosePrepared, PQclosePortal, etc */
#define LIBPQ_HAS_CLOSE_PREPARED 1
/* Indicates presence of PQsendPipelineSync */
#define LIBPQ_HAS_SEND_PIPELINE_SYNC 1
/* Indicates presence of PQsocketPoll, PQgetCurrentTimeUSec */
#define LIBPQ_HAS_SOCKET_POLL 1
 
/* Features added in PostgreSQL v18: */
/* Indicates presence of PQfullProtocolVersion */
#define LIBPQ_HAS_FULL_PROTOCOL_VERSION 1
/* Indicates presence of the PQAUTHDATA_PROMPT_OAUTH_DEVICE authdata hook */
#define LIBPQ_HAS_PROMPT_OAUTH_DEVICE 1
 
/* Features added in PostgreSQL v19: */
/* Indicates presence of PQgetThreadLock */
#define LIBPQ_HAS_GET_THREAD_LOCK 1
/* Indicates presence of the PQAUTHDATA_OAUTH_BEARER_TOKEN_V2 authdata hook */
#define LIBPQ_HAS_OAUTH_BEARER_TOKEN_V2 1
 
/*
 * Option flags for PQcopyResult
 */
#define PG_COPYRES_ATTRS          0x01
#define PG_COPYRES_TUPLES         0x02  /* Implies PG_COPYRES_ATTRS */
#define PG_COPYRES_EVENTS         0x04
#define PG_COPYRES_NOTICEHOOKS    0x08
 
/* Application-visible enum types */
 
/*
 * Although it is okay to add to these lists, values which become unused
 * should never be removed, nor should constants be redefined - that would
 * break compatibility with existing code.
 */
 
typedef enum
{
    CONNECTION_OK,
    CONNECTION_BAD,
    /* Non-blocking mode only below here */
 
    /*
     * The existence of these should never be relied upon - they should only
     * be used for user feedback or similar purposes.
     */
    CONNECTION_STARTED,         /* Waiting for connection to be made.  */
    CONNECTION_MADE,            /* Connection OK; waiting to send.     */
    CONNECTION_AWAITING_RESPONSE,   /* Waiting for a response from the
                                     * postmaster.        */
    CONNECTION_AUTH_OK,         /* Received authentication; waiting for
                                 * backend startup. */
    CONNECTION_SETENV,          /* This state is no longer used. */
    CONNECTION_SSL_STARTUP,     /* Performing SSL handshake. */
    CONNECTION_NEEDED,          /* Internal state: connect() needed. */
    CONNECTION_CHECK_WRITABLE,  /* Checking if session is read-write. */
    CONNECTION_CONSUME,         /* Consuming any extra messages. */
    CONNECTION_GSS_STARTUP,     /* Negotiating GSSAPI. */
    CONNECTION_CHECK_TARGET,    /* Internal state: checking target server
                                 * properties. */
    CONNECTION_CHECK_STANDBY,   /* Checking if server is in standby mode. */
    CONNECTION_ALLOCATED,       /* Waiting for connection attempt to be
                                 * started.  */
    CONNECTION_AUTHENTICATING,  /* Authentication is in progress with some
                                 * external system. */
} ConnStatusType;
 
typedef enum
{
    PGRES_POLLING_FAILED = 0,
    PGRES_POLLING_READING,      /* These two indicate that one may    */
    PGRES_POLLING_WRITING,      /* use select before polling again.   */
    PGRES_POLLING_OK,
    PGRES_POLLING_ACTIVE        /* unused; keep for backwards compatibility */
} PostgresPollingStatusType;
 
typedef enum
{
    PGRES_EMPTY_QUERY = 0,      /* empty query string was executed */
    PGRES_COMMAND_OK,           /* a query command that doesn't return
                                 * anything was executed properly by the
                                 * backend */
    PGRES_TUPLES_OK,            /* a query command that returns tuples was
                                 * executed properly by the backend, PGresult
                                 * contains the result tuples */
    PGRES_COPY_OUT,             /* Copy Out data transfer in progress */
    PGRES_COPY_IN,              /* Copy In data transfer in progress */
    PGRES_BAD_RESPONSE,         /* an unexpected response was recv'd from the
                                 * backend */
    PGRES_NONFATAL_ERROR,       /* notice or warning message */
    PGRES_FATAL_ERROR,          /* query failed */
    PGRES_COPY_BOTH,            /* Copy In/Out data transfer in progress */
    PGRES_SINGLE_TUPLE,         /* single tuple from larger resultset */
    PGRES_PIPELINE_SYNC,        /* pipeline synchronization point */
    PGRES_PIPELINE_ABORTED,     /* Command didn't run because of an abort
                                 * earlier in a pipeline */
    PGRES_TUPLES_CHUNK          /* chunk of tuples from larger resultset */
} ExecStatusType;
 
typedef enum
{
    PQTRANS_IDLE,               /* connection idle */
    PQTRANS_ACTIVE,             /* command in progress */
    PQTRANS_INTRANS,            /* idle, within transaction block */
    PQTRANS_INERROR,            /* idle, within failed transaction */
    PQTRANS_UNKNOWN             /* cannot determine status */
} PGTransactionStatusType;
 
typedef enum
{
    PQERRORS_TERSE,             /* single-line error messages */
    PQERRORS_DEFAULT,           /* recommended style */
    PQERRORS_VERBOSE,           /* all the facts, ma'am */
    PQERRORS_SQLSTATE           /* only error severity and SQLSTATE code */
} PGVerbosity;
 
typedef enum
{
    PQSHOW_CONTEXT_NEVER,       /* never show CONTEXT field */
    PQSHOW_CONTEXT_ERRORS,      /* show CONTEXT for errors only (default) */
    PQSHOW_CONTEXT_ALWAYS       /* always show CONTEXT field */
} PGContextVisibility;
 
/*
 * PGPing - The ordering of this enum should not be altered because the
 * values are exposed externally via pg_isready.
 */
 
typedef enum
{
    PQPING_OK,                  /* server is accepting connections */
    PQPING_REJECT,              /* server is alive but rejecting connections */
    PQPING_NO_RESPONSE,         /* could not establish connection */
    PQPING_NO_ATTEMPT           /* connection not attempted (bad params) */
} PGPing;
 
/*
 * PGpipelineStatus - Current status of pipeline mode
 */
typedef enum
{
    PQ_PIPELINE_OFF,
    PQ_PIPELINE_ON,
    PQ_PIPELINE_ABORTED
} PGpipelineStatus;
 
typedef enum
{
    PQAUTHDATA_PROMPT_OAUTH_DEVICE, /* user must visit a device-authorization
                                     * URL */
    PQAUTHDATA_OAUTH_BEARER_TOKEN,  /* server requests an OAuth Bearer token
                                     * (v2 is preferred; see below) */
    PQAUTHDATA_OAUTH_BEARER_TOKEN_V2,   /* newest API for OAuth Bearer tokens */
} PGauthData;
 
/*
 * PGconn encapsulates a connection to the backend.
 * The contents of this struct are not supposed to be known to applications.
 */
typedef struct pg_conn PGconn;
 
/*
 * PGcancelConn encapsulates a cancel connection to the backend.
 * The contents of this struct are not supposed to be known to applications.
 */
typedef struct pg_cancel_conn PGcancelConn;
 
/*
 * PGresult encapsulates the result of a query (or more precisely, of a single
 * SQL command --- a query string given to PQsendQuery can contain multiple
 * commands and thus return multiple PGresult objects).
 * The contents of this struct are not supposed to be known to applications.
 */
typedef struct pg_result PGresult;
 
/*
 * PGcancel encapsulates the information needed to cancel a running
 * query on an existing connection.
 * The contents of this struct are not supposed to be known to applications.
 */
typedef struct pg_cancel PGcancel;
 
/*
 * PGnotify represents the occurrence of a NOTIFY message.
 * Ideally this would be an opaque typedef, but it's so simple that it's
 * unlikely to change.
 * NOTE: in Postgres 6.4 and later, the be_pid is the notifying backend's,
 * whereas in earlier versions it was always your own backend's PID.
 */
typedef struct pgNotify
{
    char       *relname;        /* notification condition name */
    int         be_pid;         /* process ID of notifying server process */
    char       *extra;          /* notification parameter */
    /* Fields below here are private to libpq; apps should not use 'em */
    struct pgNotify *next;      /* list link */
} PGnotify;
 
/* pg_usec_time_t is like time_t, but with microsecond resolution */
typedef int64_t pg_usec_time_t;
 
/* Function types for notice-handling callbacks */
typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
typedef void (*PQnoticeProcessor) (void *arg, const char *message);
 
/* Print options for PQprint() */
typedef char pqbool;
 
typedef struct _PQprintOpt
{
    pqbool      header;         /* print output field headings and row count */
    pqbool      align;          /* fill align the fields */
    pqbool      standard;       /* old brain dead format */
    pqbool      html3;          /* output html tables */
    pqbool      expanded;       /* expand tables */
    pqbool      pager;          /* use pager for output if needed */
    char       *fieldSep;       /* field separator */
    char       *tableOpt;       /* insert to HTML <table ...> */
    char       *caption;        /* HTML <caption> */
    char      **fieldName;      /* null terminated array of replacement field
                                 * names */
} PQprintOpt;
 
/* ----------------
 * Structure for the conninfo parameter definitions returned by PQconndefaults
 * or PQconninfoParse.
 *
 * All fields except "val" point at static strings which must not be altered.
 * "val" is either NULL or a malloc'd current-value string.  PQconninfoFree()
 * will release both the val strings and the PQconninfoOption array itself.
 * ----------------
 */
typedef struct _PQconninfoOption
{
    char       *keyword;        /* The keyword of the option            */
    char       *envvar;         /* Fallback environment variable name   */
    char       *compiled;       /* Fallback compiled in default value   */
    char       *val;            /* Option's current value, or NULL       */
    char       *label;          /* Label for field in connect dialog    */
    char       *dispchar;       /* Indicates how to display this field in a
                                 * connect dialog. Values are: "" Display
                                 * entered value as is "*" Password field -
                                 * hide value "D"  Debug option - don't show
                                 * by default */
    int         dispsize;       /* Field size in characters for dialog  */
} PQconninfoOption;
 
/* ----------------
 * PQArgBlock -- structure for PQfn() arguments
 * ----------------
 */
typedef struct
{
    int         len;
    int         isint;
    union
    {
        int        *ptr;        /* can't use void (dec compiler barfs)   */
        int         integer;
    }           u;
} PQArgBlock;
 
/* ----------------
 * PGresAttDesc -- Data about a single attribute (column) of a query result
 * ----------------
 */
typedef struct pgresAttDesc
{
    char       *name;           /* column name */
    Oid         tableid;        /* source table, if known */
    int         columnid;       /* source column, if known */
    int         format;         /* format code for value (text/binary) */
    Oid         typid;          /* type id */
    int         typlen;         /* type size */
    int         atttypmod;      /* type-specific modifier info */
} PGresAttDesc;
 
/* ----------------
 * Exported functions of libpq
 * ----------------
 */
 
/* === in fe-connect.c === */
 
/* make a new client connection to the backend */
/* Asynchronous (non-blocking) */
extern PGconn *PQconnectStart(const char *conninfo);
extern PGconn *PQconnectStartParams(const char *const *keywords,
                                    const char *const *values, int expand_dbname);
extern PostgresPollingStatusType PQconnectPoll(PGconn *conn);
 
/* Synchronous (blocking) */
extern PGconn *PQconnectdb(const char *conninfo);
extern PGconn *PQconnectdbParams(const char *const *keywords,
                                 const char *const *values, int expand_dbname);
extern PGconn *PQsetdbLogin(const char *pghost, const char *pgport,
                            const char *pgoptions, const char *pgtty,
                            const char *dbName,
                            const char *login, const char *pwd);
 
#define PQsetdb(M_PGHOST,M_PGPORT,M_PGOPT,M_PGTTY,M_DBNAME)  \
    PQsetdbLogin(M_PGHOST, M_PGPORT, M_PGOPT, M_PGTTY, M_DBNAME, NULL, NULL)
 
/* close the current connection and free the PGconn data structure */
extern void PQfinish(PGconn *conn);
 
/* get info about connection options known to PQconnectdb */
extern PQconninfoOption *PQconndefaults(void);
 
/* parse connection options in same way as PQconnectdb */
extern PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
 
/* return the connection options used by a live connection */
extern PQconninfoOption *PQconninfo(PGconn *conn);
 
/* free the data structure returned by PQconndefaults() or PQconninfoParse() */
extern void PQconninfoFree(PQconninfoOption *connOptions);
 
/*
 * close the current connection and reestablish a new one with the same
 * parameters
 */
/* Asynchronous (non-blocking) */
extern int  PQresetStart(PGconn *conn);
extern PostgresPollingStatusType PQresetPoll(PGconn *conn);
 
/* Synchronous (blocking) */
extern void PQreset(PGconn *conn);
 
/* Create a PGcancelConn that's used to cancel a query on the given PGconn */
extern PGcancelConn *PQcancelCreate(PGconn *conn);
 
/* issue a cancel request in a non-blocking manner */
extern int  PQcancelStart(PGcancelConn *cancelConn);
 
/* issue a blocking cancel request */
extern int  PQcancelBlocking(PGcancelConn *cancelConn);
 
/* poll a non-blocking cancel request */
extern PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn);
extern ConnStatusType PQcancelStatus(const PGcancelConn *cancelConn);
extern int  PQcancelSocket(const PGcancelConn *cancelConn);
extern char *PQcancelErrorMessage(const PGcancelConn *cancelConn);
extern void PQcancelReset(PGcancelConn *cancelConn);
extern void PQcancelFinish(PGcancelConn *cancelConn);
 
 
/* request a cancel structure */
extern PGcancel *PQgetCancel(PGconn *conn);
 
/* free a cancel structure */
extern void PQfreeCancel(PGcancel *cancel);
 
/* deprecated version of PQcancelBlocking, but one which is signal-safe */
extern int  PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
 
/* deprecated version of PQcancel; not thread-safe */
extern int  PQrequestCancel(PGconn *conn);
 
/* Accessor functions for PGconn objects */
extern char *PQdb(const PGconn *conn);
extern char *PQuser(const PGconn *conn);
extern char *PQpass(const PGconn *conn);
extern char *PQhost(const PGconn *conn);
extern char *PQhostaddr(const PGconn *conn);
extern char *PQport(const PGconn *conn);
extern char *PQtty(const PGconn *conn);
extern char *PQoptions(const PGconn *conn);
extern ConnStatusType PQstatus(const PGconn *conn);
extern PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
extern const char *PQparameterStatus(const PGconn *conn,
                                     const char *paramName);
extern int  PQprotocolVersion(const PGconn *conn);
extern int  PQfullProtocolVersion(const PGconn *conn);
extern int  PQserverVersion(const PGconn *conn);
extern char *PQerrorMessage(const PGconn *conn);
extern int  PQsocket(const PGconn *conn);
extern int  PQbackendPID(const PGconn *conn);
extern PGpipelineStatus PQpipelineStatus(const PGconn *conn);
extern int  PQconnectionNeedsPassword(const PGconn *conn);
extern int  PQconnectionUsedPassword(const PGconn *conn);
extern int  PQconnectionUsedGSSAPI(const PGconn *conn);
extern int  PQclientEncoding(const PGconn *conn);
extern int  PQsetClientEncoding(PGconn *conn, const char *encoding);
 
/* SSL information functions */
extern int  PQsslInUse(PGconn *conn);
extern void *PQsslStruct(PGconn *conn, const char *struct_name);
extern const char *PQsslAttribute(PGconn *conn, const char *attribute_name);
extern const char *const *PQsslAttributeNames(PGconn *conn);
 
/*
 * Get the OpenSSL structure associated with a connection. Returns NULL for
 * unencrypted connections or if any other TLS library is in use.
 */
extern void *PQgetssl(PGconn *conn);
 
/* Tell libpq whether it needs to initialize OpenSSL */
extern void PQinitSSL(int do_init);
 
/* More detailed way to tell libpq whether it needs to initialize OpenSSL */
extern void PQinitOpenSSL(int do_ssl, int do_crypto);
 
/* Return true if GSSAPI encryption is in use */
extern int  PQgssEncInUse(PGconn *conn);
 
/* Returns GSSAPI context if GSSAPI is in use */
extern void *PQgetgssctx(PGconn *conn);
 
/* Set verbosity for PQerrorMessage and PQresultErrorMessage */
extern PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
 
/* Set CONTEXT visibility for PQerrorMessage and PQresultErrorMessage */
extern PGContextVisibility PQsetErrorContextVisibility(PGconn *conn,
                                                       PGContextVisibility show_context);
 
/* Override default notice handling routines */
extern PQnoticeReceiver PQsetNoticeReceiver(PGconn *conn,
                                            PQnoticeReceiver proc,
                                            void *arg);
extern PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn,
                                              PQnoticeProcessor proc,
                                              void *arg);
 
/*
 *     Used to set callback that prevents concurrent access to
 *     non-thread safe functions that libpq needs.
 *     The default implementation uses a libpq internal mutex.
 *     Only required for multithreaded apps that use Kerberos or
 *     older (non-threadsafe) versions of Curl both within their
 *     app and for postgresql connections.
 */
typedef void (*pgthreadlock_t) (int acquire);
 
extern pgthreadlock_t PQregisterThreadLock(pgthreadlock_t newhandler);
extern pgthreadlock_t PQgetThreadLock(void);
 
/* === in fe-trace.c === */
extern void PQtrace(PGconn *conn, FILE *debug_port);
extern void PQuntrace(PGconn *conn);
 
/* flags controlling trace output: */
/* omit timestamps from each line */
#define PQTRACE_SUPPRESS_TIMESTAMPS     (1<<0)
/* redact portions of some messages, for testing frameworks */
#define PQTRACE_REGRESS_MODE            (1<<1)
extern void PQsetTraceFlags(PGconn *conn, int flags);
 
/* === in fe-exec.c === */
 
/* Simple synchronous query */
extern PGresult *PQexec(PGconn *conn, const char *query);
extern PGresult *PQexecParams(PGconn *conn,
                              const char *command,
                              int nParams,
                              const Oid *paramTypes,
                              const char *const *paramValues,
                              const int *paramLengths,
                              const int *paramFormats,
                              int resultFormat);
extern PGresult *PQprepare(PGconn *conn, const char *stmtName,
                           const char *query, int nParams,
                           const Oid *paramTypes);
extern PGresult *PQexecPrepared(PGconn *conn,
                                const char *stmtName,
                                int nParams,
                                const char *const *paramValues,
                                const int *paramLengths,
                                const int *paramFormats,
                                int resultFormat);
 
/* Interface for multiple-result or asynchronous queries */
#define PQ_QUERY_PARAM_MAX_LIMIT 65535
 
extern int  PQsendQuery(PGconn *conn, const char *query);
extern int  PQsendQueryParams(PGconn *conn,
                              const char *command,
                              int nParams,
                              const Oid *paramTypes,
                              const char *const *paramValues,
                              const int *paramLengths,
                              const int *paramFormats,
                              int resultFormat);
extern int  PQsendPrepare(PGconn *conn, const char *stmtName,
                          const char *query, int nParams,
                          const Oid *paramTypes);
extern int  PQsendQueryPrepared(PGconn *conn,
                                const char *stmtName,
                                int nParams,
                                const char *const *paramValues,
                                const int *paramLengths,
                                const int *paramFormats,
                                int resultFormat);
extern int  PQsetSingleRowMode(PGconn *conn);
extern int  PQsetChunkedRowsMode(PGconn *conn, int chunkSize);
extern PGresult *PQgetResult(PGconn *conn);
 
/* Routines for managing an asynchronous query */
extern int  PQisBusy(PGconn *conn);
extern int  PQconsumeInput(PGconn *conn);
 
/* Routines for pipeline mode management */
extern int  PQenterPipelineMode(PGconn *conn);
extern int  PQexitPipelineMode(PGconn *conn);
extern int  PQpipelineSync(PGconn *conn);
extern int  PQsendFlushRequest(PGconn *conn);
extern int  PQsendPipelineSync(PGconn *conn);
 
/* LISTEN/NOTIFY support */
extern PGnotify *PQnotifies(PGconn *conn);
 
/* Routines for copy in/out */
extern int  PQputCopyData(PGconn *conn, const char *buffer, int nbytes);
extern int  PQputCopyEnd(PGconn *conn, const char *errormsg);
extern int  PQgetCopyData(PGconn *conn, char **buffer, int async);
 
/* Deprecated routines for copy in/out */
extern int  PQgetline(PGconn *conn, char *buffer, int length);
extern int  PQputline(PGconn *conn, const char *string);
extern int  PQgetlineAsync(PGconn *conn, char *buffer, int bufsize);
extern int  PQputnbytes(PGconn *conn, const char *buffer, int nbytes);
extern int  PQendcopy(PGconn *conn);
 
/* Set blocking/nonblocking connection to the backend */
extern int  PQsetnonblocking(PGconn *conn, int arg);
extern int  PQisnonblocking(const PGconn *conn);
extern int  PQisthreadsafe(void);
extern PGPing PQping(const char *conninfo);
extern PGPing PQpingParams(const char *const *keywords,
                           const char *const *values, int expand_dbname);
 
/* Force the write buffer to be written (or at least try) */
extern int  PQflush(PGconn *conn);
 
/*
 * "Fast path" interface --- not really recommended for application
 * use
 */
extern PGresult *PQfn(PGconn *conn,
                      int fnid,
                      int *result_buf,
                      int *result_len,
                      int result_is_int,
                      const PQArgBlock *args,
                      int nargs);
 
/* Accessor functions for PGresult objects */
extern ExecStatusType PQresultStatus(const PGresult *res);
extern char *PQresStatus(ExecStatusType status);
extern char *PQresultErrorMessage(const PGresult *res);
extern char *PQresultVerboseErrorMessage(const PGresult *res,
                                         PGVerbosity verbosity,
                                         PGContextVisibility show_context);
extern char *PQresultErrorField(const PGresult *res, int fieldcode);
extern int  PQntuples(const PGresult *res);
extern int  PQnfields(const PGresult *res);
extern int  PQbinaryTuples(const PGresult *res);
extern char *PQfname(const PGresult *res, int field_num);
extern int  PQfnumber(const PGresult *res, const char *field_name);
extern Oid  PQftable(const PGresult *res, int field_num);
extern int  PQftablecol(const PGresult *res, int field_num);
extern int  PQfformat(const PGresult *res, int field_num);
extern Oid  PQftype(const PGresult *res, int field_num);
extern int  PQfsize(const PGresult *res, int field_num);
extern int  PQfmod(const PGresult *res, int field_num);
extern char *PQcmdStatus(PGresult *res);
extern char *PQoidStatus(const PGresult *res);  /* old and ugly */
extern Oid  PQoidValue(const PGresult *res);    /* new and improved */
extern char *PQcmdTuples(PGresult *res);
extern char *PQgetvalue(const PGresult *res, int tup_num, int field_num);
extern int  PQgetlength(const PGresult *res, int tup_num, int field_num);
extern int  PQgetisnull(const PGresult *res, int tup_num, int field_num);
extern int  PQnparams(const PGresult *res);
extern Oid  PQparamtype(const PGresult *res, int param_num);
 
/* Describe prepared statements and portals */
extern PGresult *PQdescribePrepared(PGconn *conn, const char *stmt);
extern PGresult *PQdescribePortal(PGconn *conn, const char *portal);
extern int  PQsendDescribePrepared(PGconn *conn, const char *stmt);
extern int  PQsendDescribePortal(PGconn *conn, const char *portal);
 
/* Close prepared statements and portals */
extern PGresult *PQclosePrepared(PGconn *conn, const char *stmt);
extern PGresult *PQclosePortal(PGconn *conn, const char *portal);
extern int  PQsendClosePrepared(PGconn *conn, const char *stmt);
extern int  PQsendClosePortal(PGconn *conn, const char *portal);
 
/* Delete a PGresult */
extern void PQclear(PGresult *res);
 
/* For freeing other alloc'd results, such as PGnotify structs */
extern void PQfreemem(void *ptr);
 
/* Exists for backward compatibility.  bjm 2003-03-24 */
#define PQfreeNotify(ptr) PQfreemem(ptr)
 
/* Error when no password was given. */
/* Note: depending on this is deprecated; use PQconnectionNeedsPassword(). */
#define PQnoPasswordSupplied    "fe_sendauth: no password supplied\n"
 
/* Create and manipulate PGresults */
extern PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
extern PGresult *PQcopyResult(const PGresult *src, int flags);
extern int  PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
extern void *PQresultAlloc(PGresult *res, size_t nBytes);
extern size_t PQresultMemorySize(const PGresult *res);
extern int  PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
 
/* Quoting strings before inclusion in queries. */
extern size_t PQescapeStringConn(PGconn *conn,
                                 char *to, const char *from, size_t length,
                                 int *error);
extern char *PQescapeLiteral(PGconn *conn, const char *str, size_t len);
extern char *PQescapeIdentifier(PGconn *conn, const char *str, size_t len);
extern unsigned char *PQescapeByteaConn(PGconn *conn,
                                        const unsigned char *from, size_t from_length,
                                        size_t *to_length);
extern unsigned char *PQunescapeBytea(const unsigned char *strtext,
                                      size_t *retbuflen);
 
/* These forms are deprecated! */
extern size_t PQescapeString(char *to, const char *from, size_t length);
extern unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length,
                                    size_t *to_length);
 
 
 
/* === in fe-print.c === */
 
extern void PQprint(FILE *fout, /* output stream */
                    const PGresult *res,
                    const PQprintOpt *po);  /* option structure */
 
/*
 * really old printing routines
 */
extern void PQdisplayTuples(const PGresult *res,
                            FILE *fp,   /* where to send the output */
                            int fillAlign,  /* pad the fields with spaces */
                            const char *fieldSep,   /* field separator */
                            int printHeader,    /* display headers? */
                            int quiet);
 
extern void PQprintTuples(const PGresult *res,
                          FILE *fout,   /* output stream */
                          int PrintAttNames,    /* print attribute names */
                          int TerseOutput,  /* delimiter bars */
                          int colWidth);    /* width of column, if 0, use
                                             * variable width */
 
 
/* === in fe-lobj.c === */
 
/* Large-object access routines */
extern int  lo_open(PGconn *conn, Oid lobjId, int mode);
extern int  lo_close(PGconn *conn, int fd);
extern int  lo_read(PGconn *conn, int fd, char *buf, size_t len);
extern int  lo_write(PGconn *conn, int fd, const char *buf, size_t len);
extern int  lo_lseek(PGconn *conn, int fd, int offset, int whence);
extern int64_t lo_lseek64(PGconn *conn, int fd, int64_t offset, int whence);
extern Oid  lo_creat(PGconn *conn, int mode);
extern Oid  lo_create(PGconn *conn, Oid lobjId);
extern int  lo_tell(PGconn *conn, int fd);
extern int64_t lo_tell64(PGconn *conn, int fd);
extern int  lo_truncate(PGconn *conn, int fd, size_t len);
extern int  lo_truncate64(PGconn *conn, int fd, int64_t len);
extern int  lo_unlink(PGconn *conn, Oid lobjId);
extern Oid  lo_import(PGconn *conn, const char *filename);
extern Oid  lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);
extern int  lo_export(PGconn *conn, Oid lobjId, const char *filename);
 
/* === in fe-misc.c === */
 
/* Get the version of the libpq library in use */
extern int  PQlibVersion(void);
 
/* Poll a socket for reading and/or writing with an optional timeout */
extern int  PQsocketPoll(int sock, int forRead, int forWrite,
                         pg_usec_time_t end_time);
 
/* Get current time in the form PQsocketPoll wants */
extern pg_usec_time_t PQgetCurrentTimeUSec(void);
 
/* Determine length of multibyte encoded char at *s */
extern int  PQmblen(const char *s, int encoding);
 
/* Same, but not more than the distance to the end of string s */
extern int  PQmblenBounded(const char *s, int encoding);
 
/* Determine display length of multibyte encoded char at *s */
extern int  PQdsplen(const char *s, int encoding);
 
/* Get encoding id from environment variable PGCLIENTENCODING */
extern int  PQenv2encoding(void);
 
/* === in fe-auth.c === */
 
/* Authdata for PQAUTHDATA_PROMPT_OAUTH_DEVICE */
typedef struct _PGpromptOAuthDevice
{
    const char *verification_uri;   /* verification URI to visit */
    const char *user_code;      /* user code to enter */
    const char *verification_uri_complete;  /* optional combination of URI and
                                             * code, or NULL */
    int         expires_in;     /* seconds until user code expires */
} PGpromptOAuthDevice;
 
/*
 * For PGoauthBearerRequest.async(). This macro just allows clients to avoid
 * depending on libpq-int.h or Winsock for the "socket" type; it's undefined
 * immediately below.
 */
#ifdef _WIN32
#define PQ_SOCKTYPE uintptr_t   /* avoids depending on winsock2.h for SOCKET */
#else
#define PQ_SOCKTYPE int
#endif
 
/* Authdata for PQAUTHDATA_OAUTH_BEARER_TOKEN */
typedef struct PGoauthBearerRequest
{
    /* Hook inputs (constant across all calls) */
    const char *openid_configuration;   /* OIDC discovery URI */
    const char *scope;          /* required scope(s), or NULL */
 
    /* Hook outputs */
 
    /*---------
     * Callback implementing a custom asynchronous OAuth flow.
     *
     * The callback may return
     * - PGRES_POLLING_READING/WRITING, to indicate that a socket descriptor
     *   has been stored in *altsock and libpq should wait until it is
     *   readable or writable before calling back;
     * - PGRES_POLLING_OK, to indicate that the flow is complete and
     *   request->token has been set; or
     * - PGRES_POLLING_FAILED, to indicate that token retrieval has failed.
     *
     * This callback is optional. If the token can be obtained without
     * blocking during the original call to the PQAUTHDATA_OAUTH_BEARER_TOKEN
     * hook, it may be returned directly, but one of request->async or
     * request->token must be set by the hook.
     *
     * The (PQ_SOCKTYPE *) in the signature is a placeholder for the platform's
     * native socket type: (SOCKET *) on Windows, and (int *) everywhere else.
     */
    PostgresPollingStatusType (*async) (PGconn *conn,
                                        struct PGoauthBearerRequest *request,
                                        PQ_SOCKTYPE * altsock);
 
    /*
     * Callback to clean up custom allocations. A hook implementation may use
     * this to free request->token and any resources in request->user. V2
     * implementations should additionally free request->error, if set.
     *
     * This is technically optional, but highly recommended, because there is
     * no other indication as to when it is safe to free the token.
     */
    void        (*cleanup) (PGconn *conn, struct PGoauthBearerRequest *request);
 
    /*
     * The hook should set this to the Bearer token contents for the
     * connection, once the flow is completed.  The token contents must remain
     * available to libpq until the hook's cleanup callback is called.
     */
    char       *token;
 
    /*
     * Hook-defined data. libpq will not modify this pointer across calls to
     * the async callback, so it can be used to keep track of
     * application-specific state. Resources allocated here should be freed by
     * the cleanup callback.
     */
    void       *user;
} PGoauthBearerRequest;
 
#undef PQ_SOCKTYPE
 
/* Authdata for PQAUTHDATA_OAUTH_BEARER_TOKEN_V2 */
typedef struct
{
    PGoauthBearerRequest v1;    /* see the PGoauthBearerRequest struct, above */
 
    /* Hook inputs (constant across all calls) */
    const char *issuer;         /* the issuer identifier (RFC 9207) in use, as
                                 * derived from the connection's oauth_issuer */
 
    /* Hook outputs */
 
    /*
     * Hook-defined error message which will be included in the connection's
     * PQerrorMessage() output when the flow fails. libpq does not take
     * ownership of this pointer; any allocations should be freed during the
     * cleanup callback.
     */
    const char *error;
} PGoauthBearerRequestV2;
 
extern char *PQencryptPassword(const char *passwd, const char *user);
extern char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);
extern PGresult *PQchangePassword(PGconn *conn, const char *user, const char *passwd);
 
typedef int (*PQauthDataHook_type) (PGauthData type, PGconn *conn, void *data);
extern void PQsetAuthDataHook(PQauthDataHook_type hook);
extern PQauthDataHook_type PQgetAuthDataHook(void);
extern int  PQdefaultAuthDataHook(PGauthData type, PGconn *conn, void *data);
 
/* === in encnames.c === */
 
extern int  pg_char_to_encoding(const char *name);
extern const char *pg_encoding_to_char(int encoding);
extern int  pg_valid_server_encoding_id(int encoding);
 
/* === in fe-secure-openssl.c === */
 
/* Support for overriding sslpassword handling with a callback */
typedef int (*PQsslKeyPassHook_OpenSSL_type) (char *buf, int size, PGconn *conn);
extern PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
extern void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
extern int  PQdefaultSSLKeyPassHook_OpenSSL(char *buf, int size, PGconn *conn);
 
#ifdef __cplusplus
}
#endif
 
#endif                          /* LIBPQ_FE_H */