begriffs open source - ai-pg/blob - full-docs/txt/libpq-misc.txt

   1
   2 32.12. Miscellaneous Functions #
   3
   4    As always, there are some functions that just don't fit anywhere.
   5
   6    PQfreemem #
   7           Frees memory allocated by libpq.
   8
   9 void PQfreemem(void *ptr);
  10
  11           Frees memory allocated by libpq, particularly PQescapeByteaConn,
  12           PQescapeBytea, PQunescapeBytea, and PQnotifies. It is
  13           particularly important that this function, rather than free(),
  14           be used on Microsoft Windows. This is because allocating memory
  15           in a DLL and releasing it in the application works only if
  16           multithreaded/single-threaded, release/debug, and static/dynamic
  17           flags are the same for the DLL and the application. On
  18           non-Microsoft Windows platforms, this function is the same as
  19           the standard library function free().
  20
  21    PQconninfoFree #
  22           Frees the data structures allocated by PQconndefaults or
  23           PQconninfoParse.
  24
  25 void PQconninfoFree(PQconninfoOption *connOptions);
  26
  27           If the argument is a NULL pointer, no operation is performed.
  28
  29           A simple PQfreemem will not do for this, since the array
  30           contains references to subsidiary strings.
  31
  32    PQencryptPasswordConn #
  33           Prepares the encrypted form of a PostgreSQL password.
  34
  35 char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user,
  36 const char *algorithm);
  37
  38           This function is intended to be used by client applications that
  39           wish to send commands like ALTER USER joe PASSWORD 'pwd'. It is
  40           good practice not to send the original cleartext password in
  41           such a command, because it might be exposed in command logs,
  42           activity displays, and so on. Instead, use this function to
  43           convert the password to encrypted form before it is sent.
  44
  45           The passwd and user arguments are the cleartext password, and
  46           the SQL name of the user it is for. algorithm specifies the
  47           encryption algorithm to use to encrypt the password. Currently
  48           supported algorithms are md5 and scram-sha-256 (on and off are
  49           also accepted as aliases for md5, for compatibility with older
  50           server versions). Note that support for scram-sha-256 was
  51           introduced in PostgreSQL version 10, and will not work correctly
  52           with older server versions. If algorithm is NULL, this function
  53           will query the server for the current value of the
  54           password_encryption setting. That can block, and will fail if
  55           the current transaction is aborted, or if the connection is busy
  56           executing another query. If you wish to use the default
  57           algorithm for the server but want to avoid blocking, query
  58           password_encryption yourself before calling
  59           PQencryptPasswordConn, and pass that value as the algorithm.
  60
  61           The return value is a string allocated by malloc. The caller can
  62           assume the string doesn't contain any special characters that
  63           would require escaping. Use PQfreemem to free the result when
  64           done with it. On error, returns NULL, and a suitable message is
  65           stored in the connection object.
  66
  67    PQchangePassword #
  68           Changes a PostgreSQL password.
  69
  70 PGresult *PQchangePassword(PGconn *conn, const char *user, const char *passwd);
  71
  72           This function uses PQencryptPasswordConn to build and execute
  73           the command ALTER USER ... PASSWORD '...', thereby changing the
  74           user's password. It exists for the same reason as
  75           PQencryptPasswordConn, but is more convenient as it both builds
  76           and runs the command for you. PQencryptPasswordConn is passed a
  77           NULL for the algorithm argument, hence encryption is done
  78           according to the server's password_encryption setting.
  79
  80           The user and passwd arguments are the SQL name of the target
  81           user, and the new cleartext password.
  82
  83           Returns a PGresult pointer representing the result of the ALTER
  84           USER command, or a null pointer if the routine failed before
  85           issuing any command. The PQresultStatus function should be
  86           called to check the return value for any errors (including the
  87           value of a null pointer, in which case it will return
  88           PGRES_FATAL_ERROR). Use PQerrorMessage to get more information
  89           about such errors.
  90
  91    PQencryptPassword #
  92           Prepares the md5-encrypted form of a PostgreSQL password.
  93
  94 char *PQencryptPassword(const char *passwd, const char *user);
  95
  96           PQencryptPassword is an older, deprecated version of
  97           PQencryptPasswordConn. The difference is that PQencryptPassword
  98           does not require a connection object, and md5 is always used as
  99           the encryption algorithm.
 100
 101    PQmakeEmptyPGresult #
 102           Constructs an empty PGresult object with the given status.
 103
 104 PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
 105
 106           This is libpq's internal function to allocate and initialize an
 107           empty PGresult object. This function returns NULL if memory
 108           could not be allocated. It is exported because some applications
 109           find it useful to generate result objects (particularly objects
 110           with error status) themselves. If conn is not null and status
 111           indicates an error, the current error message of the specified
 112           connection is copied into the PGresult. Also, if conn is not
 113           null, any event procedures registered in the connection are
 114           copied into the PGresult. (They do not get PGEVT_RESULTCREATE
 115           calls, but see PQfireResultCreateEvents.) Note that PQclear
 116           should eventually be called on the object, just as with a
 117           PGresult returned by libpq itself.
 118
 119    PQfireResultCreateEvents #
 120           Fires a PGEVT_RESULTCREATE event (see Section 32.14) for each
 121           event procedure registered in the PGresult object. Returns
 122           non-zero for success, zero if any event procedure fails.
 123
 124 int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
 125
 126           The conn argument is passed through to event procedures but not
 127           used directly. It can be NULL if the event procedures won't use
 128           it.
 129
 130           Event procedures that have already received a PGEVT_RESULTCREATE
 131           or PGEVT_RESULTCOPY event for this object are not fired again.
 132
 133           The main reason that this function is separate from
 134           PQmakeEmptyPGresult is that it is often appropriate to create a
 135           PGresult and fill it with data before invoking the event
 136           procedures.
 137
 138    PQcopyResult #
 139           Makes a copy of a PGresult object. The copy is not linked to the
 140           source result in any way and PQclear must be called when the
 141           copy is no longer needed. If the function fails, NULL is
 142           returned.
 143
 144 PGresult *PQcopyResult(const PGresult *src, int flags);
 145
 146           This is not intended to make an exact copy. The returned result
 147           is always put into PGRES_TUPLES_OK status, and does not copy any
 148           error message in the source. (It does copy the command status
 149           string, however.) The flags argument determines what else is
 150           copied. It is a bitwise OR of several flags. PG_COPYRES_ATTRS
 151           specifies copying the source result's attributes (column
 152           definitions). PG_COPYRES_TUPLES specifies copying the source
 153           result's tuples. (This implies copying the attributes, too.)
 154           PG_COPYRES_NOTICEHOOKS specifies copying the source result's
 155           notify hooks. PG_COPYRES_EVENTS specifies copying the source
 156           result's events. (But any instance data associated with the
 157           source is not copied.) The event procedures receive
 158           PGEVT_RESULTCOPY events.
 159
 160    PQsetResultAttrs #
 161           Sets the attributes of a PGresult object.
 162
 163 int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
 164
 165           The provided attDescs are copied into the result. If the
 166           attDescs pointer is NULL or numAttributes is less than one, the
 167           request is ignored and the function succeeds. If res already
 168           contains attributes, the function will fail. If the function
 169           fails, the return value is zero. If the function succeeds, the
 170           return value is non-zero.
 171
 172    PQsetvalue #
 173           Sets a tuple field value of a PGresult object.
 174
 175 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
 176
 177           The function will automatically grow the result's internal
 178           tuples array as needed. However, the tup_num argument must be
 179           less than or equal to PQntuples, meaning this function can only
 180           grow the tuples array one tuple at a time. But any field of any
 181           existing tuple can be modified in any order. If a value at
 182           field_num already exists, it will be overwritten. If len is -1
 183           or value is NULL, the field value will be set to an SQL null
 184           value. The value is copied into the result's private storage,
 185           thus is no longer needed after the function returns. If the
 186           function fails, the return value is zero. If the function
 187           succeeds, the return value is non-zero.
 188
 189    PQresultAlloc #
 190           Allocate subsidiary storage for a PGresult object.
 191
 192 void *PQresultAlloc(PGresult *res, size_t nBytes);
 193
 194           Any memory allocated with this function will be freed when res
 195           is cleared. If the function fails, the return value is NULL. The
 196           result is guaranteed to be adequately aligned for any type of
 197           data, just as for malloc.
 198
 199    PQresultMemorySize #
 200           Retrieves the number of bytes allocated for a PGresult object.
 201
 202 size_t PQresultMemorySize(const PGresult *res);
 203
 204           This value is the sum of all malloc requests associated with the
 205           PGresult object, that is, all the memory that will be freed by
 206           PQclear. This information can be useful for managing memory
 207           consumption.
 208
 209    PQlibVersion #
 210           Return the version of libpq that is being used.
 211
 212 int PQlibVersion(void);
 213
 214           The result of this function can be used to determine, at run
 215           time, whether specific functionality is available in the
 216           currently loaded version of libpq. The function can be used, for
 217           example, to determine which connection options are available in
 218           PQconnectdb.
 219
 220           The result is formed by multiplying the library's major version
 221           number by 10000 and adding the minor version number. For
 222           example, version 10.1 will be returned as 100001, and version
 223           11.0 will be returned as 110000.
 224
 225           Prior to major version 10, PostgreSQL used three-part version
 226           numbers in which the first two parts together represented the
 227           major version. For those versions, PQlibVersion uses two digits
 228           for each part; for example version 9.1.5 will be returned as
 229           90105, and version 9.2.0 will be returned as 90200.
 230
 231           Therefore, for purposes of determining feature compatibility,
 232           applications should divide the result of PQlibVersion by 100 not
 233           10000 to determine a logical major version number. In all
 234           release series, only the last two digits differ between minor
 235           releases (bug-fix releases).
 236
 237 Note
 238
 239           This function appeared in PostgreSQL version 9.1, so it cannot
 240           be used to detect required functionality in earlier versions,
 241           since calling it will create a link dependency on version 9.1 or
 242           later.
 243
 244    PQgetCurrentTimeUSec #
 245           Retrieves the current time, expressed as the number of
 246           microseconds since the Unix epoch (that is, time_t times 1
 247           million).
 248
 249 pg_usec_time_t PQgetCurrentTimeUSec(void);
 250
 251           This is primarily useful for calculating timeout values to use
 252           with PQsocketPoll.