Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Следить 1
В избранное 0
Вики 捐赠
gooderp18绿色标准版
Вы не можете выбрать более 25 тем Темы должны начинаться с буквы или цифры, могут содержать дефисы(-) и должны содержать не более 35 символов.
Дерево: 0f75e31513
Ветки Теги
${ item.name }
Создать ветку ${ searchTerm }
из '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/PostgreSQL/doc/postgresql/html/libpq-exec.html

1164 lines
74KB
Исходник Blame История 

  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.3. Command Execution 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-status.html" title="33.2. Connection Status Functions" /><link rel="next" href="libpq-async.html" title="33.4. Asynchronous Command 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.3. Command Execution Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-status.html" title="33.2. Connection Status 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-async.html" title="33.4. Asynchronous Command Processing">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="LIBPQ-EXEC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.3. Command Execution Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-MAIN">33.3.1. Main Functions</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">33.3.2. Retrieving Query Result Information</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-NONSELECT">33.3.3. Retrieving Other Result Information</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">33.3.4. Escaping Strings for Inclusion in SQL Commands</a></span></dt></dl></div><p>

  3.    Once a connection to a database server has been successfully

  4.    established, the functions described here are used to perform

  5.    SQL queries and commands.

  6.   </p><div class="sect2" id="LIBPQ-EXEC-MAIN"><div class="titlepage"><div><div><h3 class="title">33.3.1. Main Functions</h3></div></div></div><p>

  7.     </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQEXEC"><span class="term">

  8.        <code class="function">PQexec</code>

  9.        <a id="id-1.7.3.10.3.2.1.1.1.2" class="indexterm"></a>

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

  11.         Submits a command to the server and waits for the result.

  12. 

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

  14. PGresult *PQexec(PGconn *conn, const char *command);

  15. </pre><p>

  16.        </p><p>

  17.         Returns a <code class="structname">PGresult</code> pointer or possibly a null

  18.         pointer.  A non-null pointer will generally be returned except in

  19.         out-of-memory conditions or serious errors such as inability to send

  20.         the command to the server.  The <code class="function">PQresultStatus</code> function

  21.         should be called to check the return value for any errors (including

  22.         the value of a null pointer, in which case it will return

  23.         <code class="symbol">PGRES_FATAL_ERROR</code>).  Use

  24.         <code class="function">PQerrorMessage</code> to get more information about such

  25.         errors.

  26.        </p></dd></dl></div><p>

  27. 

  28.     The command string can include multiple SQL commands

  29.     (separated by semicolons).  Multiple queries sent in a single

  30.     <code class="function">PQexec</code> call are processed in a single transaction, unless

  31.     there are explicit <code class="command">BEGIN</code>/<code class="command">COMMIT</code>

  32.     commands included in the query string to divide it into multiple

  33.     transactions.  (See <a class="xref" href="protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT" title="52.2.2.1. Multiple Statements in a Simple Query">Section 52.2.2.1</a>

  34.     for more details about how the server handles multi-query strings.)

  35.     Note however that the returned

  36.     <code class="structname">PGresult</code> structure describes only the result

  37.     of the last command executed from the string.  Should one of the

  38.     commands fail, processing of the string stops with it and the returned

  39.     <code class="structname">PGresult</code> describes the error condition.

  40.    </p><p>

  41.     </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQEXECPARAMS"><span class="term">

  42.        <code class="function">PQexecParams</code>

  43.        <a id="id-1.7.3.10.3.3.1.1.1.2" class="indexterm"></a>

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

  45.         Submits a command to the server and waits for the result,

  46.         with the ability to pass parameters separately from the SQL

  47.         command text.

  48. 

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

  50. PGresult *PQexecParams(PGconn *conn,

  51.                        const char *command,

  52.                        int nParams,

  53.                        const Oid *paramTypes,

  54.                        const char * const *paramValues,

  55.                        const int *paramLengths,

  56.                        const int *paramFormats,

  57.                        int resultFormat);

  58. </pre><p>

  59.        </p><p>

  60.         <code class="function">PQexecParams</code> is like <code class="function">PQexec</code>, but offers additional

  61.         functionality: parameter values can be specified separately from the command

  62.         string proper, and query results can be requested in either text or binary

  63.         format.  <code class="function">PQexecParams</code> is supported only in protocol 3.0 and later

  64.         connections; it will fail when using protocol 2.0.

  65.        </p><p>

  66.         The function arguments are:

  67. 

  68.         </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>conn</code></em></span></dt><dd><p>

  69.             The connection object to send the command through.

  70.            </p></dd><dt><span class="term"><em class="parameter"><code>command</code></em></span></dt><dd><p>

  71.             The SQL command string to be executed. If parameters are used,

  72.             they are referred to in the command string as <code class="literal">$1</code>,

  73.             <code class="literal">$2</code>, etc.

  74.            </p></dd><dt><span class="term"><em class="parameter"><code>nParams</code></em></span></dt><dd><p>

  75.             The number of parameters supplied; it is the length of the arrays

  76.             <em class="parameter"><code>paramTypes[]</code></em>, <em class="parameter"><code>paramValues[]</code></em>,

  77.             <em class="parameter"><code>paramLengths[]</code></em>, and <em class="parameter"><code>paramFormats[]</code></em>. (The

  78.             array pointers can be <code class="symbol">NULL</code> when <em class="parameter"><code>nParams</code></em>

  79.             is zero.)

  80.            </p></dd><dt><span class="term"><em class="parameter"><code>paramTypes[]</code></em></span></dt><dd><p>

  81.             Specifies, by OID, the data types to be assigned to the

  82.             parameter symbols.  If <em class="parameter"><code>paramTypes</code></em> is

  83.             <code class="symbol">NULL</code>, or any particular element in the array

  84.             is zero, the server infers a data type for the parameter symbol

  85.             in the same way it would do for an untyped literal string.

  86.            </p></dd><dt><span class="term"><em class="parameter"><code>paramValues[]</code></em></span></dt><dd><p>

  87.             Specifies the actual values of the parameters.  A null pointer

  88.             in this array means the corresponding parameter is null;

  89.             otherwise the pointer points to a zero-terminated text string

  90.             (for text format) or binary data in the format expected by the

  91.             server (for binary format).

  92.            </p></dd><dt><span class="term"><em class="parameter"><code>paramLengths[]</code></em></span></dt><dd><p>

  93.             Specifies the actual data lengths of binary-format parameters.

  94.             It is ignored for null parameters and text-format parameters.

  95.             The array pointer can be null when there are no binary parameters.

  96.            </p></dd><dt><span class="term"><em class="parameter"><code>paramFormats[]</code></em></span></dt><dd><p>

  97.             Specifies whether parameters are text (put a zero in the

  98.             array entry for the corresponding parameter) or binary (put

  99.             a one in the array entry for the corresponding parameter).

  100.             If the array pointer is null then all parameters are presumed

  101.             to be text strings.

  102.            </p><p>

  103.             Values passed in binary format require knowledge of

  104.             the internal representation expected by the backend.

  105.             For example, integers must be passed in network byte

  106.             order.  Passing <code class="type">numeric</code> values requires

  107.             knowledge of the server storage format, as implemented

  108.             in

  109.             <code class="filename">src/backend/utils/adt/numeric.c::numeric_send()</code> and

  110.             <code class="filename">src/backend/utils/adt/numeric.c::numeric_recv()</code>.

  111.            </p></dd><dt><span class="term"><em class="parameter"><code>resultFormat</code></em></span></dt><dd><p>

  112.             Specify zero to obtain results in text format, or one to obtain

  113.             results in binary format.  (There is not currently a provision

  114.             to obtain different result columns in different formats,

  115.             although that is possible in the underlying protocol.)

  116.            </p></dd></dl></div><p>

  117.        </p></dd></dl></div><p>

  118.    </p><p>

  119.     The primary advantage of <code class="function">PQexecParams</code> over

  120.     <code class="function">PQexec</code> is that parameter values can be separated from the

  121.     command string, thus avoiding the need for tedious and error-prone

  122.     quoting and escaping.

  123.    </p><p>

  124.     Unlike <code class="function">PQexec</code>, <code class="function">PQexecParams</code> allows at most

  125.     one SQL command in the given string.  (There can be semicolons in it,

  126.     but not more than one nonempty command.)  This is a limitation of the

  127.     underlying protocol, but has some usefulness as an extra defense against

  128.     SQL-injection attacks.

  129.    </p><div class="tip"><h3 class="title">Tip</h3><p>

  130.      Specifying parameter types via OIDs is tedious, particularly if you prefer

  131.      not to hard-wire particular OID values into your program.  However, you can

  132.      avoid doing so even in cases where the server by itself cannot determine the

  133.      type of the parameter, or chooses a different type than you want.  In the

  134.      SQL command text, attach an explicit cast to the parameter symbol to show what

  135.      data type you will send.  For example:

  136. </p><pre class="programlisting">

  137. SELECT * FROM mytable WHERE x = $1::bigint;

  138. </pre><p>

  139.      This forces parameter <code class="literal">$1</code> to be treated as <code class="type">bigint</code>, whereas

  140.      by default it would be assigned the same type as <code class="literal">x</code>.  Forcing the

  141.      parameter type decision, either this way or by specifying a numeric type OID,

  142.      is strongly recommended when sending parameter values in binary format, because

  143.      binary format has less redundancy than text format and so there is less chance

  144.      that the server will detect a type mismatch mistake for you.

  145.     </p></div><p>

  146.     </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPREPARE"><span class="term"><code class="function">PQprepare</code>

  147.        <a id="id-1.7.3.10.3.7.1.1.1.2" class="indexterm"></a>

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

  149.         Submits a request to create a prepared statement with the

  150.         given parameters, and waits for completion.

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

  152. PGresult *PQprepare(PGconn *conn,

  153.                     const char *stmtName,

  154.                     const char *query,

  155.                     int nParams,

  156.                     const Oid *paramTypes);

  157. </pre><p>

  158.        </p><p>

  159.         <code class="function">PQprepare</code> creates a prepared statement for later

  160.         execution with <code class="function">PQexecPrepared</code>.  This feature allows

  161.         commands to be executed repeatedly without being parsed and

  162.         planned each time;  see <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a> for details.

  163.         <code class="function">PQprepare</code> is supported only in protocol 3.0 and later

  164.         connections; it will fail when using protocol 2.0.

  165.        </p><p>

  166.         The function creates a prepared statement named

  167.         <em class="parameter"><code>stmtName</code></em> from the <em class="parameter"><code>query</code></em> string, which

  168.         must contain a single SQL command.  <em class="parameter"><code>stmtName</code></em> can be

  169.         <code class="literal">""</code> to create an unnamed statement, in which case any

  170.         pre-existing unnamed statement is automatically replaced; otherwise

  171.         it is an error if the statement name is already defined in the

  172.         current session.  If any parameters are used, they are referred

  173.         to in the query as <code class="literal">$1</code>, <code class="literal">$2</code>, etc.

  174.         <em class="parameter"><code>nParams</code></em> is the number of parameters for which types

  175.         are pre-specified in the array <em class="parameter"><code>paramTypes[]</code></em>.  (The

  176.         array pointer can be <code class="symbol">NULL</code> when

  177.         <em class="parameter"><code>nParams</code></em> is zero.) <em class="parameter"><code>paramTypes[]</code></em>

  178.         specifies, by OID, the data types to be assigned to the parameter

  179.         symbols.  If <em class="parameter"><code>paramTypes</code></em> is <code class="symbol">NULL</code>,

  180.         or any particular element in the array is zero, the server assigns

  181.         a data type to the parameter symbol in the same way it would do

  182.         for an untyped literal string.  Also, the query can use parameter

  183.         symbols with numbers higher than <em class="parameter"><code>nParams</code></em>; data types

  184.         will be inferred for these symbols as well.  (See

  185.         <code class="function">PQdescribePrepared</code> for a means to find out

  186.         what data types were inferred.)

  187.        </p><p>

  188.         As with <code class="function">PQexec</code>, the result is normally a

  189.         <code class="structname">PGresult</code> object whose contents indicate

  190.         server-side success or failure.  A null result indicates

  191.         out-of-memory or inability to send the command at all.  Use

  192.         <code class="function">PQerrorMessage</code> to get more information about

  193.         such errors.

  194.        </p></dd></dl></div><p>

  195. 

  196.     Prepared statements for use with <code class="function">PQexecPrepared</code> can also

  197.     be created by executing SQL <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a>

  198.     statements.  Also, although there is no <span class="application">libpq</span>

  199.     function for deleting a prepared statement, the SQL <a class="xref" href="sql-deallocate.html" title="DEALLOCATE"><span class="refentrytitle">DEALLOCATE</span></a> statement

  200.     can be used for that purpose.

  201.    </p><p>

  202.     </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQEXECPREPARED"><span class="term">

  203.        <code class="function">PQexecPrepared</code>

  204.        <a id="id-1.7.3.10.3.8.1.1.1.2" class="indexterm"></a>

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

  206.         Sends a request to execute a prepared statement with given

  207.         parameters, and waits for the result.

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

  209. PGresult *PQexecPrepared(PGconn *conn,

  210.                          const char *stmtName,

  211.                          int nParams,

  212.                          const char * const *paramValues,

  213.                          const int *paramLengths,

  214.                          const int *paramFormats,

  215.                          int resultFormat);

  216. </pre><p>

  217.        </p><p>

  218.         <code class="function">PQexecPrepared</code> is like <code class="function">PQexecParams</code>,

  219.         but the command to be executed is specified by naming a

  220.         previously-prepared statement, instead of giving a query string.

  221.         This feature allows commands that will be used repeatedly to be

  222.         parsed and planned just once, rather than each time they are

  223.         executed.  The statement must have been prepared previously in

  224.         the current session.  <code class="function">PQexecPrepared</code> is supported

  225.         only in protocol 3.0 and later connections; it will fail when

  226.         using protocol 2.0.

  227.        </p><p>

  228.         The parameters are identical to <code class="function">PQexecParams</code>, except that the

  229.         name of a prepared statement is given instead of a query string, and the

  230.         <em class="parameter"><code>paramTypes[]</code></em> parameter is not present (it is not needed since

  231.         the prepared statement's parameter types were determined when it was created).

  232.        </p></dd><dt id="LIBPQ-PQDESCRIBEPREPARED"><span class="term">

  233.        <code class="function">PQdescribePrepared</code>

  234.        <a id="id-1.7.3.10.3.8.1.2.1.2" class="indexterm"></a>

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

  236.         Submits a request to obtain information about the specified

  237.         prepared statement, and waits for completion.

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

  239. PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);

  240. </pre><p>

  241.        </p><p>

  242.         <code class="function">PQdescribePrepared</code> allows an application to obtain

  243.         information about a previously prepared statement.

  244.         <code class="function">PQdescribePrepared</code> is supported only in protocol 3.0

  245.         and later connections; it will fail when using protocol 2.0.

  246.        </p><p>

  247.         <em class="parameter"><code>stmtName</code></em> can be <code class="literal">""</code> or <code class="symbol">NULL</code> to reference

  248.         the unnamed statement, otherwise it must be the name of an existing

  249.         prepared statement.  On success, a <code class="structname">PGresult</code> with

  250.         status <code class="literal">PGRES_COMMAND_OK</code> is returned.  The

  251.         functions <code class="function">PQnparams</code> and

  252.         <code class="function">PQparamtype</code> can be applied to this

  253.         <code class="structname">PGresult</code> to obtain information about the parameters

  254.         of the prepared statement, and the functions

  255.         <code class="function">PQnfields</code>, <code class="function">PQfname</code>,

  256.         <code class="function">PQftype</code>, etc provide information about the

  257.         result columns (if any) of the statement.

  258.        </p></dd><dt id="LIBPQ-PQDESCRIBEPORTAL"><span class="term">

  259.        <code class="function">PQdescribePortal</code>

  260.        <a id="id-1.7.3.10.3.8.1.3.1.2" class="indexterm"></a>

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

  262.         Submits a request to obtain information about the specified

  263.         portal, and waits for completion.

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

  265. PGresult *PQdescribePortal(PGconn *conn, const char *portalName);

  266. </pre><p>

  267.        </p><p>

  268.         <code class="function">PQdescribePortal</code> allows an application to obtain

  269.         information about a previously created portal.

  270.         (<span class="application">libpq</span> does not provide any direct access to

  271.         portals, but you can use this function to inspect the properties

  272.         of a cursor created with a <code class="command">DECLARE CURSOR</code> SQL command.)

  273.         <code class="function">PQdescribePortal</code> is supported only in protocol 3.0

  274.         and later connections; it will fail when using protocol 2.0.

  275.        </p><p>

  276.         <em class="parameter"><code>portalName</code></em> can be <code class="literal">""</code> or <code class="symbol">NULL</code> to reference

  277.         the unnamed portal, otherwise it must be the name of an existing

  278.         portal.  On success, a <code class="structname">PGresult</code> with status

  279.         <code class="literal">PGRES_COMMAND_OK</code> is returned.  The functions

  280.         <code class="function">PQnfields</code>, <code class="function">PQfname</code>,

  281.         <code class="function">PQftype</code>, etc can be applied to the

  282.         <code class="structname">PGresult</code> to obtain information about the result

  283.         columns (if any) of the portal.

  284.        </p></dd></dl></div><p>

  285.    </p><p>

  286.     The <code class="structname">PGresult</code><a id="id-1.7.3.10.3.9.2" class="indexterm"></a>

  287.     structure encapsulates the result returned by the server.

  288.     <span class="application">libpq</span> application programmers should be

  289.     careful to maintain the <code class="structname">PGresult</code> abstraction.

  290.     Use the accessor functions below to get at the contents of

  291.     <code class="structname">PGresult</code>.  Avoid directly referencing the

  292.     fields of the <code class="structname">PGresult</code> structure because they

  293.     are subject to change in the future.

  294. 

  295.     </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQRESULTSTATUS"><span class="term">

  296.        <code class="function">PQresultStatus</code>

  297.        <a id="id-1.7.3.10.3.9.7.1.1.2" class="indexterm"></a>

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

  299.         Returns the result status of the command.

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

  301. ExecStatusType PQresultStatus(const PGresult *res);

  302. </pre><p>

  303.        </p><p>

  304.         <code class="function">PQresultStatus</code> can return one of the following values:

  305. 

  306.         </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PGRES-EMPTY-QUERY"><span class="term"><code class="literal">PGRES_EMPTY_QUERY</code></span></dt><dd><p>

  307.             The string sent to the server was empty.

  308.            </p></dd><dt id="LIBPQ-PGRES-COMMAND-OK"><span class="term"><code class="literal">PGRES_COMMAND_OK</code></span></dt><dd><p>

  309.             Successful completion of a command returning no data.

  310.            </p></dd><dt id="LIBPQ-PGRES-TUPLES-OK"><span class="term"><code class="literal">PGRES_TUPLES_OK</code></span></dt><dd><p>

  311.             Successful completion of a command returning data (such as

  312.             a <code class="command">SELECT</code> or <code class="command">SHOW</code>).

  313.            </p></dd><dt id="LIBPQ-PGRES-COPY-OUT"><span class="term"><code class="literal">PGRES_COPY_OUT</code></span></dt><dd><p>

  314.             Copy Out (from server) data transfer started.

  315.            </p></dd><dt id="LIBPQ-PGRES-COPY-IN"><span class="term"><code class="literal">PGRES_COPY_IN</code></span></dt><dd><p>

  316.             Copy In (to server) data transfer started.

  317.            </p></dd><dt id="LIBPQ-PGRES-BAD-RESPONSE"><span class="term"><code class="literal">PGRES_BAD_RESPONSE</code></span></dt><dd><p>

  318.             The server's response was not understood.

  319.            </p></dd><dt id="LIBPQ-PGRES-NONFATAL-ERROR"><span class="term"><code class="literal">PGRES_NONFATAL_ERROR</code></span></dt><dd><p>

  320.             A nonfatal error (a notice or warning) occurred.

  321.            </p></dd><dt id="LIBPQ-PGRES-FATAL-ERROR"><span class="term"><code class="literal">PGRES_FATAL_ERROR</code></span></dt><dd><p>

  322.             A fatal error occurred.

  323.            </p></dd><dt id="LIBPQ-PGRES-COPY-BOTH"><span class="term"><code class="literal">PGRES_COPY_BOTH</code></span></dt><dd><p>

  324.             Copy In/Out (to and from server) data transfer started.  This

  325.             feature is currently used only for streaming replication,

  326.             so this status should not occur in ordinary applications.

  327.            </p></dd><dt id="LIBPQ-PGRES-SINGLE-TUPLE"><span class="term"><code class="literal">PGRES_SINGLE_TUPLE</code></span></dt><dd><p>

  328.             The <code class="structname">PGresult</code> contains a single result tuple

  329.             from the current command.  This status occurs only when

  330.             single-row mode has been selected for the query

  331.             (see <a class="xref" href="libpq-single-row-mode.html" title="33.5. Retrieving Query Results Row-by-Row">Section 33.5</a>).

  332.            </p></dd></dl></div><p>

  333. 

  334.         If the result status is <code class="literal">PGRES_TUPLES_OK</code> or

  335.         <code class="literal">PGRES_SINGLE_TUPLE</code>, then

  336.         the functions described below can be used to retrieve the rows

  337.         returned by the query.  Note that a <code class="command">SELECT</code>

  338.         command that happens to retrieve zero rows still shows

  339.         <code class="literal">PGRES_TUPLES_OK</code>.

  340.         <code class="literal">PGRES_COMMAND_OK</code> is for commands that can never

  341.         return rows (<code class="command">INSERT</code> or <code class="command">UPDATE</code>

  342.         without a <code class="literal">RETURNING</code> clause,

  343.         etc.). A response of <code class="literal">PGRES_EMPTY_QUERY</code> might

  344.         indicate a bug in the client software.

  345.        </p><p>

  346.         A result of status <code class="symbol">PGRES_NONFATAL_ERROR</code> will

  347.         never be returned directly by <code class="function">PQexec</code> or other

  348.         query execution functions; results of this kind are instead passed

  349.         to the notice processor (see <a class="xref" href="libpq-notice-processing.html" title="33.12. Notice Processing">Section 33.12</a>).

  350.        </p></dd><dt id="LIBPQ-PQRESSTATUS"><span class="term">

  351.        <code class="function">PQresStatus</code>

  352.        <a id="id-1.7.3.10.3.9.7.2.1.2" class="indexterm"></a>

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

  354.         Converts the enumerated type returned by

  355.         <code class="function">PQresultStatus</code> into a string constant describing the

  356.         status code. The caller should not free the result.

  357. 

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

  359. char *PQresStatus(ExecStatusType status);

  360. </pre><p>

  361.        </p></dd><dt id="LIBPQ-PQRESULTERRORMESSAGE"><span class="term">

  362.        <code class="function">PQresultErrorMessage</code>

  363.        <a id="id-1.7.3.10.3.9.7.3.1.2" class="indexterm"></a>

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

  365.         Returns the error message associated with the command, or an empty string

  366.         if there was no error.

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

  368. char *PQresultErrorMessage(const PGresult *res);

  369. </pre><p>

  370.         If there was an error, the returned string will include a trailing

  371.         newline.  The caller should not free the result directly. It will

  372.         be freed when the associated <code class="structname">PGresult</code> handle is

  373.         passed to <code class="function">PQclear</code>.

  374.        </p><p>

  375.         Immediately following a <code class="function">PQexec</code> or

  376.         <code class="function">PQgetResult</code> call,

  377.         <code class="function">PQerrorMessage</code> (on the connection) will return

  378.         the same string as <code class="function">PQresultErrorMessage</code> (on

  379.         the result).  However, a <code class="structname">PGresult</code> will

  380.         retain its error message until destroyed, whereas the connection's

  381.         error message will change when subsequent operations are done.

  382.         Use <code class="function">PQresultErrorMessage</code> when you want to

  383.         know the status associated with a particular

  384.         <code class="structname">PGresult</code>; use

  385.         <code class="function">PQerrorMessage</code> when you want to know the

  386.         status from the latest operation on the connection.

  387.        </p></dd><dt id="LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><span class="term">

  388.        <code class="function">PQresultVerboseErrorMessage</code>

  389.        <a id="id-1.7.3.10.3.9.7.4.1.2" class="indexterm"></a>

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

  391.         Returns a reformatted version of the error message associated with

  392.         a <code class="structname">PGresult</code> object.

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

  394. char *PQresultVerboseErrorMessage(const PGresult *res,

  395.                                   PGVerbosity verbosity,

  396.                                   PGContextVisibility show_context);

  397. </pre><p>

  398.         In some situations a client might wish to obtain a more detailed

  399.         version of a previously-reported error.

  400.         <code class="function">PQresultVerboseErrorMessage</code> addresses this need

  401.         by computing the message that would have been produced

  402.         by <code class="function">PQresultErrorMessage</code> if the specified

  403.         verbosity settings had been in effect for the connection when the

  404.         given <code class="structname">PGresult</code> was generated.  If

  405.         the <code class="structname">PGresult</code> is not an error result,

  406.         <span class="quote">“<span class="quote">PGresult is not an error result</span>”</span> is reported instead.

  407.         The returned string includes a trailing newline.

  408.        </p><p>

  409.         Unlike most other functions for extracting data from

  410.         a <code class="structname">PGresult</code>, the result of this function is a freshly

  411.         allocated string.  The caller must free it

  412.         using <code class="function">PQfreemem()</code> when the string is no longer needed.

  413.        </p><p>

  414.         A NULL return is possible if there is insufficient memory.

  415.        </p></dd><dt id="LIBPQ-PQRESULTERRORFIELD"><span class="term"><code class="function">PQresultErrorField</code><a id="id-1.7.3.10.3.9.7.5.1.2" class="indexterm"></a></span></dt><dd><p>

  416.         Returns an individual field of an error report.

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

  418. char *PQresultErrorField(const PGresult *res, int fieldcode);

  419. </pre><p>

  420.         <em class="parameter"><code>fieldcode</code></em> is an error field identifier; see the symbols

  421.         listed below.  <code class="symbol">NULL</code> is returned if the

  422.         <code class="structname">PGresult</code> is not an error or warning result,

  423.         or does not include the specified field.  Field values will normally

  424.         not include a trailing newline. The caller should not free the

  425.         result directly. It will be freed when the

  426.         associated <code class="structname">PGresult</code> handle is passed to

  427.         <code class="function">PQclear</code>.

  428.        </p><p>

  429.         The following field codes are available:

  430.         </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PG-DIAG-SEVERITY"><span class="term"><code class="symbol">PG_DIAG_SEVERITY</code></span></dt><dd><p>

  431.             The severity; the field contents are <code class="literal">ERROR</code>,

  432.             <code class="literal">FATAL</code>, or <code class="literal">PANIC</code> (in an error message),

  433.             or <code class="literal">WARNING</code>, <code class="literal">NOTICE</code>, <code class="literal">DEBUG</code>,

  434.             <code class="literal">INFO</code>, or <code class="literal">LOG</code> (in a notice message), or

  435.             a localized translation of one of these.  Always present.

  436.            </p></dd><dt id="LIBPQ-PG-DIAG-SEVERITY-NONLOCALIZED"><span class="term"><code class="symbol">PG_DIAG_SEVERITY_NONLOCALIZED</code></span></dt><dd><p>

  437.             The severity; the field contents are <code class="literal">ERROR</code>,

  438.             <code class="literal">FATAL</code>, or <code class="literal">PANIC</code> (in an error message),

  439.             or <code class="literal">WARNING</code>, <code class="literal">NOTICE</code>, <code class="literal">DEBUG</code>,

  440.             <code class="literal">INFO</code>, or <code class="literal">LOG</code> (in a notice message).

  441.             This is identical to the <code class="symbol">PG_DIAG_SEVERITY</code> field except

  442.             that the contents are never localized.  This is present only in

  443.             reports generated by <span class="productname">PostgreSQL</span> versions 9.6

  444.             and later.

  445.            </p></dd><dt id="LIBPQ-PG-DIAG-SQLSTATE"><span class="term">

  446.            <code class="symbol">PG_DIAG_SQLSTATE</code>

  447.           <a id="id-1.7.3.10.3.9.7.5.2.2.1.3.1.2" class="indexterm"></a>

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

  449.             The SQLSTATE code for the error. The SQLSTATE code identifies

  450.             the type of error that has occurred; it can be used by

  451.             front-end applications to perform specific operations (such

  452.             as error handling) in response to a particular database error.

  453.             For a list of the possible SQLSTATE codes, see <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>. This field is not localizable,

  454.             and is always present.

  455.            </p></dd><dt id="LIBPQ-PG-DIAG-MESSAGE-PRIMARY"><span class="term"><code class="symbol">PG_DIAG_MESSAGE_PRIMARY</code></span></dt><dd><p>

  456.             The primary human-readable error message (typically one line).

  457.             Always present.

  458.            </p></dd><dt id="LIBPQ-PG-DIAG-MESSAGE-DETAIL"><span class="term"><code class="symbol">PG_DIAG_MESSAGE_DETAIL</code></span></dt><dd><p>

  459.             Detail: an optional secondary error message carrying more

  460.             detail about the problem.  Might run to multiple lines.

  461.            </p></dd><dt id="LIBPQ-PG-DIAG-MESSAGE-HINT"><span class="term"><code class="symbol">PG_DIAG_MESSAGE_HINT</code></span></dt><dd><p>

  462.             Hint: an optional suggestion what to do about the problem.

  463.             This is intended to differ from detail in that it offers advice

  464.             (potentially inappropriate) rather than hard facts.  Might

  465.             run to multiple lines.

  466.            </p></dd><dt id="LIBPQ-PG-DIAG-STATEMENT-POSITION"><span class="term"><code class="symbol">PG_DIAG_STATEMENT_POSITION</code></span></dt><dd><p>

  467.             A string containing a decimal integer indicating an error cursor

  468.             position as an index into the original statement string.  The

  469.             first character has index 1, and positions are measured in

  470.             characters not bytes.

  471.            </p></dd><dt id="LIBPQ-PG-DIAG-INTERNAL-POSITION"><span class="term"><code class="symbol">PG_DIAG_INTERNAL_POSITION</code></span></dt><dd><p>

  472.             This is defined the same as the

  473.             <code class="symbol">PG_DIAG_STATEMENT_POSITION</code> field, but it is used

  474.             when the cursor position refers to an internally generated

  475.             command rather than the one submitted by the client.  The

  476.             <code class="symbol">PG_DIAG_INTERNAL_QUERY</code> field will always appear when

  477.             this field appears.

  478.            </p></dd><dt id="LIBPQ-PG-DIAG-INTERNAL-QUERY"><span class="term"><code class="symbol">PG_DIAG_INTERNAL_QUERY</code></span></dt><dd><p>

  479.             The text of a failed internally-generated command.  This could

  480.             be, for example, a SQL query issued by a PL/pgSQL function.

  481.            </p></dd><dt id="LIBPQ-PG-DIAG-CONTEXT"><span class="term"><code class="symbol">PG_DIAG_CONTEXT</code></span></dt><dd><p>

  482.             An indication of the context in which the error occurred.

  483.             Presently this includes a call stack traceback of active

  484.             procedural language functions and internally-generated queries.

  485.             The trace is one entry per line, most recent first.

  486.            </p></dd><dt id="LIBPQ-PG-DIAG-SCHEMA-NAME"><span class="term"><code class="symbol">PG_DIAG_SCHEMA_NAME</code></span></dt><dd><p>

  487.             If the error was associated with a specific database object,

  488.             the name of the schema containing that object, if any.

  489.            </p></dd><dt id="LIBPQ-PG-DIAG-TABLE-NAME"><span class="term"><code class="symbol">PG_DIAG_TABLE_NAME</code></span></dt><dd><p>

  490.             If the error was associated with a specific table, the name of the

  491.             table.  (Refer to the schema name field for the name of the

  492.             table's schema.)

  493.            </p></dd><dt id="LIBPQ-PG-DIAG-COLUMN-NAME"><span class="term"><code class="symbol">PG_DIAG_COLUMN_NAME</code></span></dt><dd><p>

  494.             If the error was associated with a specific table column, the name

  495.             of the column.  (Refer to the schema and table name fields to

  496.             identify the table.)

  497.            </p></dd><dt id="LIBPQ-PG-DIAG-DATATYPE-NAME"><span class="term"><code class="symbol">PG_DIAG_DATATYPE_NAME</code></span></dt><dd><p>

  498.             If the error was associated with a specific data type, the name of

  499.             the data type.  (Refer to the schema name field for the name of

  500.             the data type's schema.)

  501.            </p></dd><dt id="LIBPQ-PG-DIAG-CONSTRAINT-NAME"><span class="term"><code class="symbol">PG_DIAG_CONSTRAINT_NAME</code></span></dt><dd><p>

  502.             If the error was associated with a specific constraint, the name

  503.             of the constraint.  Refer to fields listed above for the

  504.             associated table or domain.  (For this purpose, indexes are

  505.             treated as constraints, even if they weren't created with

  506.             constraint syntax.)

  507.            </p></dd><dt id="LIBPQ-PG-DIAG-SOURCE-FILE"><span class="term"><code class="symbol">PG_DIAG_SOURCE_FILE</code></span></dt><dd><p>

  508.             The file name of the source-code location where the error was

  509.             reported.

  510.            </p></dd><dt id="LIBPQ-PG-DIAG-SOURCE-LINE"><span class="term"><code class="symbol">PG_DIAG_SOURCE_LINE</code></span></dt><dd><p>

  511.             The line number of the source-code location where the error

  512.             was reported.

  513.            </p></dd><dt id="LIBPQ-PG-DIAG-SOURCE-FUNCTION"><span class="term"><code class="symbol">PG_DIAG_SOURCE_FUNCTION</code></span></dt><dd><p>

  514.             The name of the source-code function reporting the error.

  515.            </p></dd></dl></div><p>

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

  517.          The fields for schema name, table name, column name, data type name,

  518.          and constraint name are supplied only for a limited number of error

  519.          types; see <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>.  Do not assume that

  520.          the presence of any of these fields guarantees the presence of

  521.          another field.  Core error sources observe the interrelationships

  522.          noted above, but user-defined functions may use these fields in other

  523.          ways.  In the same vein, do not assume that these fields denote

  524.          contemporary objects in the current database.

  525.         </p></div><p>

  526.         The client is responsible for formatting displayed information to meet

  527.         its needs; in particular it should break long lines as needed.

  528.         Newline characters appearing in the error message fields should be

  529.         treated as paragraph breaks, not line breaks.

  530.        </p><p>

  531.         Errors generated internally by <span class="application">libpq</span> will

  532.         have severity and primary message, but typically no other fields.

  533.         Errors returned by a pre-3.0-protocol server will include severity and

  534.         primary message, and sometimes a detail message, but no other fields.

  535.        </p><p>

  536.         Note that error fields are only available from

  537.         <code class="structname">PGresult</code> objects, not

  538.         <code class="structname">PGconn</code> objects; there is no

  539.         <code class="function">PQerrorField</code> function.

  540.        </p></dd><dt id="LIBPQ-PQCLEAR"><span class="term"><code class="function">PQclear</code><a id="id-1.7.3.10.3.9.7.6.1.2" class="indexterm"></a></span></dt><dd><p>

  541.         Frees  the  storage  associated with a

  542.         <code class="structname">PGresult</code>.  Every command result should be

  543.         freed via <code class="function">PQclear</code> when it  is  no  longer

  544.         needed.

  545. 

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

  547. void PQclear(PGresult *res);

  548. </pre><p>

  549.        </p><p>

  550.         You can keep a <code class="structname">PGresult</code> object around for

  551.         as long as you need it; it does not go away when you issue a new

  552.         command, nor even if you close the connection.  To get rid of it,

  553.         you must call <code class="function">PQclear</code>.  Failure to do this

  554.         will result in memory leaks in your application.

  555.        </p></dd></dl></div><p>

  556.    </p></div><div class="sect2" id="LIBPQ-EXEC-SELECT-INFO"><div class="titlepage"><div><div><h3 class="title">33.3.2. Retrieving Query Result Information</h3></div></div></div><p>

  557.     These functions are used to extract information from a

  558.     <code class="structname">PGresult</code> object that represents a successful

  559.     query result (that is, one that has status

  560.     <code class="literal">PGRES_TUPLES_OK</code> or <code class="literal">PGRES_SINGLE_TUPLE</code>).

  561.     They can also be used to extract

  562.     information from a successful Describe operation: a Describe's result

  563.     has all the same column information that actual execution of the query

  564.     would provide, but it has zero rows.  For objects with other status values,

  565.     these functions will act as though the result has zero rows and zero columns.

  566.    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQNTUPLES"><span class="term">

  567.       <code class="function">PQntuples</code>

  568.       <a id="id-1.7.3.10.4.3.1.1.2" class="indexterm"></a>

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

  570.        Returns the number of rows (tuples) in the query result.

  571.        (Note that <code class="structname">PGresult</code> objects are limited to no more

  572.        than <code class="literal">INT_MAX</code> rows, so an <code class="type">int</code> result is

  573.        sufficient.)

  574. 

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

  576. int PQntuples(const PGresult *res);

  577. </pre><p>

  578. 

  579.       </p></dd><dt id="LIBPQ-PQNFIELDS"><span class="term">

  580.       <code class="function">PQnfields</code>

  581.       <a id="id-1.7.3.10.4.3.2.1.2" class="indexterm"></a>

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

  583.        Returns the number of columns (fields) in each row of the query

  584.        result.

  585. 

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

  587. int PQnfields(const PGresult *res);

  588. </pre><p>

  589.       </p></dd><dt id="LIBPQ-PQFNAME"><span class="term">

  590.       <code class="function">PQfname</code>

  591.       <a id="id-1.7.3.10.4.3.3.1.2" class="indexterm"></a>

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

  593.        Returns the column name associated with the given column number.

  594.        Column numbers start at 0. The caller should not free the result

  595.        directly. It will be freed when the associated

  596.        <code class="structname">PGresult</code> handle is passed to

  597.        <code class="function">PQclear</code>.

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

  599. char *PQfname(const PGresult *res,

  600.               int column_number);

  601. </pre><p>

  602.       </p><p>

  603.        <code class="symbol">NULL</code> is returned if the column number is out of range.

  604.       </p></dd><dt id="LIBPQ-PQFNUMBER"><span class="term">

  605.       <code class="function">PQfnumber</code>

  606.       <a id="id-1.7.3.10.4.3.4.1.2" class="indexterm"></a>

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

  608.        Returns the column number associated with the given column name.

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

  610. int PQfnumber(const PGresult *res,

  611.               const char *column_name);

  612. </pre><p>

  613.       </p><p>

  614.        -1 is returned if the given name does not match any column.

  615.       </p><p>

  616.        The given name is treated like an identifier in an SQL command,

  617.        that is, it is downcased unless double-quoted.  For example, given

  618.        a query result generated from the SQL command:

  619. </p><pre class="programlisting">

  620. SELECT 1 AS FOO, 2 AS "BAR";

  621. </pre><p>

  622.        we would have the results:

  623. </p><pre class="programlisting">

  624. PQfname(res, 0)              <em class="lineannotation"><span class="lineannotation">foo</span></em>

  625. PQfname(res, 1)              <em class="lineannotation"><span class="lineannotation">BAR</span></em>

  626. PQfnumber(res, "FOO")        <em class="lineannotation"><span class="lineannotation">0</span></em>

  627. PQfnumber(res, "foo")        <em class="lineannotation"><span class="lineannotation">0</span></em>

  628. PQfnumber(res, "BAR")        <em class="lineannotation"><span class="lineannotation">-1</span></em>

  629. PQfnumber(res, "\"BAR\"")    <em class="lineannotation"><span class="lineannotation">1</span></em>

  630. </pre><p>

  631.       </p></dd><dt id="LIBPQ-PQFTABLE"><span class="term">

  632.       <code class="function">PQftable</code>

  633.       <a id="id-1.7.3.10.4.3.5.1.2" class="indexterm"></a>

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

  635.        Returns the OID of the table from which the given column was

  636.        fetched.  Column numbers start at 0.

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

  638. Oid PQftable(const PGresult *res,

  639.              int column_number);

  640. </pre><p>

  641.       </p><p>

  642.        <code class="literal">InvalidOid</code> is returned if the column number is out of range,

  643.        or if the specified column is not a simple reference to a table column,

  644.        or when using pre-3.0 protocol.

  645.        You can query the system table <code class="literal">pg_class</code> to determine

  646.        exactly which table is referenced.

  647.       </p><p>

  648.        The type <code class="type">Oid</code> and the constant

  649.        <code class="literal">InvalidOid</code> will be defined when you include

  650.        the <span class="application">libpq</span> header file. They will both

  651.        be some integer type.

  652.       </p></dd><dt id="LIBPQ-PQFTABLECOL"><span class="term">

  653.       <code class="function">PQftablecol</code>

  654.       <a id="id-1.7.3.10.4.3.6.1.2" class="indexterm"></a>

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

  656.        Returns the column number (within its table) of the column making

  657.        up the specified query result column.  Query-result column numbers

  658.        start at 0, but table columns have nonzero numbers.

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

  660. int PQftablecol(const PGresult *res,

  661.                 int column_number);

  662. </pre><p>

  663.       </p><p>

  664.        Zero is returned if the column number is out of range, or if the

  665.        specified column is not a simple reference to a table column, or

  666.        when using pre-3.0 protocol.

  667.       </p></dd><dt id="LIBPQ-PQFFORMAT"><span class="term">

  668.       <code class="function">PQfformat</code>

  669.       <a id="id-1.7.3.10.4.3.7.1.2" class="indexterm"></a>

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

  671.        Returns the format code indicating the format of the given

  672.        column.  Column numbers start at 0.

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

  674. int PQfformat(const PGresult *res,

  675.               int column_number);

  676. </pre><p>

  677.       </p><p>

  678.        Format code zero indicates textual data representation, while format

  679.        code one indicates binary representation.  (Other codes are reserved

  680.        for future definition.)

  681.       </p></dd><dt id="LIBPQ-PQFTYPE"><span class="term">

  682.       <code class="function">PQftype</code>

  683.       <a id="id-1.7.3.10.4.3.8.1.2" class="indexterm"></a>

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

  685.        Returns the data type associated with the given  column number.

  686.        The  integer  returned is the internal OID number of the type.

  687.        Column numbers start at 0.

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

  689. Oid PQftype(const PGresult *res,

  690.             int column_number);

  691. </pre><p>

  692.       </p><p>

  693.        You can query the system table <code class="literal">pg_type</code> to

  694.        obtain the names and properties of the various data types. The

  695.        <acronym class="acronym">OID</acronym>s of the built-in data types are defined

  696.        in the file <code class="filename">src/include/catalog/pg_type_d.h</code>

  697.        in the source tree.

  698.       </p></dd><dt id="LIBPQ-PQFMOD"><span class="term">

  699.       <code class="function">PQfmod</code>

  700.       <a id="id-1.7.3.10.4.3.9.1.2" class="indexterm"></a>

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

  702.        Returns  the type modifier of the column associated with the

  703.        given column number.  Column numbers start at 0.

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

  705. int PQfmod(const PGresult *res,

  706.            int column_number);

  707. </pre><p>

  708.       </p><p>

  709.        The interpretation of modifier values is type-specific; they

  710.        typically indicate precision or size limits.  The value -1 is

  711.        used to indicate <span class="quote">“<span class="quote">no information available</span>”</span>.  Most data

  712.        types do not use modifiers, in which case the value is always

  713.        -1.

  714.       </p></dd><dt id="LIBPQ-PQFSIZE"><span class="term">

  715.       <code class="function">PQfsize</code>

  716.       <a id="id-1.7.3.10.4.3.10.1.2" class="indexterm"></a>

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

  718.        Returns  the  size  in bytes of the column associated with the

  719.        given column number.  Column numbers start at 0.

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

  721. int PQfsize(const PGresult *res,

  722.             int column_number);

  723. </pre><p>

  724.       </p><p>

  725.        <code class="function">PQfsize</code> returns the space allocated for this column

  726.        in a database row, in other words the size of the server's

  727.        internal representation of the data type.  (Accordingly, it is

  728.        not really very useful to clients.) A negative value indicates

  729.        the data type is variable-length.

  730.       </p></dd><dt id="LIBPQ-PQBINARYTUPLES"><span class="term">

  731.       <code class="function">PQbinaryTuples</code>

  732.       <a id="id-1.7.3.10.4.3.11.1.2" class="indexterm"></a>

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

  734.        Returns 1 if the <code class="structname">PGresult</code> contains binary data

  735.        and 0 if it contains text data.

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

  737. int PQbinaryTuples(const PGresult *res);

  738. </pre><p>

  739.       </p><p>

  740.        This function is deprecated (except for its use in connection with

  741.        <code class="command">COPY</code>), because it is possible for a single

  742.        <code class="structname">PGresult</code> to contain text data in some columns and

  743.        binary data in others.  <code class="function">PQfformat</code> is preferred.

  744.        <code class="function">PQbinaryTuples</code> returns 1 only if all columns of the

  745.        result are binary (format 1).

  746.       </p></dd><dt id="LIBPQ-PQGETVALUE"><span class="term">

  747.       <code class="function">PQgetvalue</code>

  748.        <a id="id-1.7.3.10.4.3.12.1.2" class="indexterm"></a>

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

  750.        Returns a single field value of one row of a

  751.        <code class="structname">PGresult</code>.  Row and column numbers start

  752.        at 0.  The caller should not free the result directly.  It will

  753.        be freed when the associated <code class="structname">PGresult</code> handle is

  754.        passed to <code class="function">PQclear</code>.

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

  756. char *PQgetvalue(const PGresult *res,

  757.                  int row_number,

  758.                  int column_number);

  759. </pre><p>

  760.       </p><p>

  761.        For data in text format, the value returned by

  762.        <code class="function">PQgetvalue</code> is a null-terminated character

  763.        string  representation of the field value.  For data in binary

  764.        format, the value is in the binary representation determined by

  765.        the data type's <code class="function">typsend</code> and <code class="function">typreceive</code>

  766.        functions.  (The value is actually followed by a zero byte in

  767.        this case too, but that is not ordinarily useful, since the

  768.        value is likely to contain embedded nulls.)

  769.       </p><p>

  770.        An empty string is returned if the field value is null.  See

  771.        <code class="function">PQgetisnull</code> to distinguish null values from

  772.        empty-string values.

  773.       </p><p>

  774.        The pointer returned  by  <code class="function">PQgetvalue</code> points

  775.        to storage that is part of the <code class="structname">PGresult</code>

  776.        structure.  One should not modify the data it points to, and one

  777.        must explicitly copy the data into other storage if it is to be

  778.        used past the lifetime of the  <code class="structname">PGresult</code>

  779.        structure itself.

  780.       </p></dd><dt id="LIBPQ-PQGETISNULL"><span class="term">

  781.       <code class="function">PQgetisnull</code>

  782.       <a id="id-1.7.3.10.4.3.13.1.2" class="indexterm"></a>

  783.       <a id="id-1.7.3.10.4.3.13.1.3" class="indexterm"></a>

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

  785.        Tests a field for a null value.  Row and column numbers start

  786.        at 0.

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

  788. int PQgetisnull(const PGresult *res,

  789.                 int row_number,

  790.                 int column_number);

  791. </pre><p>

  792.       </p><p>

  793.        This function returns  1 if the field is null and 0 if it

  794.        contains a non-null value.  (Note that

  795.        <code class="function">PQgetvalue</code> will return an empty string,

  796.        not a null pointer, for a null field.)

  797.       </p></dd><dt id="LIBPQ-PQGETLENGTH"><span class="term">

  798.      <code class="function">PQgetlength</code>

  799.      <a id="id-1.7.3.10.4.3.14.1.2" class="indexterm"></a></span></dt><dd><p>

  800.        Returns the actual length of a field value in bytes.  Row and

  801.        column numbers start at 0.

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

  803. int PQgetlength(const PGresult *res,

  804.                 int row_number,

  805.                 int column_number);

  806. </pre><p>

  807.       </p><p>

  808.        This is the actual data length for the particular data value,

  809.        that is, the size of the object pointed to by

  810.        <code class="function">PQgetvalue</code>.  For text data format this is

  811.        the same as <code class="function">strlen()</code>.  For binary format this is

  812.        essential information.  Note that one should <span class="emphasis"><em>not</em></span>

  813.        rely on <code class="function">PQfsize</code> to obtain the actual data

  814.        length.

  815.       </p></dd><dt id="LIBPQ-PQNPARAMS"><span class="term">

  816.       <code class="function">PQnparams</code>

  817.       <a id="id-1.7.3.10.4.3.15.1.2" class="indexterm"></a>

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

  819.        Returns the number of parameters of a prepared statement.

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

  821. int PQnparams(const PGresult *res);

  822. </pre><p>

  823.       </p><p>

  824.        This function is only useful when inspecting the result of

  825.        <code class="function">PQdescribePrepared</code>.  For other types of queries it

  826.        will return zero.

  827.       </p></dd><dt id="LIBPQ-PQPARAMTYPE"><span class="term">

  828.       <code class="function">PQparamtype</code>

  829.       <a id="id-1.7.3.10.4.3.16.1.2" class="indexterm"></a>

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

  831.        Returns the data type of the indicated statement parameter.

  832.        Parameter numbers start at 0.

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

  834. Oid PQparamtype(const PGresult *res, int param_number);

  835. </pre><p>

  836.       </p><p>

  837.        This function is only useful when inspecting the result of

  838.        <code class="function">PQdescribePrepared</code>.  For other types of queries it

  839.        will return zero.

  840.       </p></dd><dt id="LIBPQ-PQPRINT"><span class="term">

  841.       <code class="function">PQprint</code>

  842.       <a id="id-1.7.3.10.4.3.17.1.2" class="indexterm"></a>

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

  844.        Prints out all the rows and,  optionally,  the column names  to

  845.        the specified output stream.

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

  847. void PQprint(FILE *fout,      /* output stream */

  848.              const PGresult *res,

  849.              const PQprintOpt *po);

  850. typedef struct

  851. {

  852.     pqbool  header;      /* print output field headings and row count */

  853.     pqbool  align;       /* fill align the fields */

  854.     pqbool  standard;    /* old brain dead format */

  855.     pqbool  html3;       /* output HTML tables */

  856.     pqbool  expanded;    /* expand tables */

  857.     pqbool  pager;       /* use pager for output if needed */

  858.     char    *fieldSep;   /* field separator */

  859.     char    *tableOpt;   /* attributes for HTML table element */

  860.     char    *caption;    /* HTML table caption */

  861.     char    **fieldName; /* null-terminated array of replacement field names */

  862. } PQprintOpt;

  863. </pre><p>

  864.       </p><p>

  865.        This function was formerly used by <span class="application">psql</span>

  866.        to print query results, but this is no longer the case.  Note

  867.        that it assumes all the data is in text format.

  868.       </p></dd></dl></div></div><div class="sect2" id="LIBPQ-EXEC-NONSELECT"><div class="titlepage"><div><div><h3 class="title">33.3.3. Retrieving Other Result Information</h3></div></div></div><p>

  869.     These functions are used to extract other information from

  870.     <code class="structname">PGresult</code> objects.

  871.    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCMDSTATUS"><span class="term">

  872.       <code class="function">PQcmdStatus</code>

  873.       <a id="id-1.7.3.10.5.3.1.1.2" class="indexterm"></a>

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

  875.        Returns the command status tag from the SQL command that generated

  876.        the <code class="structname">PGresult</code>.

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

  878. char *PQcmdStatus(PGresult *res);

  879. </pre><p>

  880.       </p><p>

  881.        Commonly this is just the name of the command, but it might include

  882.        additional data such as the number of rows processed. The caller

  883.        should not free the result directly. It will be freed when the

  884.        associated <code class="structname">PGresult</code> handle is passed to

  885.        <code class="function">PQclear</code>.

  886.       </p></dd><dt id="LIBPQ-PQCMDTUPLES"><span class="term">

  887.       <code class="function">PQcmdTuples</code>

  888.       <a id="id-1.7.3.10.5.3.2.1.2" class="indexterm"></a>

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

  890.        Returns the number of rows affected by the SQL command.

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

  892. char *PQcmdTuples(PGresult *res);

  893. </pre><p>

  894.       </p><p>

  895.        This function returns a string containing the number of rows

  896.        affected by the <acronym class="acronym">SQL</acronym> statement that generated the

  897.        <code class="structname">PGresult</code>. This function can only be used following

  898.        the execution of a <code class="command">SELECT</code>, <code class="command">CREATE TABLE AS</code>,

  899.        <code class="command">INSERT</code>, <code class="command">UPDATE</code>, <code class="command">DELETE</code>,

  900.        <code class="command">MOVE</code>, <code class="command">FETCH</code>, or <code class="command">COPY</code> statement,

  901.        or an <code class="command">EXECUTE</code> of a prepared query that contains an

  902.        <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or <code class="command">DELETE</code> statement.

  903.        If the command that generated the <code class="structname">PGresult</code> was anything

  904.        else, <code class="function">PQcmdTuples</code> returns an empty string. The caller

  905.        should not free the return value directly. It will be freed when

  906.        the associated <code class="structname">PGresult</code> handle is passed to

  907.        <code class="function">PQclear</code>.

  908.       </p></dd><dt id="LIBPQ-PQOIDVALUE"><span class="term">

  909.       <code class="function">PQoidValue</code>

  910.       <a id="id-1.7.3.10.5.3.3.1.2" class="indexterm"></a>

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

  912.        Returns the OID<a id="id-1.7.3.10.5.3.3.2.1.1" class="indexterm"></a>

  913.        of the inserted row, if the <acronym class="acronym">SQL</acronym> command was an

  914.        <code class="command">INSERT</code> that inserted exactly one row into a table that

  915.        has OIDs, or a <code class="command">EXECUTE</code> of a prepared query containing

  916.        a suitable <code class="command">INSERT</code> statement.  Otherwise, this function

  917.        returns <code class="literal">InvalidOid</code>. This function will also

  918.        return <code class="literal">InvalidOid</code> if the table affected by the

  919.        <code class="command">INSERT</code> statement does not contain OIDs.

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

  921. Oid PQoidValue(const PGresult *res);

  922. </pre><p>

  923.       </p></dd><dt id="LIBPQ-PQOIDSTATUS"><span class="term">

  924.       <code class="function">PQoidStatus</code>

  925.       <a id="id-1.7.3.10.5.3.4.1.2" class="indexterm"></a>

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

  927.        This function is deprecated in favor of

  928.        <code class="function">PQoidValue</code> and is not thread-safe.

  929.        It returns a string with the OID of the inserted row, while

  930.        <code class="function">PQoidValue</code> returns the OID value.

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

  932. char *PQoidStatus(const PGresult *res);

  933. </pre><p>

  934.       </p></dd></dl></div></div><div class="sect2" id="LIBPQ-EXEC-ESCAPE-STRING"><div class="titlepage"><div><div><h3 class="title">33.3.4. Escaping Strings for Inclusion in SQL Commands</h3></div></div></div><a id="id-1.7.3.10.6.2" class="indexterm"></a><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQESCAPELITERAL"><span class="term">

  935.       <code class="function">PQescapeLiteral</code>

  936.       <a id="id-1.7.3.10.6.3.1.1.2" class="indexterm"></a>

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

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

  939. char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);

  940. </pre><p>

  941.      </p><p>

  942.       <code class="function">PQescapeLiteral</code> escapes a string for

  943.       use within an SQL command.  This is useful when inserting data

  944.       values as literal constants in SQL commands.  Certain characters

  945.       (such as quotes and backslashes) must be escaped to prevent them

  946.       from being interpreted specially by the SQL parser.

  947.       <code class="function">PQescapeLiteral</code> performs this operation.

  948.      </p><p>

  949.       <code class="function">PQescapeLiteral</code> returns an escaped version of the

  950.       <em class="parameter"><code>str</code></em> parameter in memory allocated with

  951.       <code class="function">malloc()</code>.  This memory should be freed using

  952.       <code class="function">PQfreemem()</code> when the result is no longer needed.

  953.       A terminating zero byte is not required, and should not be

  954.       counted in <em class="parameter"><code>length</code></em>.  (If a terminating zero byte is found

  955.       before <em class="parameter"><code>length</code></em> bytes are processed,

  956.       <code class="function">PQescapeLiteral</code> stops at the zero; the behavior is

  957.       thus rather like <code class="function">strncpy</code>.) The

  958.       return string has all special characters replaced so that they can

  959.       be properly processed by the <span class="productname">PostgreSQL</span>

  960.       string literal parser.  A terminating zero byte is also added.  The

  961.       single quotes that must surround <span class="productname">PostgreSQL</span>

  962.       string literals are included in the result string.

  963.      </p><p>

  964.       On error, <code class="function">PQescapeLiteral</code> returns <code class="symbol">NULL</code> and a suitable

  965.       message is stored in the <em class="parameter"><code>conn</code></em> object.

  966.      </p><div class="tip"><h3 class="title">Tip</h3><p>

  967.        It is especially important to do proper escaping when handling

  968.        strings that were received from an untrustworthy source.

  969.        Otherwise there is a security risk: you are vulnerable to

  970.        <span class="quote">“<span class="quote">SQL injection</span>”</span> attacks wherein unwanted SQL commands are

  971.        fed to your database.

  972.       </p></div><p>

  973.       Note that it is neither necessary nor correct to do escaping when a data

  974.       value is passed as a separate parameter in <code class="function">PQexecParams</code> or

  975.       its sibling routines.

  976.      </p></dd><dt id="LIBPQ-PQESCAPEIDENTIFIER"><span class="term">

  977.       <code class="function">PQescapeIdentifier</code>

  978.       <a id="id-1.7.3.10.6.3.2.1.2" class="indexterm"></a>

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

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

  981. char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);

  982. </pre><p>

  983.      </p><p>

  984.       <code class="function">PQescapeIdentifier</code> escapes a string for

  985.       use as an SQL identifier, such as a table, column, or function name.

  986.       This is useful when a user-supplied identifier might contain

  987.       special characters that would otherwise not be interpreted as part

  988.       of the identifier by the SQL parser, or when the identifier might

  989.       contain upper case characters whose case should be preserved.

  990.      </p><p>

  991.       <code class="function">PQescapeIdentifier</code> returns a version of the

  992.       <em class="parameter"><code>str</code></em> parameter escaped as an SQL identifier

  993.       in memory allocated with <code class="function">malloc()</code>.  This memory must be

  994.       freed using <code class="function">PQfreemem()</code> when the result is no longer

  995.       needed.  A terminating zero byte is not required, and should not be

  996.       counted in <em class="parameter"><code>length</code></em>.  (If a terminating zero byte is found

  997.       before <em class="parameter"><code>length</code></em> bytes are processed,

  998.       <code class="function">PQescapeIdentifier</code> stops at the zero; the behavior is

  999.       thus rather like <code class="function">strncpy</code>.) The

  1000.       return string has all special characters replaced so that it

  1001.       will be properly processed as an SQL identifier.  A terminating zero byte

  1002.       is also added.  The return string will also be surrounded by double

  1003.       quotes.

  1004.      </p><p>

  1005.       On error, <code class="function">PQescapeIdentifier</code> returns <code class="symbol">NULL</code> and a suitable

  1006.       message is stored in the <em class="parameter"><code>conn</code></em> object.

  1007.      </p><div class="tip"><h3 class="title">Tip</h3><p>

  1008.        As with string literals, to prevent SQL injection attacks,

  1009.        SQL identifiers must be escaped when they are received from an

  1010.        untrustworthy source.

  1011.       </p></div></dd><dt id="LIBPQ-PQESCAPESTRINGCONN"><span class="term">

  1012.       <code class="function">PQescapeStringConn</code>

  1013.       <a id="id-1.7.3.10.6.3.3.1.2" class="indexterm"></a>

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

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

  1016. size_t PQescapeStringConn(PGconn *conn,

  1017.                           char *to, const char *from, size_t length,

  1018.                           int *error);

  1019. </pre><p>

  1020.      </p><p>

  1021.       <code class="function">PQescapeStringConn</code> escapes string literals, much like

  1022.       <code class="function">PQescapeLiteral</code>.  Unlike <code class="function">PQescapeLiteral</code>,

  1023.       the caller is responsible for providing an appropriately sized buffer.

  1024.       Furthermore, <code class="function">PQescapeStringConn</code> does not generate the

  1025.       single quotes that must surround <span class="productname">PostgreSQL</span> string

  1026.       literals; they should be provided in the SQL command that the

  1027.       result is inserted into.  The parameter <em class="parameter"><code>from</code></em> points to

  1028.       the first character of the string that is to be escaped, and the

  1029.       <em class="parameter"><code>length</code></em> parameter gives the number of bytes in this

  1030.       string.  A terminating zero byte is not required, and should not be

  1031.       counted in <em class="parameter"><code>length</code></em>.  (If a terminating zero byte is found

  1032.       before <em class="parameter"><code>length</code></em> bytes are processed,

  1033.       <code class="function">PQescapeStringConn</code> stops at the zero; the behavior is

  1034.       thus rather like <code class="function">strncpy</code>.) <em class="parameter"><code>to</code></em> shall point

  1035.       to a buffer that is able to hold at least one more byte than twice

  1036.       the value of <em class="parameter"><code>length</code></em>, otherwise the behavior is undefined.

  1037.       Behavior is likewise undefined if the <em class="parameter"><code>to</code></em> and

  1038.       <em class="parameter"><code>from</code></em> strings overlap.

  1039.      </p><p>

  1040.       If the <em class="parameter"><code>error</code></em> parameter is not <code class="symbol">NULL</code>, then

  1041.       <code class="literal">*error</code> is set to zero on success, nonzero on error.

  1042.       Presently the only possible error conditions involve invalid multibyte

  1043.       encoding in the source string.  The output string is still generated

  1044.       on error, but it can be expected that the server will reject it as

  1045.       malformed.  On error, a suitable message is stored in the

  1046.       <em class="parameter"><code>conn</code></em> object, whether or not <em class="parameter"><code>error</code></em> is <code class="symbol">NULL</code>.

  1047.      </p><p>

  1048.       <code class="function">PQescapeStringConn</code> returns the number of bytes written

  1049.       to <em class="parameter"><code>to</code></em>, not including the terminating zero byte.

  1050.      </p></dd><dt id="LIBPQ-PQESCAPESTRING"><span class="term">

  1051.       <code class="function">PQescapeString</code>

  1052.       <a id="id-1.7.3.10.6.3.4.1.2" class="indexterm"></a>

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

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

  1055.        <code class="function">PQescapeStringConn</code>.

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

  1057. size_t PQescapeString (char *to, const char *from, size_t length);

  1058. </pre><p>

  1059.      </p><p>

  1060.       The only difference from <code class="function">PQescapeStringConn</code> is that

  1061.       <code class="function">PQescapeString</code> does not take <code class="structname">PGconn</code>

  1062.       or <em class="parameter"><code>error</code></em> parameters.

  1063.       Because of this, it cannot adjust its behavior depending on the

  1064.       connection properties (such as character encoding) and therefore

  1065.       <span class="emphasis"><em>it might give the wrong results</em></span>.  Also, it has no way

  1066.       to report error conditions.

  1067.      </p><p>

  1068.       <code class="function">PQescapeString</code> can be used safely in

  1069.       client programs that work with only one <span class="productname">PostgreSQL</span>

  1070.       connection at a time (in this case it can find out what it needs to

  1071.       know <span class="quote">“<span class="quote">behind the scenes</span>”</span>).  In other contexts it is a security

  1072.       hazard and should be avoided in favor of

  1073.       <code class="function">PQescapeStringConn</code>.

  1074.      </p></dd><dt id="LIBPQ-PQESCAPEBYTEACONN"><span class="term">

  1075.       <code class="function">PQescapeByteaConn</code>

  1076.       <a id="id-1.7.3.10.6.3.5.1.2" class="indexterm"></a>

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

  1078.        Escapes binary data for use within an SQL command with the type

  1079.        <code class="type">bytea</code>.  As with <code class="function">PQescapeStringConn</code>,

  1080.        this is only used when inserting data directly into an SQL command string.

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

  1082. unsigned char *PQescapeByteaConn(PGconn *conn,

  1083.                                  const unsigned char *from,

  1084.                                  size_t from_length,

  1085.                                  size_t *to_length);

  1086. </pre><p>

  1087.       </p><p>

  1088.        Certain byte values must be escaped when used as part of a

  1089.        <code class="type">bytea</code> literal in an <acronym class="acronym">SQL</acronym> statement.

  1090.        <code class="function">PQescapeByteaConn</code> escapes bytes using

  1091.        either hex encoding or backslash escaping.  See <a class="xref" href="datatype-binary.html" title="8.4. Binary Data Types">Section 8.4</a> for more information.

  1092.       </p><p>

  1093.        The <em class="parameter"><code>from</code></em> parameter points to the first

  1094.        byte of the string that is to be escaped, and the

  1095.        <em class="parameter"><code>from_length</code></em> parameter gives the number of

  1096.        bytes in this binary string.  (A terminating zero byte is

  1097.        neither necessary nor counted.)  The <em class="parameter"><code>to_length</code></em>

  1098.        parameter points to a variable that will hold the resultant

  1099.        escaped string length. This result string length includes the terminating

  1100.        zero byte of the result.

  1101.       </p><p>

  1102.        <code class="function">PQescapeByteaConn</code> returns an escaped version of the

  1103.        <em class="parameter"><code>from</code></em> parameter binary string in memory

  1104.        allocated with <code class="function">malloc()</code>.  This memory should be freed using

  1105.        <code class="function">PQfreemem()</code> when the result is no longer needed.  The

  1106.        return string has all special characters replaced so that they can

  1107.        be properly processed by the <span class="productname">PostgreSQL</span>

  1108.        string literal parser, and the <code class="type">bytea</code> input function. A

  1109.        terminating zero byte is also added.  The single quotes that must

  1110.        surround <span class="productname">PostgreSQL</span> string literals are

  1111.        not part of the result string.

  1112.       </p><p>

  1113.        On error, a null pointer is returned, and a suitable error message

  1114.        is stored in the <em class="parameter"><code>conn</code></em> object.  Currently, the only

  1115.        possible error is insufficient memory for the result string.

  1116.       </p></dd><dt id="LIBPQ-PQESCAPEBYTEA"><span class="term">

  1117.       <code class="function">PQescapeBytea</code>

  1118.       <a id="id-1.7.3.10.6.3.6.1.2" class="indexterm"></a>

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

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

  1121.        <code class="function">PQescapeByteaConn</code>.

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

  1123. unsigned char *PQescapeBytea(const unsigned char *from,

  1124.                              size_t from_length,

  1125.                              size_t *to_length);

  1126. </pre><p>

  1127.       </p><p>

  1128.        The only difference from <code class="function">PQescapeByteaConn</code> is that

  1129.        <code class="function">PQescapeBytea</code> does not take a <code class="structname">PGconn</code>

  1130.        parameter.  Because of this, <code class="function">PQescapeBytea</code> can

  1131.        only be used safely in client programs that use a single

  1132.        <span class="productname">PostgreSQL</span> connection at a time (in this case

  1133.        it can find out what it needs to know <span class="quote">“<span class="quote">behind the

  1134.        scenes</span>”</span>).  It <span class="emphasis"><em>might give the wrong results</em></span> if

  1135.        used in programs that use multiple database connections (use

  1136.        <code class="function">PQescapeByteaConn</code> in such cases).

  1137.       </p></dd><dt id="LIBPQ-PQUNESCAPEBYTEA"><span class="term">

  1138.       <code class="function">PQunescapeBytea</code>

  1139.       <a id="id-1.7.3.10.6.3.7.1.2" class="indexterm"></a>

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

  1141.        Converts a string representation of binary data into binary data

  1142.        — the reverse of <code class="function">PQescapeBytea</code>.  This

  1143.        is needed when retrieving <code class="type">bytea</code> data in text format,

  1144.        but not when retrieving it in binary format.

  1145. 

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

  1147. unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);

  1148. </pre><p>

  1149.       </p><p>

  1150.        The <em class="parameter"><code>from</code></em> parameter points to a string

  1151.        such as might be returned by <code class="function">PQgetvalue</code> when applied

  1152.        to a <code class="type">bytea</code> column. <code class="function">PQunescapeBytea</code>

  1153.        converts this string representation into its binary representation.

  1154.        It returns a pointer to a buffer allocated with

  1155.        <code class="function">malloc()</code>, or <code class="symbol">NULL</code> on error, and puts the size of

  1156.        the buffer in <em class="parameter"><code>to_length</code></em>. The result must be

  1157.        freed using <code class="function">PQfreemem</code> when it is no longer needed.

  1158.       </p><p>

  1159.        This conversion is not exactly the inverse of

  1160.        <code class="function">PQescapeBytea</code>, because the string is not expected

  1161.        to be <span class="quote">“<span class="quote">escaped</span>”</span> when received from <code class="function">PQgetvalue</code>.

  1162.        In particular this means there is no need for string quoting considerations,

  1163.        and so no need for a <code class="structname">PGconn</code> parameter.

  1164.       </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-status.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-async.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.2. Connection Status Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 33.4. Asynchronous Command Processing</td></tr></table></div></body></html>
上海开阖软件有限公司 沪ICP备12045867号-1