1/*-------------------------------------------------------------------------
7 * miscellaneous useful functions
9 * The communication routines here are analogous to the ones in
10 * backend/libpq/pqcomm.c and backend/libpq/pqformat.c, but operate
11 * in the considerably different environment of the frontend libpq.
12 * In particular, we work with a bare nonblock-mode socket, rather than
13 * a stdio stream, so that we can avoid unwanted blocking of the application.
15 * XXX: MOVE DEBUG PRINTOUT TO HIGHER LEVEL. As is, block and restart
16 * will cause repeat printouts.
18 * We must speak the same transmitted data representations as the backend
22 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
23 * Portions Copyright (c) 1994, Regents of the University of California
26 * src/interfaces/libpq/fe-misc.c
28 *-------------------------------------------------------------------------
51#include "pg_config_paths.h"
60 * PQlibVersion: return the libpq version number
65 return PG_VERSION_NUM;
70 * pqGetc: read 1 character from the connection
72 * All these routines return 0 on success, EOF on error.
73 * Note that for the Get routines, EOF only means there is not enough
74 * data in the buffer, not that there is necessarily a hard error.
89 * pqPutc: write 1 char to the current message
103 * read a null-terminated string from the connection,
104 * and store it in an expansible PQExpBuffer.
105 * If we run out of memory, all of the string is still read,
106 * but the excess characters are silently discarded.
111 /* Copy conn data to locals for faster search loop */
117 while (inCursor < inEnd && inBuffer[inCursor])
120 if (inCursor >= inEnd)
149 * pqPuts: write a null-terminated string to the current message
162 * read exactly len bytes in buffer s, no null termination
171 /* no terminating null */
180 * skip over len bytes in input buffer.
182 * Note: this is primarily useful for its debug output, which should
183 * be exactly the same as for pqGetnchar. We assume the data in question
184 * will actually be used, but just isn't getting copied anywhere as yet.
199 * write exactly len bytes to the current message
212 * read a 2 or 4 byte integer and convert from network byte order
213 * to local byte order
239 "integer of size %lu not supported by pqGetInt",
240 (
unsigned long) bytes);
249 * write an integer of 2 or 4 bytes, converting from host byte order
250 * to network byte order.
272 "integer of size %lu not supported by pqPutInt",
273 (
unsigned long) bytes);
281 * Make sure conn's output buffer can hold bytes_needed bytes (caller must
282 * include already-stored data into the value!)
284 * Returns 0 on success, EOF if failed to enlarge buffer
292 /* Quick exit if we have enough space */
293 if (bytes_needed <= (
size_t) newsize)
297 * If we need to enlarge the buffer, we first try to double it in size; if
298 * that doesn't work, enlarge in multiples of 8K. This avoids thrashing
299 * the malloc pool by repeated small enlargements.
301 * Note: tests for newsize > 0 are to catch integer overflow.
306 }
while (newsize > 0 && bytes_needed > (
size_t) newsize);
308 if (newsize > 0 && bytes_needed <= (
size_t) newsize)
313 /* realloc succeeded */
324 }
while (newsize > 0 && bytes_needed > (
size_t) newsize);
326 if (newsize > 0 && bytes_needed <= (
size_t) newsize)
331 /* realloc succeeded */
338 /* realloc failed. Probably out of memory */
340 "cannot allocate memory for output buffer\n");
345 * Make sure conn's input buffer can hold bytes_needed bytes (caller must
346 * include already-stored data into the value!)
348 * Returns 0 on success, EOF if failed to enlarge buffer
356 /* Quick exit if we have enough space */
357 if (bytes_needed <= (
size_t) newsize)
361 * Before concluding that we need to enlarge the buffer, left-justify
362 * whatever is in it and recheck. The caller's value of bytes_needed
363 * includes any data to the left of inStart, but we can delete that in
364 * preference to enlarging the buffer. It's slightly ugly to have this
365 * function do this, but it's better than making callers worry about it.
382 /* buffer is logically empty, reset it */
386 /* Recheck whether we have enough space */
387 if (bytes_needed <= (
size_t) newsize)
391 * If we need to enlarge the buffer, we first try to double it in size; if
392 * that doesn't work, enlarge in multiples of 8K. This avoids thrashing
393 * the malloc pool by repeated small enlargements.
395 * Note: tests for newsize > 0 are to catch integer overflow.
400 }
while (newsize > 0 && bytes_needed > (
size_t) newsize);
402 if (newsize > 0 && bytes_needed <= (
size_t) newsize)
407 /* realloc succeeded */
418 }
while (newsize > 0 && bytes_needed > (
size_t) newsize);
420 if (newsize > 0 && bytes_needed <= (
size_t) newsize)
425 /* realloc succeeded */
432 /* realloc failed. Probably out of memory */
434 "cannot allocate memory for input buffer\n");
439 * pqParseDone: after a server-to-client message has successfully
440 * been parsed, advance conn->inStart to account for it.
445 /* trace server-to-client message */
449 /* Mark message as done */
454 * pqPutMsgStart: begin construction of a message to the server
456 * msg_type is the message type byte, or 0 for a message without type byte
457 * (only startup messages have no type byte)
459 * Returns 0 on success, EOF on error
461 * The idea here is that we construct the message in conn->outBuffer,
462 * beginning just past any data already in outBuffer (ie, at
463 * outBuffer+outCount). We enlarge the buffer as needed to hold the message.
464 * When the message is complete, we fill in the length word (if needed) and
465 * then advance outCount past the message, making it eligible to send.
467 * The state variable conn->outMsgStart points to the incomplete message's
468 * length word: it is either outCount or outCount+1 depending on whether
469 * there is a type byte. The state variable conn->outMsgEnd is the end of
470 * the data collected so far.
478 /* allow room for message type byte */
484 /* do we want a length word? */
486 /* allow room for message length */
489 /* make sure there is room for message header */
492 /* okay, save the message type byte if any */
495 /* set up the message pointers */
498 /* length word, if needed, will be filled in by pqPutMsgEnd */
504 * pqPutMsgBytes: add bytes to a partially-constructed message
506 * Returns 0 on success, EOF on error
511 /* make sure there is room for it */
514 /* okay, save the data */
517 /* no Pfdebug call here, caller should do it */
522 * pqPutMsgEnd: finish constructing a message and possibly send it
524 * Returns 0 on success, EOF on error
526 * We don't actually send anything here unless we've accumulated at least
527 * 8K worth of data (the typical size of a pipe buffer on Unix systems).
528 * This avoids sending small partial packets. The caller must use pqFlush
529 * when it's important to flush all the data out to the server.
534 /* Fill in length word if needed */
543 /* trace client-to-server message */
553 /* Make message eligible to send */
556 /* If appropriate, try to push out some data */
562 * On Unix-pipe connections, it seems profitable to prefer sending
563 * pipe-buffer-sized packets not randomly-sized ones, so retain the
564 * last partial-8K chunk in our buffer for now. On TCP connections,
565 * the advantage of that is far less clear. Moreover, it flat out
566 * isn't safe when using SSL or GSSAPI, because those code paths have
567 * API stipulations that if they fail to send all the data that was
568 * offered in the previous write attempt, we mustn't offer less data
569 * in this write attempt. The previous write attempt might've been
570 * pqFlush attempting to send everything in the buffer, so we mustn't
571 * offer less now. (Presently, we won't try to use SSL or GSSAPI on
572 * Unix connections, so those checks are just Asserts. They'll have
573 * to become part of the regular if-test if we ever change that.)
583 toSend -= toSend % 8192;
588 /* in nonblock mode, don't complain if unable to send it all */
595 * pqReadData: read more data, if any is available
596 * Possible return values:
597 * 1: successfully loaded at least one more byte
598 * 0: no data is presently available, but no error detected
599 * -1: error detected (including EOF = connection closure);
600 * conn->errorMessage set
601 * NOTE: callers must not assume that pointers or indexes into conn->inBuffer
602 * remain valid across this call!
617 /* Left-justify any data in the buffer to make room */
631 /* buffer is logically empty, reset it */
636 * If the buffer is fairly full, enlarge it. We need to be able to enlarge
637 * the buffer in case a single message exceeds the initial buffer size. We
638 * enlarge before filling the buffer entirely so as to avoid asking the
639 * kernel for a partial packet. The magic constant here should be large
640 * enough for a TCP packet or Unix pipe bufferload. 8K is the usual pipe
648 * We don't insist that the enlarge worked, but we need some room
651 return -1;
/* errorMessage already set */
655 /* OK, try to read some data */
666 /* Some systems return EAGAIN/EWOULDBLOCK for no data */
671#if defined(EWOULDBLOCK) && (!defined(EAGAIN) || (EWOULDBLOCK != EAGAIN))
676 /* We might get ECONNRESET etc here if connection failed */
678 goto definitelyFailed;
681 /* pqsecure_read set the error message for us */
690 * Hack to deal with the fact that some kernels will only give us back
691 * 1 packet per recv() call, even if we asked for more and there is
692 * more available. If it looks like we are reading a long message,
693 * loop back to recv() again immediately, until we run out of data or
694 * buffer space. Without this, the block-and-restart behavior of
695 * libpq's higher levels leads to O(N^2) performance on long messages.
697 * Since we left-justified the data above, conn->inEnd gives the
698 * amount of data already read in the current message. We consider
699 * the message "long" once we have acquired 32k ...
711 return 1;
/* got a zero read after successful tries */
714 * A return value of 0 could mean just that no data is now available, or
715 * it could mean EOF --- that is, the server has closed the connection.
716 * Since we have the socket in nonblock mode, the only way to tell the
717 * difference is to see if select() is saying that the file is ready.
718 * Grumble. Fortunately, we don't expect this path to be taken much,
719 * since in normal practice we should not be trying to read data unless
720 * the file selected for reading already.
722 * In SSL mode it's even worse: SSL_read() could say WANT_READ and then
723 * data could arrive before we make the pqReadReady() test, but the second
724 * SSL_read() could still say WANT_READ because the data received was not
725 * a complete SSL record. So we must play dumb and assume there is more
726 * data, relying on the SSL layer to detect true EOF.
737 /* definitely no data available */
743 /* we override pqReadReady's message with something more useful */
748 * Still not sure that it's EOF, because some data could have just
761 /* Some systems return EAGAIN/EWOULDBLOCK for no data */
766#if defined(EWOULDBLOCK) && (!defined(EAGAIN) || (EWOULDBLOCK != EAGAIN))
771 /* We might get ECONNRESET etc here if connection failed */
773 goto definitelyFailed;
776 /* pqsecure_read set the error message for us */
787 * OK, we are getting a zero read even though select() says ready. This
788 * means the connection has been closed. Cope.
792 "\tThis probably means the server terminated abnormally\n"
793 "\tbefore or while processing the request.");
795 /* Come here if lower-level code already set a suitable errorMessage */
797 /* Do *not* drop any already-read data; caller still wants it */
804 * pqSendSome: send data waiting in the output buffer.
806 * len is how much to try to send (typically equal to outCount, but may
809 * Return 0 on success, -1 on failure and 1 when not all data could be sent
810 * because the socket would block and the connection is non-blocking.
812 * Note that this is also responsible for consuming data from the socket
813 * (putting it in conn->inBuffer) in any situation where we can't send
814 * all the specified data immediately.
816 * If a socket-level write failure occurs, conn->write_failed is set and the
817 * error message is saved in conn->write_err_msg, but we clear the output
818 * buffer and return zero anyway; this is because callers should soldier on
819 * until we have read what we can from the server and checked for an error
820 * message. write_err_msg should be reported only when we are unable to
821 * obtain a server error first. Much of that behavior is implemented at
822 * lower levels, but this function deals with some edge cases.
832 * If we already had a write failure, we will never again try to send data
833 * on that connection. Even if the kernel would let us, we've probably
834 * lost message boundary sync with the server. conn->write_failed
835 * therefore persists until the connection is reset, and we just discard
836 * all data presented to be written. However, as long as we still have a
837 * valid socket, we should continue to absorb data from the backend, so
838 * that we can collect any final error messages.
842 /* conn->write_err_msg should be set up already */
844 /* Absorb input data if any, and detect socket closure */
856 /* Store error message in conn->write_err_msg, if possible */
857 /* (strdup failure is OK, we'll cope later) */
859 /* Discard queued data; no chance it'll ever be sent */
864 /* while there's still data to send */
874 * Windows can fail on large sends, per KB article Q201213. The
875 * failure-point appears to be different in different versions of
876 * Windows, but 64k should always be safe.
883 /* Anything except EAGAIN/EWOULDBLOCK/EINTR is trouble */
890#if defined(EWOULDBLOCK) && (!defined(EAGAIN) || (EWOULDBLOCK != EAGAIN))
898 /* Discard queued data; no chance it'll ever be sent */
901 /* Absorb input data if any, and detect socket closure */
909 * Lower-level code should already have filled
910 * conn->write_err_msg (and set conn->write_failed) or
911 * conn->errorMessage. In the former case, we pretend
912 * there's no problem; the write_failed condition will be
913 * dealt with later. Otherwise, report the error now.
931 * We didn't send it all, wait till we can send more.
933 * There are scenarios in which we can't send data because the
934 * communications channel is full, but we cannot expect the server
935 * to clear the channel eventually because it's blocked trying to
936 * send data to us. (This can happen when we are sending a large
937 * amount of COPY data, and the server has generated lots of
938 * NOTICE responses.) To avoid a deadlock situation, we must be
939 * prepared to accept and buffer incoming data before we try
940 * again. Furthermore, it is possible that such incoming data
941 * might not arrive until after we've gone to sleep. Therefore,
942 * we wait for either read ready or write ready.
944 * In non-blocking mode, we don't wait here directly, but return 1
945 * to indicate that data is still pending. The caller should wait
946 * for both read and write ready conditions, and call
947 * PQconsumeInput() on read ready, but just in case it doesn't, we
948 * call pqReadData() ourselves before returning. That's not
949 * enough if the data has not arrived yet, but it's the best we
950 * can do, and works pretty well in practice. (The documentation
951 * used to say that you only need to wait for write-ready, so
952 * there are still plenty of applications like that out there.)
954 * Note that errors here don't result in write_failed becoming
959 result = -1;
/* error message already set up */
977 /* shift the remaining contents of the buffer */
987 * pqFlush: send any data waiting in the output buffer
989 * Return 0 on success, -1 on failure and 1 when not all data could be sent
990 * because the socket would block and the connection is non-blocking.
991 * (See pqSendSome comments about how failure should be handled.)
1009 * pqWait: wait until we can read or write the connection socket
1011 * JAB: If SSL enabled and used and forRead, buffered bytes short-circuit the
1014 * We also stop waiting and return if the kernel flags an exception condition
1015 * on the socket. The actual error condition will be detected and reported
1016 * when the caller tries to read or write the socket.
1025 * pqWaitTimed: wait, but not past end_time.
1027 * Returns -1 on failure, 0 if the socket is readable/writable, 1 if it timed out.
1029 * The timeout is specified by end_time, which is the int64 number of
1030 * microseconds since the Unix epoch (that is, time_t times 1 million).
1031 * Timeout is infinite if end_time is -1. Timeout is immediate (no blocking)
1032 * if end_time is 0 (or indeed, any time before now).
1042 return -1;
/* errorMessage is already set */
1054 * pqReadReady: is select() saying the file is ready to read?
1055 * Returns -1 on failure, 0 if not ready, 1 if ready.
1064 * pqWriteReady: is select() saying the file is ready to write?
1065 * Returns -1 on failure, 0 if not ready, 1 if ready.
1074 * Checks a socket, using poll or select, for data to be read, written,
1075 * or both. Returns >0 if one or more conditions are met, 0 if it timed
1076 * out, -1 if an error occurred.
1078 * If an altsock is set for asynchronous authentication, that will be used in
1079 * preference to the "server" socket. Otherwise, if SSL is in use, the SSL
1080 * buffer is checked prior to checking the socket for read data directly.
1103 /* Check for SSL library buffering read bytes */
1106 /* short-circuit the select */
1112 /* We will retry as long as we get EINTR */
1130 * Check a file descriptor for read and/or write data, possibly waiting.
1131 * If neither forRead nor forWrite are set, immediately return a timeout
1132 * condition (without waiting). Return >0 if condition is met, 0
1133 * if a timeout occurred, -1 if an error or interrupt occurred.
1135 * The timeout is specified by end_time, which is the int64 number of
1136 * microseconds since the Unix epoch (that is, time_t times 1 million).
1137 * Timeout is infinite if end_time is -1. Timeout is immediate (no blocking)
1138 * if end_time is 0 (or indeed, any time before now).
1143 /* We use poll(2) if available, otherwise select(2) */
1145 struct pollfd input_fd;
1148 if (!forRead && !forWrite)
1152 input_fd.events = POLLERR;
1153 input_fd.revents = 0;
1156 input_fd.events |= POLLIN;
1158 input_fd.events |= POLLOUT;
1160 /* Compute appropriate timeout interval */
1175 return poll(&input_fd, 1, timeout_ms);
1176#else /* !HAVE_POLL */
1181 struct timeval timeout;
1182 struct timeval *ptr_timeout;
1184 if (!forRead && !forWrite)
1187 FD_ZERO(&input_mask);
1188 FD_ZERO(&output_mask);
1189 FD_ZERO(&except_mask);
1191 FD_SET(sock, &input_mask);
1194 FD_SET(sock, &output_mask);
1195 FD_SET(sock, &except_mask);
1197 /* Compute appropriate timeout interval */
1203 timeout.tv_usec = 0;
1204 ptr_timeout = &timeout;
1218 timeout.tv_usec = 0;
1220 ptr_timeout = &timeout;
1223 return select(sock + 1, &input_mask, &output_mask,
1224 &except_mask, ptr_timeout);
1225#endif /* HAVE_POLL */
1229 * PQgetCurrentTimeUSec: get current time with microsecond precision
1231 * This provides a platform-independent way of producing a reference
1232 * value for PQsocketPoll's timeout parameter.
1237 struct timeval tval;
1245 * A couple of "miscellaneous" multibyte related functions. They used
1246 * to be in fe-print.c but that file is doomed.
1250 * Like pg_encoding_mblen(). Use this in callers that want the
1251 * dynamically-linked libpq's stance on encodings, even if that means
1252 * different behavior in different startups of the executable.
1261 * Like pg_encoding_mblen_bounded(). Use this in callers that want the
1262 * dynamically-linked libpq's stance on encodings, even if that means
1263 * different behavior in different startups of the executable.
1272 * Returns the display length of the character beginning at s, using the
1273 * specified encoding.
1282 * Get encoding id from environment variable PGCLIENTENCODING.
1290 str = getenv(
"PGCLIENTENCODING");
1304libpq_binddomain(
void)
1307 * At least on Windows, there are gettext implementations that fail if
1308 * multiple threads call bindtextdomain() concurrently. Use a mutex and
1309 * flag variable to ensure that we call it just once per process. It is
1310 * not known that similar bugs exist on non-Windows platforms, but we
1311 * might as well do it the same way everywhere.
1313 static volatile bool already_bound =
false;
1318 /* bindtextdomain() does not preserve errno */
1320 int save_errno = GetLastError();
1322 int save_errno = errno;
1332 * No relocatable lookup here because the calling executable could
1335 ldir = getenv(
"PGLOCALEDIR");
1339 already_bound =
true;
1345 SetLastError(save_errno);
1360libpq_ngettext(
const char *msgid,
const char *msgid_plural,
unsigned long n)
1366#endif /* ENABLE_NLS */
1370 * Append a formatted string to the given buffer, after translating it. A
1371 * newline is automatically appended; the format should not end with a
1377 int save_errno = errno;
1381 Assert(fmt[strlen(fmt) - 1] !=
'\n');
1384 return;
/* already failed */
1386 /* Loop in case we have to retry after enlarging the buffer. */
1390 va_start(
args, fmt);
1399 * Append a formatted string to the error message buffer of the given
1400 * connection, after translating it. A newline is automatically appended; the
1401 * format should not end with a newline.
1406 int save_errno = errno;
1410 Assert(fmt[strlen(fmt) - 1] !=
'\n');
1413 return;
/* already failed */
1415 /* Loop in case we have to retry after enlarging the buffer. */
1419 va_start(
args, fmt);
Datum now(PG_FUNCTION_ARGS)
#define PG_TEXTDOMAIN(domain)
#define dngettext(d, s, p, n)
void pqDropConnection(PGconn *conn, bool flushInput)
void pqInternalNotice(const PGNoticeHooks *hooks, const char *fmt,...)
int pqPutc(char c, PGconn *conn)
int pqReadData(PGconn *conn)
int pqPutInt(int value, size_t bytes, PGconn *conn)
int pqCheckOutBufferSpace(size_t bytes_needed, PGconn *conn)
int pqFlush(PGconn *conn)
void pqParseDone(PGconn *conn, int newInStart)
int pqReadReady(PGconn *conn)
static int pqSocketCheck(PGconn *conn, int forRead, int forWrite, pg_usec_time_t end_time)
int pqPutMsgStart(char msg_type, PGconn *conn)
int pqSkipnchar(size_t len, PGconn *conn)
int PQsocketPoll(int sock, int forRead, int forWrite, pg_usec_time_t end_time)
int pqGetc(char *result, PGconn *conn)
int pqGetInt(int *result, size_t bytes, PGconn *conn)
int PQmblen(const char *s, int encoding)
int pqWait(int forRead, int forWrite, PGconn *conn)
int pqGets(PQExpBuffer buf, PGconn *conn)
int pqPutnchar(const void *s, size_t len, PGconn *conn)
int PQdsplen(const char *s, int encoding)
int pqCheckInBufferSpace(size_t bytes_needed, PGconn *conn)
static int pqPutMsgBytes(const void *buf, size_t len, PGconn *conn)
static int pqSendSome(PGconn *conn, int len)
pg_usec_time_t PQgetCurrentTimeUSec(void)
static int pqGets_internal(PQExpBuffer buf, PGconn *conn, bool resetbuffer)
int pqPuts(const char *s, PGconn *conn)
void libpq_append_error(PQExpBuffer errorMessage, const char *fmt,...)
int pqGetnchar(void *s, size_t len, PGconn *conn)
int PQmblenBounded(const char *s, int encoding)
void libpq_append_conn_error(PGconn *conn, const char *fmt,...)
int pqWaitTimed(int forRead, int forWrite, PGconn *conn, pg_usec_time_t end_time)
int pqGets_append(PQExpBuffer buf, PGconn *conn)
int pqWriteReady(PGconn *conn)
int pqPutMsgEnd(PGconn *conn)
bool pgtls_read_pending(PGconn *conn)
ssize_t pqsecure_write(PGconn *conn, const void *ptr, size_t len)
ssize_t pqsecure_read(PGconn *conn, void *ptr, size_t len)
void pqTraceOutputMessage(PGconn *conn, const char *message, bool toServer)
void pqTraceOutputNoTypeByteMessage(PGconn *conn, const char *message)
Assert(PointerIsAligned(start, uint64))
#define libpq_ngettext(s, p, n)
#define pqIsnonblocking(conn)
#define pg_char_to_encoding
#define PG_STRERROR_R_BUFLEN
#define ALL_CONNECTION_FAILURE_ERRNOS
size_t strnlen(const char *str, size_t maxlen)
void resetPQExpBuffer(PQExpBuffer str)
void appendBinaryPQExpBuffer(PQExpBuffer str, const char *data, size_t datalen)
bool appendPQExpBufferVA(PQExpBuffer str, const char *fmt, va_list args)
void appendPQExpBufferChar(PQExpBuffer str, char ch)
void appendPQExpBufferStr(PQExpBuffer str, const char *data)
#define PQExpBufferBroken(str)
int pthread_mutex_unlock(pthread_mutex_t *mp)
int pthread_mutex_lock(pthread_mutex_t *mp)
#define PTHREAD_MUTEX_INITIALIZER
struct sockaddr_storage addr
PQExpBufferData errorMessage
PGNoticeHooks noticeHooks
int pg_encoding_dsplen(int encoding, const char *mbstr)
int pg_encoding_mblen(int encoding, const char *mbstr)
#define select(n, r, w, e, timeout)
int gettimeofday(struct timeval *tp, void *tzp)