1 /*------------------------------------------------------------------------- 2 * 3 * libpq-int.h 4 * This file contains internal definitions meant to be used only by 5 * the frontend libpq library, not by applications that call it. 6 * 7 * An application can include this file if it wants to bypass the 8 * official API defined by libpq-fe.h, but code that does so is much 9 * more likely to break across PostgreSQL releases than code that uses 10 * only the official API. 11 * 12 * Portions Copyright (c) 1996-2021, PostgreSQL Global Development Group 13 * Portions Copyright (c) 1994, Regents of the University of California 14 * 15 * src/interfaces/libpq/libpq-int.h 16 * 17 *------------------------------------------------------------------------- 18 */ 19 20 #ifndef LIBPQ_INT_H 21 #define LIBPQ_INT_H 22 23 /* We assume libpq-fe.h has already been included. */ 24 #include "libpq-events.h" 25 26 #include <time.h> 27 #ifndef WIN32 28 #include <sys/time.h> 29 #endif 30 31 #ifdef ENABLE_THREAD_SAFETY 32 #ifdef WIN32 33 #include "pthread-win32.h" 34 #else 35 #include <pthread.h> 36 #endif 37 #include <signal.h> 38 #endif 39 40 /* include stuff common to fe and be */ 41 #include "getaddrinfo.h" 42 #include "libpq/pqcomm.h" 43 /* include stuff found in fe only */ 44 #include "pqexpbuffer.h" 45 46 #ifdef ENABLE_GSS 47 #if defined(HAVE_GSSAPI_H) 48 #include <gssapi.h> 49 #else 50 #include <gssapi/gssapi.h> 51 #endif 52 #endif 53 54 #ifdef ENABLE_SSPI 55 #define SECURITY_WIN32 56 #if defined(WIN32) && !defined(_MSC_VER) 57 #include <ntsecapi.h> 58 #endif 59 #include <security.h> 60 #undef SECURITY_WIN32 61 62 #ifndef ENABLE_GSS 63 /* 64 * Define a fake structure compatible with GSSAPI on Unix. 65 */ 66 typedef struct 67 { 68 void *value; 69 int length; 70 } gss_buffer_desc; 71 #endif 72 #endif /* ENABLE_SSPI */ 73 74 #ifdef USE_OPENSSL 75 #include <openssl/ssl.h> 76 #include <openssl/err.h> 77 78 #ifndef OPENSSL_NO_ENGINE 79 #define USE_SSL_ENGINE 80 #endif 81 #endif /* USE_OPENSSL */ 82 83 /* 84 * POSTGRES backend dependent Constants. 85 */ 86 #define CMDSTATUS_LEN 64 /* should match COMPLETION_TAG_BUFSIZE */ 87 88 /* 89 * PGresult and the subsidiary types PGresAttDesc, PGresAttValue 90 * represent the result of a query (or more precisely, of a single SQL 91 * command --- a query string given to PQexec can contain multiple commands). 92 * Note we assume that a single command can return at most one tuple group, 93 * hence there is no need for multiple descriptor sets. 94 */ 95 96 /* Subsidiary-storage management structure for PGresult. 97 * See space management routines in fe-exec.c for details. 98 * Note that space[k] refers to the k'th byte starting from the physical 99 * head of the block --- it's a union, not a struct! 100 */ 101 typedef union pgresult_data PGresult_data; 102 103 union pgresult_data 104 { 105 PGresult_data *next; /* link to next block, or NULL */ 106 char space[1]; /* dummy for accessing block as bytes */ 107 }; 108 109 /* Data about a single parameter of a prepared statement */ 110 typedef struct pgresParamDesc 111 { 112 Oid typid; /* type id */ 113 } PGresParamDesc; 114 115 /* 116 * Data for a single attribute of a single tuple 117 * 118 * We use char* for Attribute values. 119 * 120 * The value pointer always points to a null-terminated area; we add a 121 * null (zero) byte after whatever the backend sends us. This is only 122 * particularly useful for text values ... with a binary value, the 123 * value might have embedded nulls, so the application can't use C string 124 * operators on it. But we add a null anyway for consistency. 125 * Note that the value itself does not contain a length word. 126 * 127 * A NULL attribute is a special case in two ways: its len field is NULL_LEN 128 * and its value field points to null_field in the owning PGresult. All the 129 * NULL attributes in a query result point to the same place (there's no need 130 * to store a null string separately for each one). 131 */ 132 133 #define NULL_LEN (-1) /* pg_result len for NULL value */ 134 135 typedef struct pgresAttValue 136 { 137 int len; /* length in bytes of the value */ 138 char *value; /* actual value, plus terminating zero byte */ 139 } PGresAttValue; 140 141 /* Typedef for message-field list entries */ 142 typedef struct pgMessageField 143 { 144 struct pgMessageField *next; /* list link */ 145 char code; /* field code */ 146 char contents[FLEXIBLE_ARRAY_MEMBER]; /* value, nul-terminated */ 147 } PGMessageField; 148 149 /* Fields needed for notice handling */ 150 typedef struct 151 { 152 PQnoticeReceiver noticeRec; /* notice message receiver */ 153 void *noticeRecArg; 154 PQnoticeProcessor noticeProc; /* notice message processor */ 155 void *noticeProcArg; 156 } PGNoticeHooks; 157 158 typedef struct PGEvent 159 { 160 PGEventProc proc; /* the function to call on events */ 161 char *name; /* used only for error messages */ 162 void *passThrough; /* pointer supplied at registration time */ 163 void *data; /* optional state (instance) data */ 164 bool resultInitialized; /* T if RESULTCREATE/COPY succeeded */ 165 } PGEvent; 166 167 struct pg_result 168 { 169 int ntups; 170 int numAttributes; 171 PGresAttDesc *attDescs; 172 PGresAttValue **tuples; /* each PGresult tuple is an array of 173 * PGresAttValue's */ 174 int tupArrSize; /* allocated size of tuples array */ 175 int numParameters; 176 PGresParamDesc *paramDescs; 177 ExecStatusType resultStatus; 178 char cmdStatus[CMDSTATUS_LEN]; /* cmd status from the query */ 179 int binary; /* binary tuple values if binary == 1, 180 * otherwise text */ 181 182 /* 183 * These fields are copied from the originating PGconn, so that operations 184 * on the PGresult don't have to reference the PGconn. 185 */ 186 PGNoticeHooks noticeHooks; 187 PGEvent *events; 188 int nEvents; 189 int client_encoding; /* encoding id */ 190 191 /* 192 * Error information (all NULL if not an error result). errMsg is the 193 * "overall" error message returned by PQresultErrorMessage. If we have 194 * per-field info then it is stored in a linked list. 195 */ 196 char *errMsg; /* error message, or NULL if no error */ 197 PGMessageField *errFields; /* message broken into fields */ 198 char *errQuery; /* text of triggering query, if available */ 199 200 /* All NULL attributes in the query result point to this null string */ 201 char null_field[1]; 202 203 /* 204 * Space management information. Note that attDescs and error stuff, if 205 * not null, point into allocated blocks. But tuples points to a 206 * separately malloc'd block, so that we can realloc it. 207 */ 208 PGresult_data *curBlock; /* most recently allocated block */ 209 int curOffset; /* start offset of free space in block */ 210 int spaceLeft; /* number of free bytes remaining in block */ 211 212 size_t memorySize; /* total space allocated for this PGresult */ 213 }; 214 215 /* PGAsyncStatusType defines the state of the query-execution state machine */ 216 typedef enum 217 { 218 PGASYNC_IDLE, /* nothing's happening, dude */ 219 PGASYNC_BUSY, /* query in progress */ 220 PGASYNC_READY, /* query done, waiting for client to fetch 221 * result */ 222 PGASYNC_READY_MORE, /* query done, waiting for client to fetch 223 * result, more results expected from this 224 * query */ 225 PGASYNC_COPY_IN, /* Copy In data transfer in progress */ 226 PGASYNC_COPY_OUT, /* Copy Out data transfer in progress */ 227 PGASYNC_COPY_BOTH /* Copy In/Out data transfer in progress */ 228 } PGAsyncStatusType; 229 230 /* Target server type (decoded value of target_session_attrs) */ 231 typedef enum 232 { 233 SERVER_TYPE_ANY = 0, /* Any server (default) */ 234 SERVER_TYPE_READ_WRITE, /* Read-write server */ 235 SERVER_TYPE_READ_ONLY, /* Read-only server */ 236 SERVER_TYPE_PRIMARY, /* Primary server */ 237 SERVER_TYPE_STANDBY, /* Standby server */ 238 SERVER_TYPE_PREFER_STANDBY, /* Prefer standby server */ 239 SERVER_TYPE_PREFER_STANDBY_PASS2 /* second pass - behaves same as ANY */ 240 } PGTargetServerType; 241 242 /* Boolean value plus a not-known state, for GUCs we might have to fetch */ 243 typedef enum 244 { 245 PG_BOOL_UNKNOWN = 0, /* Currently unknown */ 246 PG_BOOL_YES, /* Yes (true) */ 247 PG_BOOL_NO /* No (false) */ 248 } PGTernaryBool; 249 250 /* Typedef for the EnvironmentOptions[] array */ 251 typedef struct PQEnvironmentOption 252 { 253 const char *envName, /* name of an environment variable */ 254 *pgName; /* name of corresponding SET variable */ 255 } PQEnvironmentOption; 256 257 /* Typedef for parameter-status list entries */ 258 typedef struct pgParameterStatus 259 { 260 struct pgParameterStatus *next; /* list link */ 261 char *name; /* parameter name */ 262 char *value; /* parameter value */ 263 /* Note: name and value are stored in same malloc block as struct is */ 264 } pgParameterStatus; 265 266 /* large-object-access data ... allocated only if large-object code is used. */ 267 typedef struct pgLobjfuncs 268 { 269 Oid fn_lo_open; /* OID of backend function lo_open */ 270 Oid fn_lo_close; /* OID of backend function lo_close */ 271 Oid fn_lo_creat; /* OID of backend function lo_creat */ 272 Oid fn_lo_create; /* OID of backend function lo_create */ 273 Oid fn_lo_unlink; /* OID of backend function lo_unlink */ 274 Oid fn_lo_lseek; /* OID of backend function lo_lseek */ 275 Oid fn_lo_lseek64; /* OID of backend function lo_lseek64 */ 276 Oid fn_lo_tell; /* OID of backend function lo_tell */ 277 Oid fn_lo_tell64; /* OID of backend function lo_tell64 */ 278 Oid fn_lo_truncate; /* OID of backend function lo_truncate */ 279 Oid fn_lo_truncate64; /* OID of function lo_truncate64 */ 280 Oid fn_lo_read; /* OID of backend function LOread */ 281 Oid fn_lo_write; /* OID of backend function LOwrite */ 282 } PGlobjfuncs; 283 284 /* PGdataValue represents a data field value being passed to a row processor. 285 * It could be either text or binary data; text data is not zero-terminated. 286 * A SQL NULL is represented by len < 0; then value is still valid but there 287 * are no data bytes there. 288 */ 289 typedef struct pgDataValue 290 { 291 int len; /* data length in bytes, or <0 if NULL */ 292 const char *value; /* data value, without zero-termination */ 293 } PGdataValue; 294 295 /* Host address type enum for struct pg_conn_host */ 296 typedef enum pg_conn_host_type 297 { 298 CHT_HOST_NAME, 299 CHT_HOST_ADDRESS, 300 CHT_UNIX_SOCKET 301 } pg_conn_host_type; 302 303 /* 304 * PGQueryClass tracks which query protocol is in use for each command queue 305 * entry, or special operation in execution 306 */ 307 typedef enum 308 { 309 PGQUERY_SIMPLE, /* simple Query protocol (PQexec) */ 310 PGQUERY_EXTENDED, /* full Extended protocol (PQexecParams) */ 311 PGQUERY_PREPARE, /* Parse only (PQprepare) */ 312 PGQUERY_DESCRIBE, /* Describe Statement or Portal */ 313 PGQUERY_SYNC /* Sync (at end of a pipeline) */ 314 } PGQueryClass; 315 316 /* 317 * An entry in the pending command queue. 318 */ 319 typedef struct PGcmdQueueEntry 320 { 321 PGQueryClass queryclass; /* Query type */ 322 char *query; /* SQL command, or NULL if none/unknown/OOM */ 323 struct PGcmdQueueEntry *next; /* list link */ 324 } PGcmdQueueEntry; 325 326 /* 327 * pg_conn_host stores all information about each of possibly several hosts 328 * mentioned in the connection string. Most fields are derived by splitting 329 * the relevant connection parameter (e.g., pghost) at commas. 330 */ 331 typedef struct pg_conn_host 332 { 333 pg_conn_host_type type; /* type of host address */ 334 char *host; /* host name or socket path */ 335 char *hostaddr; /* host numeric IP address */ 336 char *port; /* port number (always provided) */ 337 char *password; /* password for this host, read from the 338 * password file; NULL if not sought or not 339 * found in password file. */ 340 } pg_conn_host; 341 342 /* 343 * PGconn stores all the state data associated with a single connection 344 * to a backend. 345 */ 346 struct pg_conn 347 { 348 /* Saved values of connection options */ 349 char *pghost; /* the machine on which the server is running, 350 * or a path to a UNIX-domain socket, or a 351 * comma-separated list of machines and/or 352 * paths; if NULL, use DEFAULT_PGSOCKET_DIR */ 353 char *pghostaddr; /* the numeric IP address of the machine on 354 * which the server is running, or a 355 * comma-separated list of same. Takes 356 * precedence over pghost. */ 357 char *pgport; /* the server's communication port number, or 358 * a comma-separated list of ports */ 359 char *connect_timeout; /* connection timeout (numeric string) */ 360 char *pgtcp_user_timeout; /* tcp user timeout (numeric string) */ 361 char *client_encoding_initial; /* encoding to use */ 362 char *pgoptions; /* options to start the backend with */ 363 char *appname; /* application name */ 364 char *fbappname; /* fallback application name */ 365 char *dbName; /* database name */ 366 char *replication; /* connect as the replication standby? */ 367 char *pguser; /* Postgres username and password, if any */ 368 char *pgpass; 369 char *pgpassfile; /* path to a file containing password(s) */ 370 char *channel_binding; /* channel binding mode 371 * (require,prefer,disable) */ 372 char *keepalives; /* use TCP keepalives? */ 373 char *keepalives_idle; /* time between TCP keepalives */ 374 char *keepalives_interval; /* time between TCP keepalive 375 * retransmits */ 376 char *keepalives_count; /* maximum number of TCP keepalive 377 * retransmits */ 378 char *sslmode; /* SSL mode (require,prefer,allow,disable) */ 379 char *sslcompression; /* SSL compression (0 or 1) */ 380 char *sslkey; /* client key filename */ 381 char *sslcert; /* client certificate filename */ 382 char *sslpassword; /* client key file password */ 383 char *sslrootcert; /* root certificate filename */ 384 char *sslcrl; /* certificate revocation list filename */ 385 char *sslcrldir; /* certificate revocation list directory name */ 386 char *sslsni; /* use SSL SNI extension (0 or 1) */ 387 char *requirepeer; /* required peer credentials for local sockets */ 388 char *gssencmode; /* GSS mode (require,prefer,disable) */ 389 char *krbsrvname; /* Kerberos service name */ 390 char *gsslib; /* What GSS library to use ("gssapi" or 391 * "sspi") */ 392 char *ssl_min_protocol_version; /* minimum TLS protocol version */ 393 char *ssl_max_protocol_version; /* maximum TLS protocol version */ 394 char *target_session_attrs; /* desired session properties */ 395 396 /* Optional file to write trace info to */ 397 FILE *Pfdebug; 398 int traceFlags; 399 400 /* Callback procedures for notice message processing */ 401 PGNoticeHooks noticeHooks; 402 403 /* Event procs registered via PQregisterEventProc */ 404 PGEvent *events; /* expandable array of event data */ 405 int nEvents; /* number of active events */ 406 int eventArraySize; /* allocated array size */ 407 408 /* Status indicators */ 409 ConnStatusType status; 410 PGAsyncStatusType asyncStatus; 411 PGTransactionStatusType xactStatus; /* never changes to ACTIVE */ 412 char last_sqlstate[6]; /* last reported SQLSTATE */ 413 bool options_valid; /* true if OK to attempt connection */ 414 bool nonblocking; /* whether this connection is using nonblock 415 * sending semantics */ 416 PGpipelineStatus pipelineStatus; /* status of pipeline mode */ 417 bool singleRowMode; /* return current query result row-by-row? */ 418 char copy_is_binary; /* 1 = copy binary, 0 = copy text */ 419 int copy_already_done; /* # bytes already returned in COPY OUT */ 420 PGnotify *notifyHead; /* oldest unreported Notify msg */ 421 PGnotify *notifyTail; /* newest unreported Notify msg */ 422 423 /* Support for multiple hosts in connection string */ 424 int nconnhost; /* # of hosts named in conn string */ 425 int whichhost; /* host we're currently trying/connected to */ 426 pg_conn_host *connhost; /* details about each named host */ 427 char *connip; /* IP address for current network connection */ 428 429 /* 430 * The pending command queue as a singly-linked list. Head is the command 431 * currently in execution, tail is where new commands are added. 432 */ 433 PGcmdQueueEntry *cmd_queue_head; 434 PGcmdQueueEntry *cmd_queue_tail; 435 436 /* 437 * To save malloc traffic, we don't free entries right away; instead we 438 * save them in this list for possible reuse. 439 */ 440 PGcmdQueueEntry *cmd_queue_recycle; 441 442 /* Connection data */ 443 pgsocket sock; /* FD for socket, PGINVALID_SOCKET if 444 * unconnected */ 445 SockAddr laddr; /* Local address */ 446 SockAddr raddr; /* Remote address */ 447 ProtocolVersion pversion; /* FE/BE protocol version in use */ 448 int sversion; /* server version, e.g. 70401 for 7.4.1 */ 449 bool auth_req_received; /* true if any type of auth req received */ 450 bool password_needed; /* true if server demanded a password */ 451 bool sigpipe_so; /* have we masked SIGPIPE via SO_NOSIGPIPE? */ 452 bool sigpipe_flag; /* can we mask SIGPIPE via MSG_NOSIGNAL? */ 453 bool write_failed; /* have we had a write failure on sock? */ 454 char *write_err_msg; /* write error message, or NULL if OOM */ 455 456 /* Transient state needed while establishing connection */ 457 PGTargetServerType target_server_type; /* desired session properties */ 458 bool try_next_addr; /* time to advance to next address/host? */ 459 bool try_next_host; /* time to advance to next connhost[]? */ 460 struct addrinfo *addrlist; /* list of addresses for current connhost */ 461 struct addrinfo *addr_cur; /* the one currently being tried */ 462 int addrlist_family; /* needed to know how to free addrlist */ 463 bool send_appname; /* okay to send application_name? */ 464 465 /* Miscellaneous stuff */ 466 int be_pid; /* PID of backend --- needed for cancels */ 467 int be_key; /* key of backend --- needed for cancels */ 468 pgParameterStatus *pstatus; /* ParameterStatus data */ 469 int client_encoding; /* encoding id */ 470 bool std_strings; /* standard_conforming_strings */ 471 PGTernaryBool default_transaction_read_only; /* default_transaction_read_only */ 472 PGTernaryBool in_hot_standby; /* in_hot_standby */ 473 PGVerbosity verbosity; /* error/notice message verbosity */ 474 PGContextVisibility show_context; /* whether to show CONTEXT field */ 475 PGlobjfuncs *lobjfuncs; /* private state for large-object access fns */ 476 477 /* Buffer for data received from backend and not yet processed */ 478 char *inBuffer; /* currently allocated buffer */ 479 int inBufSize; /* allocated size of buffer */ 480 int inStart; /* offset to first unconsumed data in buffer */ 481 int inCursor; /* next byte to tentatively consume */ 482 int inEnd; /* offset to first position after avail data */ 483 484 /* Buffer for data not yet sent to backend */ 485 char *outBuffer; /* currently allocated buffer */ 486 int outBufSize; /* allocated size of buffer */ 487 int outCount; /* number of chars waiting in buffer */ 488 489 /* State for constructing messages in outBuffer */ 490 int outMsgStart; /* offset to msg start (length word); if -1, 491 * msg has no length word */ 492 int outMsgEnd; /* offset to msg end (so far) */ 493 494 /* Row processor interface workspace */ 495 PGdataValue *rowBuf; /* array for passing values to rowProcessor */ 496 int rowBufLen; /* number of entries allocated in rowBuf */ 497 498 /* Status for asynchronous result construction */ 499 PGresult *result; /* result being constructed */ 500 PGresult *next_result; /* next result (used in single-row mode) */ 501 502 /* Assorted state for SASL, SSL, GSS, etc */ 503 void *sasl_state; 504 505 /* SSL structures */ 506 bool ssl_in_use; 507 508 #ifdef USE_SSL 509 bool allow_ssl_try; /* Allowed to try SSL negotiation */ 510 bool wait_ssl_try; /* Delay SSL negotiation until after 511 * attempting normal connection */ 512 #ifdef USE_OPENSSL 513 SSL *ssl; /* SSL status, if have SSL connection */ 514 X509 *peer; /* X509 cert of server */ 515 #ifdef USE_SSL_ENGINE 516 ENGINE *engine; /* SSL engine, if any */ 517 #else 518 void *engine; /* dummy field to keep struct the same if 519 * OpenSSL version changes */ 520 #endif 521 bool crypto_loaded; /* Track if libcrypto locking callbacks have 522 * been done for this connection. This can be 523 * removed once support for OpenSSL 1.0.2 is 524 * removed as this locking is handled 525 * internally in OpenSSL >= 1.1.0. */ 526 #endif /* USE_OPENSSL */ 527 #endif /* USE_SSL */ 528 529 #ifdef ENABLE_GSS 530 gss_ctx_id_t gctx; /* GSS context */ 531 gss_name_t gtarg_nam; /* GSS target name */ 532 533 /* The following are encryption-only */ 534 bool try_gss; /* GSS attempting permitted */ 535 bool gssenc; /* GSS encryption is usable */ 536 gss_cred_id_t gcred; /* GSS credential temp storage. */ 537 538 /* GSS encryption I/O state --- see fe-secure-gssapi.c */ 539 char *gss_SendBuffer; /* Encrypted data waiting to be sent */ 540 int gss_SendLength; /* End of data available in gss_SendBuffer */ 541 int gss_SendNext; /* Next index to send a byte from 542 * gss_SendBuffer */ 543 int gss_SendConsumed; /* Number of *unencrypted* bytes consumed 544 * for current contents of gss_SendBuffer */ 545 char *gss_RecvBuffer; /* Received, encrypted data */ 546 int gss_RecvLength; /* End of data available in gss_RecvBuffer */ 547 char *gss_ResultBuffer; /* Decryption of data in gss_RecvBuffer */ 548 int gss_ResultLength; /* End of data available in 549 * gss_ResultBuffer */ 550 int gss_ResultNext; /* Next index to read a byte from 551 * gss_ResultBuffer */ 552 uint32 gss_MaxPktSize; /* Maximum size we can encrypt and fit the 553 * results into our output buffer */ 554 #endif 555 556 #ifdef ENABLE_SSPI 557 CredHandle *sspicred; /* SSPI credentials handle */ 558 CtxtHandle *sspictx; /* SSPI context */ 559 char *sspitarget; /* SSPI target name */ 560 int usesspi; /* Indicate if SSPI is in use on the 561 * connection */ 562 #endif 563 564 /* 565 * Buffer for current error message. This is cleared at the start of any 566 * connection attempt or query cycle; after that, all code should append 567 * messages to it, never overwrite. 568 */ 569 PQExpBufferData errorMessage; /* expansible string */ 570 571 /* Buffer for receiving various parts of messages */ 572 PQExpBufferData workBuffer; /* expansible string */ 573 }; 574 575 /* PGcancel stores all data necessary to cancel a connection. A copy of this 576 * data is required to safely cancel a connection running on a different 577 * thread. 578 */ 579 struct pg_cancel 580 { 581 SockAddr raddr; /* Remote address */ 582 int be_pid; /* PID of backend --- needed for cancels */ 583 int be_key; /* key of backend --- needed for cancels */ 584 }; 585 586 587 /* String descriptions of the ExecStatusTypes. 588 * direct use of this array is deprecated; call PQresStatus() instead. 589 */ 590 extern char *const pgresStatus[]; 591 592 593 #ifdef USE_SSL 594 595 #ifndef WIN32 596 #define USER_CERT_FILE ".postgresql/postgresql.crt" 597 #define USER_KEY_FILE ".postgresql/postgresql.key" 598 #define ROOT_CERT_FILE ".postgresql/root.crt" 599 #define ROOT_CRL_FILE ".postgresql/root.crl" 600 #else 601 /* On Windows, the "home" directory is already PostgreSQL-specific */ 602 #define USER_CERT_FILE "postgresql.crt" 603 #define USER_KEY_FILE "postgresql.key" 604 #define ROOT_CERT_FILE "root.crt" 605 #define ROOT_CRL_FILE "root.crl" 606 #endif 607 608 #endif /* USE_SSL */ 609 610 /* ---------------- 611 * Internal functions of libpq 612 * Functions declared here need to be visible across files of libpq, 613 * but are not intended to be called by applications. We use the 614 * convention "pqXXX" for internal functions, vs. the "PQxxx" names 615 * used for application-visible routines. 616 * ---------------- 617 */ 618 619 /* === in fe-connect.c === */ 620 621 extern void pqDropConnection(PGconn *conn, bool flushInput); 622 extern int pqPacketSend(PGconn *conn, char pack_type, 623 const void *buf, size_t buf_len); 624 extern bool pqGetHomeDirectory(char *buf, int bufsize); 625 626 #ifdef ENABLE_THREAD_SAFETY 627 extern pgthreadlock_t pg_g_threadlock; 628 629 #define PGTHREAD_ERROR(msg) \ 630 do { \ 631 fprintf(stderr, "%s\n", msg); \ 632 abort(); \ 633 } while (0) 634 635 636 #define pglock_thread() pg_g_threadlock(true) 637 #define pgunlock_thread() pg_g_threadlock(false) 638 #else 639 #define pglock_thread() ((void) 0) 640 #define pgunlock_thread() ((void) 0) 641 #endif 642 643 /* === in fe-exec.c === */ 644 645 extern void pqSetResultError(PGresult *res, PQExpBuffer errorMessage); 646 extern void *pqResultAlloc(PGresult *res, size_t nBytes, bool isBinary); 647 extern char *pqResultStrdup(PGresult *res, const char *str); 648 extern void pqClearAsyncResult(PGconn *conn); 649 extern void pqSaveErrorResult(PGconn *conn); 650 extern PGresult *pqPrepareAsyncResult(PGconn *conn); 651 extern void pqInternalNotice(const PGNoticeHooks *hooks, const char *fmt,...) pg_attribute_printf(2, 3); 652 extern void pqSaveMessageField(PGresult *res, char code, 653 const char *value); 654 extern void pqSaveParameterStatus(PGconn *conn, const char *name, 655 const char *value); 656 extern int pqRowProcessor(PGconn *conn, const char **errmsgp); 657 extern void pqCommandQueueAdvance(PGconn *conn); 658 extern int PQsendQueryContinue(PGconn *conn, const char *query); 659 660 /* === in fe-protocol3.c === */ 661 662 extern char *pqBuildStartupPacket3(PGconn *conn, int *packetlen, 663 const PQEnvironmentOption *options); 664 extern void pqParseInput3(PGconn *conn); 665 extern int pqGetErrorNotice3(PGconn *conn, bool isError); 666 extern void pqBuildErrorMessage3(PQExpBuffer msg, const PGresult *res, 667 PGVerbosity verbosity, PGContextVisibility show_context); 668 extern int pqGetCopyData3(PGconn *conn, char **buffer, int async); 669 extern int pqGetline3(PGconn *conn, char *s, int maxlen); 670 extern int pqGetlineAsync3(PGconn *conn, char *buffer, int bufsize); 671 extern int pqEndcopy3(PGconn *conn); 672 extern PGresult *pqFunctionCall3(PGconn *conn, Oid fnid, 673 int *result_buf, int *actual_result_len, 674 int result_is_int, 675 const PQArgBlock *args, int nargs); 676 677 /* === in fe-misc.c === */ 678 679 /* 680 * "Get" and "Put" routines return 0 if successful, EOF if not. Note that for 681 * Get, EOF merely means the buffer is exhausted, not that there is 682 * necessarily any error. 683 */ 684 extern int pqCheckOutBufferSpace(size_t bytes_needed, PGconn *conn); 685 extern int pqCheckInBufferSpace(size_t bytes_needed, PGconn *conn); 686 extern int pqGetc(char *result, PGconn *conn); 687 extern int pqPutc(char c, PGconn *conn); 688 extern int pqGets(PQExpBuffer buf, PGconn *conn); 689 extern int pqGets_append(PQExpBuffer buf, PGconn *conn); 690 extern int pqPuts(const char *s, PGconn *conn); 691 extern int pqGetnchar(char *s, size_t len, PGconn *conn); 692 extern int pqSkipnchar(size_t len, PGconn *conn); 693 extern int pqPutnchar(const char *s, size_t len, PGconn *conn); 694 extern int pqGetInt(int *result, size_t bytes, PGconn *conn); 695 extern int pqPutInt(int value, size_t bytes, PGconn *conn); 696 extern int pqPutMsgStart(char msg_type, PGconn *conn); 697 extern int pqPutMsgEnd(PGconn *conn); 698 extern int pqReadData(PGconn *conn); 699 extern int pqFlush(PGconn *conn); 700 extern int pqWait(int forRead, int forWrite, PGconn *conn); 701 extern int pqWaitTimed(int forRead, int forWrite, PGconn *conn, 702 time_t finish_time); 703 extern int pqReadReady(PGconn *conn); 704 extern int pqWriteReady(PGconn *conn); 705 706 /* === in fe-secure.c === */ 707 708 extern int pqsecure_initialize(PGconn *, bool, bool); 709 extern PostgresPollingStatusType pqsecure_open_client(PGconn *); 710 extern void pqsecure_close(PGconn *); 711 extern ssize_t pqsecure_read(PGconn *, void *ptr, size_t len); 712 extern ssize_t pqsecure_write(PGconn *, const void *ptr, size_t len); 713 extern ssize_t pqsecure_raw_read(PGconn *, void *ptr, size_t len); 714 extern ssize_t pqsecure_raw_write(PGconn *, const void *ptr, size_t len); 715 716 #if defined(ENABLE_THREAD_SAFETY) && !defined(WIN32) 717 extern int pq_block_sigpipe(sigset_t *osigset, bool *sigpipe_pending); 718 extern void pq_reset_sigpipe(sigset_t *osigset, bool sigpipe_pending, 719 bool got_epipe); 720 #endif 721 722 /* === SSL === */ 723 724 /* 725 * The SSL implementation provides these functions. 726 */ 727 728 /* 729 * Implementation of PQinitSSL(). 730 */ 731 extern void pgtls_init_library(bool do_ssl, int do_crypto); 732 733 /* 734 * Initialize SSL library. 735 * 736 * The conn parameter is only used to be able to pass back an error 737 * message - no connection-local setup is made here. do_ssl controls 738 * if SSL is initialized, and do_crypto does the same for the crypto 739 * part. 740 * 741 * Returns 0 if OK, -1 on failure (adding a message to conn->errorMessage). 742 */ 743 extern int pgtls_init(PGconn *conn, bool do_ssl, bool do_crypto); 744 745 /* 746 * Begin or continue negotiating a secure session. 747 */ 748 extern PostgresPollingStatusType pgtls_open_client(PGconn *conn); 749 750 /* 751 * Close SSL connection. 752 */ 753 extern void pgtls_close(PGconn *conn); 754 755 /* 756 * Read data from a secure connection. 757 * 758 * On failure, this function is responsible for appending a suitable message 759 * to conn->errorMessage. The caller must still inspect errno, but only 760 * to determine whether to continue/retry after error. 761 */ 762 extern ssize_t pgtls_read(PGconn *conn, void *ptr, size_t len); 763 764 /* 765 * Is there unread data waiting in the SSL read buffer? 766 */ 767 extern bool pgtls_read_pending(PGconn *conn); 768 769 /* 770 * Write data to a secure connection. 771 * 772 * On failure, this function is responsible for appending a suitable message 773 * to conn->errorMessage. The caller must still inspect errno, but only 774 * to determine whether to continue/retry after error. 775 */ 776 extern ssize_t pgtls_write(PGconn *conn, const void *ptr, size_t len); 777 778 /* 779 * Get the hash of the server certificate, for SCRAM channel binding type 780 * tls-server-end-point. 781 * 782 * NULL is sent back to the caller in the event of an error, with an 783 * error message for the caller to consume. 784 * 785 * This is not supported with old versions of OpenSSL that don't have 786 * the X509_get_signature_nid() function. 787 */ 788 #if defined(USE_OPENSSL) && defined(HAVE_X509_GET_SIGNATURE_NID) 789 #define HAVE_PGTLS_GET_PEER_CERTIFICATE_HASH 790 extern char *pgtls_get_peer_certificate_hash(PGconn *conn, size_t *len); 791 #endif 792 793 /* 794 * Verify that the server certificate matches the host name we connected to. 795 * 796 * The certificate's Common Name and Subject Alternative Names are considered. 797 * 798 * Returns 1 if the name matches, and 0 if it does not. On error, returns 799 * -1, and sets the libpq error message. 800 * 801 */ 802 extern int pgtls_verify_peer_name_matches_certificate_guts(PGconn *conn, 803 int *names_examined, 804 char **first_name); 805 806 /* === GSSAPI === */ 807 808 #ifdef ENABLE_GSS 809 810 /* 811 * Establish a GSSAPI-encrypted connection. 812 */ 813 extern PostgresPollingStatusType pqsecure_open_gss(PGconn *conn); 814 815 /* 816 * Read and write functions for GSSAPI-encrypted connections, with internal 817 * buffering to handle nonblocking sockets. 818 */ 819 extern ssize_t pg_GSS_write(PGconn *conn, const void *ptr, size_t len); 820 extern ssize_t pg_GSS_read(PGconn *conn, void *ptr, size_t len); 821 #endif 822 823 /* === in libpq-trace.c === */ 824 825 extern void pqTraceOutputMessage(PGconn *conn, const char *message, 826 bool toServer); 827 extern void pqTraceOutputNoTypeByteMessage(PGconn *conn, const char *message); 828 829 /* === miscellaneous macros === */ 830 831 /* 832 * this is so that we can check if a connection is non-blocking internally 833 * without the overhead of a function call 834 */ 835 #define pqIsnonblocking(conn) ((conn)->nonblocking) 836 837 /* 838 * Connection's outbuffer threshold, for pipeline mode. 839 */ 840 #define OUTBUFFER_THRESHOLD 65536 841 842 #ifdef ENABLE_NLS 843 extern char *libpq_gettext(const char *msgid) pg_attribute_format_arg(1); 844 extern char *libpq_ngettext(const char *msgid, const char *msgid_plural, unsigned long n) pg_attribute_format_arg(1) pg_attribute_format_arg(2); 845 #else 846 #define libpq_gettext(x) (x) 847 #define libpq_ngettext(s, p, n) ((n) == 1 ? (s) : (p)) 848 #endif 849 850 /* 851 * These macros are needed to let error-handling code be portable between 852 * Unix and Windows. (ugh) 853 */ 854 #ifdef WIN32 855 #define SOCK_ERRNO (WSAGetLastError()) 856 #define SOCK_STRERROR winsock_strerror 857 #define SOCK_ERRNO_SET(e) WSASetLastError(e) 858 #else 859 #define SOCK_ERRNO errno 860 #define SOCK_STRERROR strerror_r 861 #define SOCK_ERRNO_SET(e) (errno = (e)) 862 #endif 863 864 #endif /* LIBPQ_INT_H */ 865