codekingpro/portable-devtools
114k
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>