Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Sledovat 1
Oblíbit 0
Wiki 捐赠
gooderp18绿色标准版
Nelze vybrat více než 25 témat Téma musí začínat písmenem nebo číslem, může obsahovat pomlčky („-“) a může být dlouhé až 35 znaků.
Strom: 0f75e31513
Větve Značky
${ item.name }
Vytvořit větev ${ searchTerm }
z „0f75e31513“
${ noResults }
Green_GoodERP18_FSJ_Standard/PostgreSQL/doc/postgresql/html/libpq-misc.html

268 lines
18KB
Surový Blame Historie 

  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>33.11. 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 V1.79.1" /><link rel="prev" href="libpq-control.html" title="33.10. Control Functions" /><link rel="next" href="libpq-notice-processing.html" title="33.12. Notice Processing" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.11. Miscellaneous Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-control.html" title="33.10. Control Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 33. libpq - C Library">Up</a></td><th width="60%" align="center">Chapter 33. <span xmlns="http://www.w3.org/1999/xhtml" class="application">libpq</span> - C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 12.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-notice-processing.html" title="33.12. Notice Processing">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="LIBPQ-MISC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.11. Miscellaneous Functions</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">

  5.      <code class="function">PQfreemem</code>

  6.      <a id="id-1.7.3.18.3.1.1.2" class="indexterm"></a>

  7.     </span></dt><dd><p>

  8.       Frees memory allocated by <span class="application">libpq</span>.

  9. </p><pre class="synopsis">

  10. void PQfreemem(void *ptr);

  11. </pre><p>

  12.      </p><p>

  13.       Frees memory allocated by <span class="application">libpq</span>, particularly

  14.       <code class="function">PQescapeByteaConn</code>,

  15.       <code class="function">PQescapeBytea</code>,

  16.       <code class="function">PQunescapeBytea</code>,

  17.       and <code class="function">PQnotifies</code>.

  18.       It is particularly important that this function, rather than

  19.       <code class="function">free()</code>, be used on Microsoft Windows.  This is because

  20.       allocating memory in a DLL and releasing it in the application works

  21.       only if multithreaded/single-threaded, release/debug, and static/dynamic

  22.       flags are the same for the DLL and the application.  On non-Microsoft

  23.       Windows platforms, this function is the same as the standard library

  24.       function <code class="function">free()</code>.

  25.      </p></dd><dt id="LIBPQ-PQCONNINFOFREE"><span class="term">

  26.      <code class="function">PQconninfoFree</code>

  27.      <a id="id-1.7.3.18.3.2.1.2" class="indexterm"></a>

  28.     </span></dt><dd><p>

  29.       Frees the data structures allocated by

  30.       <code class="function">PQconndefaults</code> or <code class="function">PQconninfoParse</code>.

  31. </p><pre class="synopsis">

  32. void PQconninfoFree(PQconninfoOption *connOptions);

  33. </pre><p>

  34.      </p><p>

  35.       A simple <code class="function">PQfreemem</code> will not do for this, since

  36.       the array contains references to subsidiary strings.

  37.      </p></dd><dt id="LIBPQ-PQENCRYPTPASSWORDCONN"><span class="term">

  38.      <code class="function">PQencryptPasswordConn</code>

  39.      <a id="id-1.7.3.18.3.3.1.2" class="indexterm"></a>

  40.     </span></dt><dd><p>

  41.       Prepares the encrypted form of a <span class="productname">PostgreSQL</span> password.

  42. </p><pre class="synopsis">

  43. char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);

  44. </pre><p>

  45.       This function is intended to be used by client applications that

  46.       wish to send commands like <code class="literal">ALTER USER joe PASSWORD

  47.       'pwd'</code>.  It is good practice not to send the original cleartext

  48.       password in such a command, because it might be exposed in command

  49.       logs, activity displays, and so on.  Instead, use this function to

  50.       convert the password to encrypted form before it is sent.

  51.      </p><p>

  52.       The <em class="parameter"><code>passwd</code></em> and <em class="parameter"><code>user</code></em> arguments

  53.       are the cleartext password, and the SQL name of the user it is for.

  54.       <em class="parameter"><code>algorithm</code></em> specifies the encryption algorithm

  55.       to use to encrypt the password. Currently supported algorithms are

  56.       <code class="literal">md5</code> and <code class="literal">scram-sha-256</code> (<code class="literal">on</code> and

  57.       <code class="literal">off</code> are also accepted as aliases for <code class="literal">md5</code>, for

  58.       compatibility with older server versions). Note that support for

  59.       <code class="literal">scram-sha-256</code> was introduced in <span class="productname">PostgreSQL</span>

  60.       version 10, and will not work correctly with older server versions. If

  61.       <em class="parameter"><code>algorithm</code></em> is <code class="symbol">NULL</code>, this function will query

  62.       the server for the current value of the

  63.       <a class="xref" href="runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION">password_encryption</a> setting. That can block, and

  64.       will fail if the current transaction is aborted, or if the connection

  65.       is busy executing another query. If you wish to use the default

  66.       algorithm for the server but want to avoid blocking, query

  67.       <code class="varname">password_encryption</code> yourself before calling

  68.       <code class="function">PQencryptPasswordConn</code>, and pass that value as the

  69.       <em class="parameter"><code>algorithm</code></em>.

  70.      </p><p>

  71.       The return value is a string allocated by <code class="function">malloc</code>.

  72.       The caller can assume the string doesn't contain any special characters

  73.       that would require escaping.  Use <code class="function">PQfreemem</code> to free the

  74.       result when done with it. On error, returns <code class="symbol">NULL</code>, and

  75.       a suitable message is stored in the connection object.

  76.      </p></dd><dt id="LIBPQ-PQENCRYPTPASSWORD"><span class="term">

  77.      <code class="function">PQencryptPassword</code>

  78.      <a id="id-1.7.3.18.3.4.1.2" class="indexterm"></a>

  79.     </span></dt><dd><p>

  80.       Prepares the md5-encrypted form of a <span class="productname">PostgreSQL</span> password.

  81. </p><pre class="synopsis">

  82. char *PQencryptPassword(const char *passwd, const char *user);

  83. </pre><p>

  84.       <code class="function">PQencryptPassword</code> is an older, deprecated version of

  85.       <code class="function">PQencryptPasswordConn</code>. The difference is that

  86.       <code class="function">PQencryptPassword</code> does not

  87.       require a connection object, and <code class="literal">md5</code> is always used as the

  88.       encryption algorithm.

  89.      </p></dd><dt id="LIBPQ-PQMAKEEMPTYPGRESULT"><span class="term">

  90.      <code class="function">PQmakeEmptyPGresult</code>

  91.      <a id="id-1.7.3.18.3.5.1.2" class="indexterm"></a>

  92.     </span></dt><dd><p>

  93.       Constructs an empty <code class="structname">PGresult</code> object with the given status.

  94. </p><pre class="synopsis">

  95. PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);

  96. </pre><p>

  97.      </p><p>

  98.       This is <span class="application">libpq</span>'s internal function to allocate and

  99.       initialize an empty <code class="structname">PGresult</code> object.  This

  100.       function returns <code class="symbol">NULL</code> if memory could not be allocated. It is

  101.       exported because some applications find it useful to generate result

  102.       objects (particularly objects with error status) themselves.  If

  103.       <em class="parameter"><code>conn</code></em> is not null and <em class="parameter"><code>status</code></em>

  104.       indicates an error, the current error message of the specified

  105.       connection is copied into the <code class="structname">PGresult</code>.

  106.       Also, if <em class="parameter"><code>conn</code></em> is not null, any event procedures

  107.       registered in the connection are copied into the

  108.       <code class="structname">PGresult</code>.  (They do not get

  109.       <code class="literal">PGEVT_RESULTCREATE</code> calls, but see

  110.       <code class="function">PQfireResultCreateEvents</code>.)

  111.       Note that <code class="function">PQclear</code> should eventually be called

  112.       on the object, just as with a <code class="structname">PGresult</code>

  113.       returned by <span class="application">libpq</span> itself.

  114.      </p></dd><dt id="LIBPQ-PQFIRERESULTCREATEEVENTS"><span class="term">

  115.      <code class="function">PQfireResultCreateEvents</code>

  116.      <a id="id-1.7.3.18.3.6.1.2" class="indexterm"></a>

  117.     </span></dt><dd><p>

  118.       Fires a <code class="literal">PGEVT_RESULTCREATE</code> event (see <a class="xref" href="libpq-events.html" title="33.13. Event System">Section 33.13</a>) for each event procedure registered in the

  119.       <code class="structname">PGresult</code> object.  Returns non-zero for success,

  120.       zero if any event procedure fails.

  121. 

  122. </p><pre class="synopsis">

  123. int PQfireResultCreateEvents(PGconn *conn, PGresult *res);

  124. </pre><p>

  125.      </p><p>

  126.       The <code class="literal">conn</code> argument is passed through to event procedures

  127.       but not used directly.  It can be <code class="symbol">NULL</code> if the event

  128.       procedures won't use it.

  129.      </p><p>

  130.       Event procedures that have already received a

  131.       <code class="literal">PGEVT_RESULTCREATE</code> or <code class="literal">PGEVT_RESULTCOPY</code> event

  132.       for this object are not fired again.

  133.      </p><p>

  134.       The main reason that this function is separate from

  135.       <code class="function">PQmakeEmptyPGresult</code> is that it is often appropriate

  136.       to create a <code class="structname">PGresult</code> and fill it with data

  137.       before invoking the event procedures.

  138.      </p></dd><dt id="LIBPQ-PQCOPYRESULT"><span class="term">

  139.      <code class="function">PQcopyResult</code>

  140.      <a id="id-1.7.3.18.3.7.1.2" class="indexterm"></a>

  141.     </span></dt><dd><p>

  142.       Makes a copy of a <code class="structname">PGresult</code> object.  The copy is

  143.       not linked to the source result in any way and

  144.       <code class="function">PQclear</code> must be called when the copy is no longer

  145.       needed.  If the function fails, <code class="symbol">NULL</code> is returned.

  146. 

  147. </p><pre class="synopsis">

  148. PGresult *PQcopyResult(const PGresult *src, int flags);

  149. </pre><p>

  150.      </p><p>

  151.       This is not intended to make an exact copy.  The returned result is

  152.       always put into <code class="literal">PGRES_TUPLES_OK</code> status, and does not

  153.       copy any error message in the source.  (It does copy the command status

  154.       string, however.)  The <em class="parameter"><code>flags</code></em> argument determines

  155.       what else is copied.  It is a bitwise OR of several flags.

  156.       <code class="literal">PG_COPYRES_ATTRS</code> specifies copying the source

  157.       result's attributes (column definitions).

  158.       <code class="literal">PG_COPYRES_TUPLES</code> specifies copying the source

  159.       result's tuples.  (This implies copying the attributes, too.)

  160.       <code class="literal">PG_COPYRES_NOTICEHOOKS</code> specifies

  161.       copying the source result's notify hooks.

  162.       <code class="literal">PG_COPYRES_EVENTS</code> specifies copying the source

  163.       result's events.  (But any instance data associated with the source

  164.       is not copied.)

  165.      </p></dd><dt id="LIBPQ-PQSETRESULTATTRS"><span class="term">

  166.      <code class="function">PQsetResultAttrs</code>

  167.      <a id="id-1.7.3.18.3.8.1.2" class="indexterm"></a>

  168.     </span></dt><dd><p>

  169.       Sets the attributes of a <code class="structname">PGresult</code> object.

  170. </p><pre class="synopsis">

  171. int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);

  172. </pre><p>

  173.      </p><p>

  174.       The provided <em class="parameter"><code>attDescs</code></em> are copied into the result.

  175.       If the <em class="parameter"><code>attDescs</code></em> pointer is <code class="symbol">NULL</code> or

  176.       <em class="parameter"><code>numAttributes</code></em> is less than one, the request is

  177.       ignored and the function succeeds.  If <em class="parameter"><code>res</code></em>

  178.       already contains attributes, the function will fail.  If the function

  179.       fails, the return value is zero.  If the function succeeds, the return

  180.       value is non-zero.

  181.      </p></dd><dt id="LIBPQ-PQSETVALUE"><span class="term">

  182.      <code class="function">PQsetvalue</code>

  183.      <a id="id-1.7.3.18.3.9.1.2" class="indexterm"></a>

  184.     </span></dt><dd><p>

  185.       Sets a tuple field value of a <code class="structname">PGresult</code> object.

  186. </p><pre class="synopsis">

  187. int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);

  188. </pre><p>

  189.      </p><p>

  190.       The function will automatically grow the result's internal tuples array

  191.       as needed.  However, the <em class="parameter"><code>tup_num</code></em> argument must be

  192.       less than or equal to <code class="function">PQntuples</code>, meaning this

  193.       function can only grow the tuples array one tuple at a time.  But any

  194.       field of any existing tuple can be modified in any order.  If a value at

  195.       <em class="parameter"><code>field_num</code></em> already exists, it will be overwritten.

  196.       If <em class="parameter"><code>len</code></em> is -1 or

  197.       <em class="parameter"><code>value</code></em> is <code class="symbol">NULL</code>, the field value

  198.       will be set to an SQL null value.  The

  199.       <em class="parameter"><code>value</code></em> is copied into the result's private storage,

  200.       thus is no longer needed after the function

  201.       returns.  If the function fails, the return value is zero.  If the

  202.       function succeeds, the return value is non-zero.

  203.      </p></dd><dt id="LIBPQ-PQRESULTALLOC"><span class="term">

  204.      <code class="function">PQresultAlloc</code>

  205.      <a id="id-1.7.3.18.3.10.1.2" class="indexterm"></a>

  206.     </span></dt><dd><p>

  207.       Allocate subsidiary storage for a <code class="structname">PGresult</code> object.

  208. </p><pre class="synopsis">

  209. void *PQresultAlloc(PGresult *res, size_t nBytes);

  210. </pre><p>

  211.      </p><p>

  212.       Any memory allocated with this function will be freed when

  213.       <em class="parameter"><code>res</code></em> is cleared.  If the function fails,

  214.       the return value is <code class="symbol">NULL</code>.  The result is

  215.       guaranteed to be adequately aligned for any type of data,

  216.       just as for <code class="function">malloc</code>.

  217.      </p></dd><dt id="LIBPQ-PQRESULTMEMORYSIZE"><span class="term">

  218.      <code class="function">PQresultMemorySize</code>

  219.      <a id="id-1.7.3.18.3.11.1.2" class="indexterm"></a>

  220.     </span></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 space that will be freed by <code class="function">PQclear</code>.

  230.       This information can be useful for managing memory consumption.

  231.      </p></dd><dt id="LIBPQ-PQLIBVERSION"><span class="term">

  232.      <code class="function">PQlibVersion</code>

  233.      <a id="id-1.7.3.18.3.12.1.2" class="indexterm"></a>

  234.     </span></dt><dd><p>

  235.       Return the version of <span class="productname">libpq</span> that is being used.

  236. </p><pre class="synopsis">

  237. int PQlibVersion(void);

  238. </pre><p>

  239.      </p><p>

  240.       The result of this function can be used to determine, at

  241.       run time, whether specific functionality is available in the currently

  242.       loaded version of libpq. The function can be used, for example,

  243.       to determine which connection options are available in

  244.       <code class="function">PQconnectdb</code>.

  245.      </p><p>

  246.       The result is formed by multiplying the library's major version

  247.       number by 10000 and adding the minor version number.  For example,

  248.       version 10.1 will be returned as 100001, and version 11.0 will be

  249.       returned as 110000.

  250.      </p><p>

  251.       Prior to major version 10, <span class="productname">PostgreSQL</span> used

  252.       three-part version numbers in which the first two parts together

  253.       represented the major version.  For those

  254.       versions, <code class="function">PQlibVersion</code> uses two digits for each

  255.       part; for example version 9.1.5 will be returned as 90105, and

  256.       version 9.2.0 will be returned as 90200.

  257.      </p><p>

  258.       Therefore, for purposes of determining feature compatibility,

  259.       applications should divide the result of <code class="function">PQlibVersion</code>

  260.       by 100 not 10000 to determine a logical major version number.

  261.       In all release series, only the last two digits differ between

  262.       minor releases (bug-fix releases).

  263.      </p><div class="note"><h3 class="title">Note</h3><p>

  264.        This function appeared in <span class="productname">PostgreSQL</span> version 9.1, so

  265.        it cannot be used to detect required functionality in earlier

  266.        versions, since calling it will create a link dependency

  267.        on version 9.1 or later.

  268.       </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">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-notice-processing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.10. Control Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 33.12. Notice Processing</td></tr></table></div></body></html>
上海开阖软件有限公司 沪ICP备12045867号-1