begriffs open source - ai-pg/blob - full-docs/src/sgml/html/libpq-misc.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.12. Miscellaneous Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-control.html" title="32.11. Control Functions" /><link rel="next" href="libpq-notice-processing.html" title="32.13. Notice Processing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.12. Miscellaneous Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-control.html" title="32.11. Control Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-notice-processing.html" title="32.13. Notice Processing">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-MISC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.12. Miscellaneous Functions <a href="#LIBPQ-MISC" class="id_link">#</a></h2></div></div></div><p>
   3    As always, there are some functions that just don't fit anywhere.
   4   </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQFREEMEM"><span class="term"><code class="function">PQfreemem</code><a id="id-1.7.3.19.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFREEMEM" class="id_link">#</a></dt><dd><p>
   5       Frees memory allocated by <span class="application">libpq</span>.
   6 </p><pre class="synopsis">
   7 void PQfreemem(void *ptr);
   8 </pre><p>
   9      </p><p>
  10       Frees memory allocated by <span class="application">libpq</span>, particularly
  11       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a>,
  12       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a>,
  13       <a class="xref" href="libpq-exec.html#LIBPQ-PQUNESCAPEBYTEA"><code class="function">PQunescapeBytea</code></a>,
  14       and <code class="function">PQnotifies</code>.
  15       It is particularly important that this function, rather than
  16       <code class="function">free()</code>, be used on Microsoft Windows.  This is because
  17       allocating memory in a DLL and releasing it in the application works
  18       only if multithreaded/single-threaded, release/debug, and static/dynamic
  19       flags are the same for the DLL and the application.  On non-Microsoft
  20       Windows platforms, this function is the same as the standard library
  21       function <code class="function">free()</code>.
  22      </p></dd><dt id="LIBPQ-PQCONNINFOFREE"><span class="term"><code class="function">PQconninfoFree</code><a id="id-1.7.3.19.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNINFOFREE" class="id_link">#</a></dt><dd><p>
  23       Frees the data structures allocated by
  24       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a> or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFOPARSE"><code class="function">PQconninfoParse</code></a>.
  25 </p><pre class="synopsis">
  26 void PQconninfoFree(PQconninfoOption *connOptions);
  27 </pre><p>
  28       If the argument is a <code class="symbol">NULL</code> pointer, no operation is
  29       performed.
  30      </p><p>
  31       A simple <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a> will not do for this, since
  32       the array contains references to subsidiary strings.
  33      </p></dd><dt id="LIBPQ-PQENCRYPTPASSWORDCONN"><span class="term"><code class="function">PQencryptPasswordConn</code><a id="id-1.7.3.19.3.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQENCRYPTPASSWORDCONN" class="id_link">#</a></dt><dd><p>
  34       Prepares the encrypted form of a <span class="productname">PostgreSQL</span> password.
  35 </p><pre class="synopsis">
  36 char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);
  37 </pre><p>
  38       This function is intended to be used by client applications that
  39       wish to send commands like <code class="literal">ALTER USER joe PASSWORD
  40       'pwd'</code>.  It is good practice not to send the original cleartext
  41       password in such a command, because it might be exposed in command
  42       logs, activity displays, and so on.  Instead, use this function to
  43       convert the password to encrypted form before it is sent.
  44      </p><p>
  45       The <em class="parameter"><code>passwd</code></em> and <em class="parameter"><code>user</code></em> arguments
  46       are the cleartext password, and the SQL name of the user it is for.
  47       <em class="parameter"><code>algorithm</code></em> specifies the encryption algorithm
  48       to use to encrypt the password. Currently supported algorithms are
  49       <code class="literal">md5</code> and <code class="literal">scram-sha-256</code> (<code class="literal">on</code> and
  50       <code class="literal">off</code> are also accepted as aliases for <code class="literal">md5</code>, for
  51       compatibility with older server versions). Note that support for
  52       <code class="literal">scram-sha-256</code> was introduced in <span class="productname">PostgreSQL</span>
  53       version 10, and will not work correctly with older server versions. If
  54       <em class="parameter"><code>algorithm</code></em> is <code class="symbol">NULL</code>, this function will query
  55       the server for the current value of the
  56       <a class="xref" href="runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION">password_encryption</a> setting. That can block, and
  57       will fail if the current transaction is aborted, or if the connection
  58       is busy executing another query. If you wish to use the default
  59       algorithm for the server but want to avoid blocking, query
  60       <code class="varname">password_encryption</code> yourself before calling
  61       <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN"><code class="function">PQencryptPasswordConn</code></a>, and pass that value as the
  62       <em class="parameter"><code>algorithm</code></em>.
  63      </p><p>
  64       The return value is a string allocated by <code class="function">malloc</code>.
  65       The caller can assume the string doesn't contain any special characters
  66       that would require escaping.  Use <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a> to free the
  67       result when done with it. On error, returns <code class="symbol">NULL</code>, and
  68       a suitable message is stored in the connection object.
  69      </p></dd><dt id="LIBPQ-PQCHANGEPASSWORD"><span class="term"><code class="function">PQchangePassword</code><a id="id-1.7.3.19.3.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCHANGEPASSWORD" class="id_link">#</a></dt><dd><p>
  70       Changes a <span class="productname">PostgreSQL</span> password.
  71 </p><pre class="synopsis">
  72 PGresult *PQchangePassword(PGconn *conn, const char *user, const char *passwd);
  73 </pre><p>
  74       This function uses <code class="function">PQencryptPasswordConn</code>
  75       to build and execute the command <code class="literal">ALTER USER ... PASSWORD
  76       '...'</code>, thereby changing the user's password. It exists for
  77       the same reason as <code class="function">PQencryptPasswordConn</code>, but
  78       is more convenient as it both builds and runs the command for you.
  79       <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN"><code class="function">PQencryptPasswordConn</code></a> is passed a
  80       <code class="symbol">NULL</code> for the algorithm argument, hence encryption is
  81       done according to the server's <a class="xref" href="runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION">password_encryption</a>
  82       setting.
  83      </p><p>
  84       The <em class="parameter"><code>user</code></em> and <em class="parameter"><code>passwd</code></em> arguments
  85       are the SQL name of the target user, and the new cleartext password.
  86      </p><p>
  87       Returns a <code class="structname">PGresult</code> pointer representing
  88       the result of the <code class="literal">ALTER USER</code> command, or
  89       a null pointer if the routine failed before issuing any command.
  90       The <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> function should be called
  91       to check the return value for any errors (including the value of a null
  92       pointer, in which case it will return
  93       <code class="symbol">PGRES_FATAL_ERROR</code>). Use
  94       <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
  95       <code class="function">PQerrorMessage</code>
  96
  97      </a> to get more information about
  98       such errors.
  99      </p></dd><dt id="LIBPQ-PQENCRYPTPASSWORD"><span class="term"><code class="function">PQencryptPassword</code><a id="id-1.7.3.19.3.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQENCRYPTPASSWORD" class="id_link">#</a></dt><dd><p>
 100       Prepares the md5-encrypted form of a <span class="productname">PostgreSQL</span> password.
 101 </p><pre class="synopsis">
 102 char *PQencryptPassword(const char *passwd, const char *user);
 103 </pre><p>
 104       <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORD"><code class="function">PQencryptPassword</code></a> is an older, deprecated version of
 105       <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN"><code class="function">PQencryptPasswordConn</code></a>. The difference is that
 106       <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORD"><code class="function">PQencryptPassword</code></a> does not
 107       require a connection object, and <code class="literal">md5</code> is always used as the
 108       encryption algorithm.
 109      </p></dd><dt id="LIBPQ-PQMAKEEMPTYPGRESULT"><span class="term"><code class="function">PQmakeEmptyPGresult</code><a id="id-1.7.3.19.3.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQMAKEEMPTYPGRESULT" class="id_link">#</a></dt><dd><p>
 110       Constructs an empty <code class="structname">PGresult</code> object with the given status.
 111 </p><pre class="synopsis">
 112 PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
 113 </pre><p>
 114      </p><p>
 115       This is <span class="application">libpq</span>'s internal function to allocate and
 116       initialize an empty <code class="structname">PGresult</code> object.  This
 117       function returns <code class="symbol">NULL</code> if memory could not be allocated. It is
 118       exported because some applications find it useful to generate result
 119       objects (particularly objects with error status) themselves.  If
 120       <em class="parameter"><code>conn</code></em> is not null and <em class="parameter"><code>status</code></em>
 121       indicates an error, the current error message of the specified
 122       connection is copied into the <code class="structname">PGresult</code>.
 123       Also, if <em class="parameter"><code>conn</code></em> is not null, any event procedures
 124       registered in the connection are copied into the
 125       <code class="structname">PGresult</code>.  (They do not get
 126       <code class="literal">PGEVT_RESULTCREATE</code> calls, but see
 127       <a class="xref" href="libpq-misc.html#LIBPQ-PQFIRERESULTCREATEEVENTS"><code class="function">PQfireResultCreateEvents</code></a>.)
 128       Note that <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> should eventually be called
 129       on the object, just as with a <code class="structname">PGresult</code>
 130       returned by <span class="application">libpq</span> itself.
 131      </p></dd><dt id="LIBPQ-PQFIRERESULTCREATEEVENTS"><span class="term"><code class="function">PQfireResultCreateEvents</code><a id="id-1.7.3.19.3.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFIRERESULTCREATEEVENTS" class="id_link">#</a></dt><dd><p>
 132       Fires a <code class="literal">PGEVT_RESULTCREATE</code> event (see <a class="xref" href="libpq-events.html" title="32.14. Event System">Section 32.14</a>) for each event procedure registered in the
 133       <code class="structname">PGresult</code> object.  Returns non-zero for success,
 134       zero if any event procedure fails.
 135
 136 </p><pre class="synopsis">
 137 int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
 138 </pre><p>
 139      </p><p>
 140       The <code class="literal">conn</code> argument is passed through to event procedures
 141       but not used directly.  It can be <code class="symbol">NULL</code> if the event
 142       procedures won't use it.
 143      </p><p>
 144       Event procedures that have already received a
 145       <code class="literal">PGEVT_RESULTCREATE</code> or <code class="literal">PGEVT_RESULTCOPY</code> event
 146       for this object are not fired again.
 147      </p><p>
 148       The main reason that this function is separate from
 149       <a class="xref" href="libpq-misc.html#LIBPQ-PQMAKEEMPTYPGRESULT"><code class="function">PQmakeEmptyPGresult</code></a> is that it is often appropriate
 150       to create a <code class="structname">PGresult</code> and fill it with data
 151       before invoking the event procedures.
 152      </p></dd><dt id="LIBPQ-PQCOPYRESULT"><span class="term"><code class="function">PQcopyResult</code><a id="id-1.7.3.19.3.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCOPYRESULT" class="id_link">#</a></dt><dd><p>
 153       Makes a copy of a <code class="structname">PGresult</code> object.  The copy is
 154       not linked to the source result in any way and
 155       <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> must be called when the copy is no longer
 156       needed.  If the function fails, <code class="symbol">NULL</code> is returned.
 157
 158 </p><pre class="synopsis">
 159 PGresult *PQcopyResult(const PGresult *src, int flags);
 160 </pre><p>
 161      </p><p>
 162       This is not intended to make an exact copy.  The returned result is
 163       always put into <code class="literal">PGRES_TUPLES_OK</code> status, and does not
 164       copy any error message in the source.  (It does copy the command status
 165       string, however.)  The <em class="parameter"><code>flags</code></em> argument determines
 166       what else is copied.  It is a bitwise OR of several flags.
 167       <code class="literal">PG_COPYRES_ATTRS</code> specifies copying the source
 168       result's attributes (column definitions).
 169       <code class="literal">PG_COPYRES_TUPLES</code> specifies copying the source
 170       result's tuples.  (This implies copying the attributes, too.)
 171       <code class="literal">PG_COPYRES_NOTICEHOOKS</code> specifies
 172       copying the source result's notify hooks.
 173       <code class="literal">PG_COPYRES_EVENTS</code> specifies copying the source
 174       result's events.  (But any instance data associated with the source
 175       is not copied.)
 176       The event procedures receive <code class="literal">PGEVT_RESULTCOPY</code> events.
 177      </p></dd><dt id="LIBPQ-PQSETRESULTATTRS"><span class="term"><code class="function">PQsetResultAttrs</code><a id="id-1.7.3.19.3.9.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETRESULTATTRS" class="id_link">#</a></dt><dd><p>
 178       Sets the attributes of a <code class="structname">PGresult</code> object.
 179 </p><pre class="synopsis">
 180 int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
 181 </pre><p>
 182      </p><p>
 183       The provided <em class="parameter"><code>attDescs</code></em> are copied into the result.
 184       If the <em class="parameter"><code>attDescs</code></em> pointer is <code class="symbol">NULL</code> or
 185       <em class="parameter"><code>numAttributes</code></em> is less than one, the request is
 186       ignored and the function succeeds.  If <em class="parameter"><code>res</code></em>
 187       already contains attributes, the function will fail.  If the function
 188       fails, the return value is zero.  If the function succeeds, the return
 189       value is non-zero.
 190      </p></dd><dt id="LIBPQ-PQSETVALUE"><span class="term"><code class="function">PQsetvalue</code><a id="id-1.7.3.19.3.10.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETVALUE" class="id_link">#</a></dt><dd><p>
 191       Sets a tuple field value of a <code class="structname">PGresult</code> object.
 192 </p><pre class="synopsis">
 193 int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
 194 </pre><p>
 195      </p><p>
 196       The function will automatically grow the result's internal tuples array
 197       as needed.  However, the <em class="parameter"><code>tup_num</code></em> argument must be
 198       less than or equal to <a class="xref" href="libpq-exec.html#LIBPQ-PQNTUPLES"><code class="function">PQntuples</code></a>, meaning this
 199       function can only grow the tuples array one tuple at a time.  But any
 200       field of any existing tuple can be modified in any order.  If a value at
 201       <em class="parameter"><code>field_num</code></em> already exists, it will be overwritten.
 202       If <em class="parameter"><code>len</code></em> is -1 or
 203       <em class="parameter"><code>value</code></em> is <code class="symbol">NULL</code>, the field value
 204       will be set to an SQL null value.  The
 205       <em class="parameter"><code>value</code></em> is copied into the result's private storage,
 206       thus is no longer needed after the function
 207       returns.  If the function fails, the return value is zero.  If the
 208       function succeeds, the return value is non-zero.
 209      </p></dd><dt id="LIBPQ-PQRESULTALLOC"><span class="term"><code class="function">PQresultAlloc</code><a id="id-1.7.3.19.3.11.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESULTALLOC" class="id_link">#</a></dt><dd><p>
 210       Allocate subsidiary storage for a <code class="structname">PGresult</code> object.
 211 </p><pre class="synopsis">
 212 void *PQresultAlloc(PGresult *res, size_t nBytes);
 213 </pre><p>
 214      </p><p>
 215       Any memory allocated with this function will be freed when
 216       <em class="parameter"><code>res</code></em> is cleared.  If the function fails,
 217       the return value is <code class="symbol">NULL</code>.  The result is
 218       guaranteed to be adequately aligned for any type of data,
 219       just as for <code class="function">malloc</code>.
 220      </p></dd><dt id="LIBPQ-PQRESULTMEMORYSIZE"><span class="term"><code class="function">PQresultMemorySize</code><a id="id-1.7.3.19.3.12.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESULTMEMORYSIZE" class="id_link">#</a></dt><dd><p>
 221       Retrieves the number of bytes allocated for
 222       a <code class="structname">PGresult</code> object.
 223 </p><pre class="synopsis">
 224 size_t PQresultMemorySize(const PGresult *res);
 225 </pre><p>
 226      </p><p>
 227       This value is the sum of all <code class="function">malloc</code> requests
 228       associated with the <code class="structname">PGresult</code> object, that is,
 229       all the memory that will be freed by <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.
 230       This information can be useful for managing memory consumption.
 231      </p></dd><dt id="LIBPQ-PQLIBVERSION"><span class="term"><code class="function">PQlibVersion</code><a id="id-1.7.3.19.3.13.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQLIBVERSION" class="id_link">#</a></dt><dd><p>
 232       Return the version of <span class="application">libpq</span> that is being used.
 233 </p><pre class="synopsis">
 234 int PQlibVersion(void);
 235 </pre><p>
 236      </p><p>
 237       The result of this function can be used to determine, at
 238       run time, whether specific functionality is available in the currently
 239       loaded version of libpq. The function can be used, for example,
 240       to determine which connection options are available in
 241       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
 242      </p><p>
 243       The result is formed by multiplying the library's major version
 244       number by 10000 and adding the minor version number.  For example,
 245       version 10.1 will be returned as 100001, and version 11.0 will be
 246       returned as 110000.
 247      </p><p>
 248       Prior to major version 10, <span class="productname">PostgreSQL</span> used
 249       three-part version numbers in which the first two parts together
 250       represented the major version.  For those
 251       versions, <a class="xref" href="libpq-misc.html#LIBPQ-PQLIBVERSION"><code class="function">PQlibVersion</code></a> uses two digits for each
 252       part; for example version 9.1.5 will be returned as 90105, and
 253       version 9.2.0 will be returned as 90200.
 254      </p><p>
 255       Therefore, for purposes of determining feature compatibility,
 256       applications should divide the result of <a class="xref" href="libpq-misc.html#LIBPQ-PQLIBVERSION"><code class="function">PQlibVersion</code></a>
 257       by 100 not 10000 to determine a logical major version number.
 258       In all release series, only the last two digits differ between
 259       minor releases (bug-fix releases).
 260      </p><div class="note"><h3 class="title">Note</h3><p>
 261        This function appeared in <span class="productname">PostgreSQL</span> version 9.1, so
 262        it cannot be used to detect required functionality in earlier
 263        versions, since calling it will create a link dependency
 264        on version 9.1 or later.
 265       </p></div></dd><dt id="LIBPQ-PQGETCURRENTTIMEUSEC"><span class="term"><code class="function">PQgetCurrentTimeUSec</code><a id="id-1.7.3.19.3.14.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETCURRENTTIMEUSEC" class="id_link">#</a></dt><dd><p>
 266       Retrieves the current time, expressed as the number of microseconds
 267       since the Unix epoch (that is, <code class="type">time_t</code> times 1 million).
 268 </p><pre class="synopsis">
 269 pg_usec_time_t PQgetCurrentTimeUSec(void);
 270 </pre><p>
 271      </p><p>
 272       This is primarily useful for calculating timeout values to use with
 273       <a class="xref" href="libpq-connect.html#LIBPQ-PQSOCKETPOLL"><code class="function">PQsocketPoll</code></a>.
 274      </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-control.html" title="32.11. Control Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-notice-processing.html" title="32.13. Notice Processing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.11. Control Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.13. Notice Processing</td></tr></table></div></body></html>