Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes14kdownloads
libpq-misc.html235 linesDownload Raw Back to 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>34.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="34.11. Control Functions" /><link rel="next" href="libpq-notice-processing.html" title="34.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">34.12. Miscellaneous Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-control.html" title="34.11. Control Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-notice-processing.html" title="34.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">34.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">7void PQfreemem(void *ptr);8</pre><p>9     </p><p>10      Frees memory allocated by <span class="application">libpq</span>, particularly11      <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 than16      <code class="function">free()</code>, be used on Microsoft Windows.  This is because17      allocating memory in a DLL and releasing it in the application works18      only if multithreaded/single-threaded, release/debug, and static/dynamic19      flags are the same for the DLL and the application.  On non-Microsoft20      Windows platforms, this function is the same as the standard library21      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 by24      <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">26void PQconninfoFree(PQconninfoOption *connOptions);27</pre><p>28      If the argument is a <code class="symbol">NULL</code> pointer, no operation is29      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, since32      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">36char *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 that39      wish to send commands like <code class="literal">ALTER USER joe PASSWORD40      'pwd'</code>.  It is good practice not to send the original cleartext41      password in such a command, because it might be exposed in command42      logs, activity displays, and so on.  Instead, use this function to43      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> arguments46      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 algorithm48      to use to encrypt the password. Currently supported algorithms are49      <code class="literal">md5</code> and <code class="literal">scram-sha-256</code> (<code class="literal">on</code> and50      <code class="literal">off</code> are also accepted as aliases for <code class="literal">md5</code>, for51      compatibility with older server versions). Note that support for52      <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. If54      <em class="parameter"><code>algorithm</code></em> is <code class="symbol">NULL</code>, this function will query55      the server for the current value of the56      <a class="xref" href="runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION">password_encryption</a> setting. That can block, and57      will fail if the current transaction is aborted, or if the connection58      is busy executing another query. If you wish to use the default59      algorithm for the server but want to avoid blocking, query60      <code class="varname">password_encryption</code> yourself before calling61      <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN"><code class="function">PQencryptPasswordConn</code></a>, and pass that value as the62      <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 characters66      that would require escaping.  Use <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a> to free the67      result when done with it. On error, returns <code class="symbol">NULL</code>, and68      a suitable message is stored in the connection object.69     </p></dd><dt id="LIBPQ-PQENCRYPTPASSWORD"><span class="term"><code class="function">PQencryptPassword</code><a id="id-1.7.3.19.3.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQENCRYPTPASSWORD" class="id_link">#</a></dt><dd><p>70      Prepares the md5-encrypted form of a <span class="productname">PostgreSQL</span> password.71</p><pre class="synopsis">72char *PQencryptPassword(const char *passwd, const char *user);73</pre><p>74      <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORD"><code class="function">PQencryptPassword</code></a> is an older, deprecated version of75      <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN"><code class="function">PQencryptPasswordConn</code></a>. The difference is that76      <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORD"><code class="function">PQencryptPassword</code></a> does not77      require a connection object, and <code class="literal">md5</code> is always used as the78      encryption algorithm.79     </p></dd><dt id="LIBPQ-PQMAKEEMPTYPGRESULT"><span class="term"><code class="function">PQmakeEmptyPGresult</code><a id="id-1.7.3.19.3.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQMAKEEMPTYPGRESULT" class="id_link">#</a></dt><dd><p>80      Constructs an empty <code class="structname">PGresult</code> object with the given status.81</p><pre class="synopsis">82PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);83</pre><p>84     </p><p>85      This is <span class="application">libpq</span>'s internal function to allocate and86      initialize an empty <code class="structname">PGresult</code> object.  This87      function returns <code class="symbol">NULL</code> if memory could not be allocated. It is88      exported because some applications find it useful to generate result89      objects (particularly objects with error status) themselves.  If90      <em class="parameter"><code>conn</code></em> is not null and <em class="parameter"><code>status</code></em>91      indicates an error, the current error message of the specified92      connection is copied into the <code class="structname">PGresult</code>.93      Also, if <em class="parameter"><code>conn</code></em> is not null, any event procedures94      registered in the connection are copied into the95      <code class="structname">PGresult</code>.  (They do not get96      <code class="literal">PGEVT_RESULTCREATE</code> calls, but see97      <a class="xref" href="libpq-misc.html#LIBPQ-PQFIRERESULTCREATEEVENTS"><code class="function">PQfireResultCreateEvents</code></a>.)98      Note that <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> should eventually be called99      on the object, just as with a <code class="structname">PGresult</code>100      returned by <span class="application">libpq</span> itself.101     </p></dd><dt id="LIBPQ-PQFIRERESULTCREATEEVENTS"><span class="term"><code class="function">PQfireResultCreateEvents</code><a id="id-1.7.3.19.3.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFIRERESULTCREATEEVENTS" class="id_link">#</a></dt><dd><p>102      Fires a <code class="literal">PGEVT_RESULTCREATE</code> event (see <a class="xref" href="libpq-events.html" title="34.14. Event System">Section 34.14</a>) for each event procedure registered in the103      <code class="structname">PGresult</code> object.  Returns non-zero for success,104      zero if any event procedure fails.105 106</p><pre class="synopsis">107int PQfireResultCreateEvents(PGconn *conn, PGresult *res);108</pre><p>109     </p><p>110      The <code class="literal">conn</code> argument is passed through to event procedures111      but not used directly.  It can be <code class="symbol">NULL</code> if the event112      procedures won't use it.113     </p><p>114      Event procedures that have already received a115      <code class="literal">PGEVT_RESULTCREATE</code> or <code class="literal">PGEVT_RESULTCOPY</code> event116      for this object are not fired again.117     </p><p>118      The main reason that this function is separate from119      <a class="xref" href="libpq-misc.html#LIBPQ-PQMAKEEMPTYPGRESULT"><code class="function">PQmakeEmptyPGresult</code></a> is that it is often appropriate120      to create a <code class="structname">PGresult</code> and fill it with data121      before invoking the event procedures.122     </p></dd><dt id="LIBPQ-PQCOPYRESULT"><span class="term"><code class="function">PQcopyResult</code><a id="id-1.7.3.19.3.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCOPYRESULT" class="id_link">#</a></dt><dd><p>123      Makes a copy of a <code class="structname">PGresult</code> object.  The copy is124      not linked to the source result in any way and125      <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> must be called when the copy is no longer126      needed.  If the function fails, <code class="symbol">NULL</code> is returned.127 128</p><pre class="synopsis">129PGresult *PQcopyResult(const PGresult *src, int flags);130</pre><p>131     </p><p>132      This is not intended to make an exact copy.  The returned result is133      always put into <code class="literal">PGRES_TUPLES_OK</code> status, and does not134      copy any error message in the source.  (It does copy the command status135      string, however.)  The <em class="parameter"><code>flags</code></em> argument determines136      what else is copied.  It is a bitwise OR of several flags.137      <code class="literal">PG_COPYRES_ATTRS</code> specifies copying the source138      result's attributes (column definitions).139      <code class="literal">PG_COPYRES_TUPLES</code> specifies copying the source140      result's tuples.  (This implies copying the attributes, too.)141      <code class="literal">PG_COPYRES_NOTICEHOOKS</code> specifies142      copying the source result's notify hooks.143      <code class="literal">PG_COPYRES_EVENTS</code> specifies copying the source144      result's events.  (But any instance data associated with the source145      is not copied.)146      The event procedures receive <code class="literal">PGEVT_RESULTCOPY</code> events.147     </p></dd><dt id="LIBPQ-PQSETRESULTATTRS"><span class="term"><code class="function">PQsetResultAttrs</code><a id="id-1.7.3.19.3.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETRESULTATTRS" class="id_link">#</a></dt><dd><p>148      Sets the attributes of a <code class="structname">PGresult</code> object.149</p><pre class="synopsis">150int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);151</pre><p>152     </p><p>153      The provided <em class="parameter"><code>attDescs</code></em> are copied into the result.154      If the <em class="parameter"><code>attDescs</code></em> pointer is <code class="symbol">NULL</code> or155      <em class="parameter"><code>numAttributes</code></em> is less than one, the request is156      ignored and the function succeeds.  If <em class="parameter"><code>res</code></em>157      already contains attributes, the function will fail.  If the function158      fails, the return value is zero.  If the function succeeds, the return159      value is non-zero.160     </p></dd><dt id="LIBPQ-PQSETVALUE"><span class="term"><code class="function">PQsetvalue</code><a id="id-1.7.3.19.3.9.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETVALUE" class="id_link">#</a></dt><dd><p>161      Sets a tuple field value of a <code class="structname">PGresult</code> object.162</p><pre class="synopsis">163int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);164</pre><p>165     </p><p>166      The function will automatically grow the result's internal tuples array167      as needed.  However, the <em class="parameter"><code>tup_num</code></em> argument must be168      less than or equal to <a class="xref" href="libpq-exec.html#LIBPQ-PQNTUPLES"><code class="function">PQntuples</code></a>, meaning this169      function can only grow the tuples array one tuple at a time.  But any170      field of any existing tuple can be modified in any order.  If a value at171      <em class="parameter"><code>field_num</code></em> already exists, it will be overwritten.172      If <em class="parameter"><code>len</code></em> is -1 or173      <em class="parameter"><code>value</code></em> is <code class="symbol">NULL</code>, the field value174      will be set to an SQL null value.  The175      <em class="parameter"><code>value</code></em> is copied into the result's private storage,176      thus is no longer needed after the function177      returns.  If the function fails, the return value is zero.  If the178      function succeeds, the return value is non-zero.179     </p></dd><dt id="LIBPQ-PQRESULTALLOC"><span class="term"><code class="function">PQresultAlloc</code><a id="id-1.7.3.19.3.10.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESULTALLOC" class="id_link">#</a></dt><dd><p>180      Allocate subsidiary storage for a <code class="structname">PGresult</code> object.181</p><pre class="synopsis">182void *PQresultAlloc(PGresult *res, size_t nBytes);183</pre><p>184     </p><p>185      Any memory allocated with this function will be freed when186      <em class="parameter"><code>res</code></em> is cleared.  If the function fails,187      the return value is <code class="symbol">NULL</code>.  The result is188      guaranteed to be adequately aligned for any type of data,189      just as for <code class="function">malloc</code>.190     </p></dd><dt id="LIBPQ-PQRESULTMEMORYSIZE"><span class="term"><code class="function">PQresultMemorySize</code><a id="id-1.7.3.19.3.11.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESULTMEMORYSIZE" class="id_link">#</a></dt><dd><p>191      Retrieves the number of bytes allocated for192      a <code class="structname">PGresult</code> object.193</p><pre class="synopsis">194size_t PQresultMemorySize(const PGresult *res);195</pre><p>196     </p><p>197      This value is the sum of all <code class="function">malloc</code> requests198      associated with the <code class="structname">PGresult</code> object, that is,199      all the space that will be freed by <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.200      This information can be useful for managing memory consumption.201     </p></dd><dt id="LIBPQ-PQLIBVERSION"><span class="term"><code class="function">PQlibVersion</code><a id="id-1.7.3.19.3.12.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQLIBVERSION" class="id_link">#</a></dt><dd><p>202      Return the version of <span class="productname">libpq</span> that is being used.203</p><pre class="synopsis">204int PQlibVersion(void);205</pre><p>206     </p><p>207      The result of this function can be used to determine, at208      run time, whether specific functionality is available in the currently209      loaded version of libpq. The function can be used, for example,210      to determine which connection options are available in211      <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.212     </p><p>213      The result is formed by multiplying the library's major version214      number by 10000 and adding the minor version number.  For example,215      version 10.1 will be returned as 100001, and version 11.0 will be216      returned as 110000.217     </p><p>218      Prior to major version 10, <span class="productname">PostgreSQL</span> used219      three-part version numbers in which the first two parts together220      represented the major version.  For those221      versions, <a class="xref" href="libpq-misc.html#LIBPQ-PQLIBVERSION"><code class="function">PQlibVersion</code></a> uses two digits for each222      part; for example version 9.1.5 will be returned as 90105, and223      version 9.2.0 will be returned as 90200.224     </p><p>225      Therefore, for purposes of determining feature compatibility,226      applications should divide the result of <a class="xref" href="libpq-misc.html#LIBPQ-PQLIBVERSION"><code class="function">PQlibVersion</code></a>227      by 100 not 10000 to determine a logical major version number.228      In all release series, only the last two digits differ between229      minor releases (bug-fix releases).230     </p><div class="note"><h3 class="title">Note</h3><p>231       This function appeared in <span class="productname">PostgreSQL</span> version 9.1, so232       it cannot be used to detect required functionality in earlier233       versions, since calling it will create a link dependency234       on version 9.1 or later.235      </p></div></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="34.11. Control Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-notice-processing.html" title="34.13. Notice Processing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.11. Control Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.13. Notice Processing</td></tr></table></div></body></html>
codekingpro/portable-devtools · Team Ai