Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes15kdownloads
libpq-exec.html1053 linesDownload Raw Back to html
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.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 Vsnapshot" /><link rel="prev" href="libpq-status.html" title="34.2. Connection Status Functions" /><link rel="next" href="libpq-async.html" title="34.4. Asynchronous Command Processing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.3. Command Execution Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-status.html" title="34.2. Connection Status Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-async.html" title="34.4. Asynchronous Command Processing">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-EXEC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.3. Command Execution Functions <a href="#LIBPQ-EXEC" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-MAIN">34.3.1. Main Functions</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">34.3.2. Retrieving Query Result Information</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-NONSELECT">34.3.3. Retrieving Other Result Information</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">34.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 successfully4   established, the functions described here are used to perform5   SQL queries and commands.6  </p><div class="sect2" id="LIBPQ-EXEC-MAIN"><div class="titlepage"><div><div><h3 class="title">34.3.1. Main Functions <a href="#LIBPQ-EXEC-MAIN" class="id_link">#</a></h3></div></div></div><p>7    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQEXEC"><span class="term"><code class="function">PQexec</code><a id="id-1.7.3.10.3.2.1.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQEXEC" class="id_link">#</a></dt><dd><p>8        Submits a command to the server and waits for the result.9 10</p><pre class="synopsis">11PGresult *PQexec(PGconn *conn, const char *command);12</pre><p>13       </p><p>14        Returns a <code class="structname">PGresult</code> pointer or possibly a null15        pointer.  A non-null pointer will generally be returned except in16        out-of-memory conditions or serious errors such as inability to send17        the command to the server.  The <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> function18        should be called to check the return value for any errors (including19        the value of a null pointer, in which case it will return20        <code class="symbol">PGRES_FATAL_ERROR</code>).  Use21        <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to get more information about such22        errors.23       </p></dd></dl></div><p>24 25    The command string can include multiple SQL commands26    (separated by semicolons).  Multiple queries sent in a single27    <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> call are processed in a single transaction, unless28    there are explicit <code class="command">BEGIN</code>/<code class="command">COMMIT</code>29    commands included in the query string to divide it into multiple30    transactions.  (See <a class="xref" href="protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT" title="55.2.2.1. Multiple Statements in a Simple Query">Section 55.2.2.1</a>31    for more details about how the server handles multi-query strings.)32    Note however that the returned33    <code class="structname">PGresult</code> structure describes only the result34    of the last command executed from the string.  Should one of the35    commands fail, processing of the string stops with it and the returned36    <code class="structname">PGresult</code> describes the error condition.37   </p><p>38    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQEXECPARAMS"><span class="term"><code class="function">PQexecParams</code><a id="id-1.7.3.10.3.3.1.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQEXECPARAMS" class="id_link">#</a></dt><dd><p>39        Submits a command to the server and waits for the result,40        with the ability to pass parameters separately from the SQL41        command text.42 43</p><pre class="synopsis">44PGresult *PQexecParams(PGconn *conn,45                       const char *command,46                       int nParams,47                       const Oid *paramTypes,48                       const char * const *paramValues,49                       const int *paramLengths,50                       const int *paramFormats,51                       int resultFormat);52</pre><p>53       </p><p>54        <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a> is like <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>, but offers additional55        functionality: parameter values can be specified separately from the command56        string proper, and query results can be requested in either text or binary57        format.58       </p><p>59        The function arguments are:60 61        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>conn</code></em></span></dt><dd><p>62            The connection object to send the command through.63           </p></dd><dt><span class="term"><em class="parameter"><code>command</code></em></span></dt><dd><p>64            The SQL command string to be executed. If parameters are used,65            they are referred to in the command string as <code class="literal">$1</code>,66            <code class="literal">$2</code>, etc.67           </p></dd><dt><span class="term"><em class="parameter"><code>nParams</code></em></span></dt><dd><p>68            The number of parameters supplied; it is the length of the arrays69            <em class="parameter"><code>paramTypes[]</code></em>, <em class="parameter"><code>paramValues[]</code></em>,70            <em class="parameter"><code>paramLengths[]</code></em>, and <em class="parameter"><code>paramFormats[]</code></em>. (The71            array pointers can be <code class="symbol">NULL</code> when <em class="parameter"><code>nParams</code></em>72            is zero.)73           </p></dd><dt><span class="term"><em class="parameter"><code>paramTypes[]</code></em></span></dt><dd><p>74            Specifies, by OID, the data types to be assigned to the75            parameter symbols.  If <em class="parameter"><code>paramTypes</code></em> is76            <code class="symbol">NULL</code>, or any particular element in the array77            is zero, the server infers a data type for the parameter symbol78            in the same way it would do for an untyped literal string.79           </p></dd><dt><span class="term"><em class="parameter"><code>paramValues[]</code></em></span></dt><dd><p>80            Specifies the actual values of the parameters.  A null pointer81            in this array means the corresponding parameter is null;82            otherwise the pointer points to a zero-terminated text string83            (for text format) or binary data in the format expected by the84            server (for binary format).85           </p></dd><dt><span class="term"><em class="parameter"><code>paramLengths[]</code></em></span></dt><dd><p>86            Specifies the actual data lengths of binary-format parameters.87            It is ignored for null parameters and text-format parameters.88            The array pointer can be null when there are no binary parameters.89           </p></dd><dt><span class="term"><em class="parameter"><code>paramFormats[]</code></em></span></dt><dd><p>90            Specifies whether parameters are text (put a zero in the91            array entry for the corresponding parameter) or binary (put92            a one in the array entry for the corresponding parameter).93            If the array pointer is null then all parameters are presumed94            to be text strings.95           </p><p>96            Values passed in binary format require knowledge of97            the internal representation expected by the backend.98            For example, integers must be passed in network byte99            order.  Passing <code class="type">numeric</code> values requires100            knowledge of the server storage format, as implemented101            in102            <code class="filename">src/backend/utils/adt/numeric.c::numeric_send()</code> and103            <code class="filename">src/backend/utils/adt/numeric.c::numeric_recv()</code>.104           </p></dd><dt><span class="term"><em class="parameter"><code>resultFormat</code></em></span></dt><dd><p>105            Specify zero to obtain results in text format, or one to obtain106            results in binary format.  (There is not currently a provision107            to obtain different result columns in different formats,108            although that is possible in the underlying protocol.)109           </p></dd></dl></div><p>110       </p></dd></dl></div><p>111   </p><p>112    The primary advantage of <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a> over113    <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> is that parameter values can be separated from the114    command string, thus avoiding the need for tedious and error-prone115    quoting and escaping.116   </p><p>117    Unlike <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>, <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a> allows at most118    one SQL command in the given string.  (There can be semicolons in it,119    but not more than one nonempty command.)  This is a limitation of the120    underlying protocol, but has some usefulness as an extra defense against121    SQL-injection attacks.122   </p><div class="tip"><h3 class="title">Tip</h3><p>123     Specifying parameter types via OIDs is tedious, particularly if you prefer124     not to hard-wire particular OID values into your program.  However, you can125     avoid doing so even in cases where the server by itself cannot determine the126     type of the parameter, or chooses a different type than you want.  In the127     SQL command text, attach an explicit cast to the parameter symbol to show what128     data type you will send.  For example:129</p><pre class="programlisting">130SELECT * FROM mytable WHERE x = $1::bigint;131</pre><p>132     This forces parameter <code class="literal">$1</code> to be treated as <code class="type">bigint</code>, whereas133     by default it would be assigned the same type as <code class="literal">x</code>.  Forcing the134     parameter type decision, either this way or by specifying a numeric type OID,135     is strongly recommended when sending parameter values in binary format, because136     binary format has less redundancy than text format and so there is less chance137     that the server will detect a type mismatch mistake for you.138    </p></div><p>139    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPREPARE"><span class="term"><code class="function">PQprepare</code><a id="id-1.7.3.10.3.7.1.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPREPARE" class="id_link">#</a></dt><dd><p>140        Submits a request to create a prepared statement with the141        given parameters, and waits for completion.142</p><pre class="synopsis">143PGresult *PQprepare(PGconn *conn,144                    const char *stmtName,145                    const char *query,146                    int nParams,147                    const Oid *paramTypes);148</pre><p>149       </p><p>150        <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a> creates a prepared statement for later151        execution with <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>.  This feature allows152        commands to be executed repeatedly without being parsed and153        planned each time;  see <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a> for details.154       </p><p>155        The function creates a prepared statement named156        <em class="parameter"><code>stmtName</code></em> from the <em class="parameter"><code>query</code></em> string, which157        must contain a single SQL command.  <em class="parameter"><code>stmtName</code></em> can be158        <code class="literal">""</code> to create an unnamed statement, in which case any159        pre-existing unnamed statement is automatically replaced; otherwise160        it is an error if the statement name is already defined in the161        current session.  If any parameters are used, they are referred162        to in the query as <code class="literal">$1</code>, <code class="literal">$2</code>, etc.163        <em class="parameter"><code>nParams</code></em> is the number of parameters for which types164        are pre-specified in the array <em class="parameter"><code>paramTypes[]</code></em>.  (The165        array pointer can be <code class="symbol">NULL</code> when166        <em class="parameter"><code>nParams</code></em> is zero.) <em class="parameter"><code>paramTypes[]</code></em>167        specifies, by OID, the data types to be assigned to the parameter168        symbols.  If <em class="parameter"><code>paramTypes</code></em> is <code class="symbol">NULL</code>,169        or any particular element in the array is zero, the server assigns170        a data type to the parameter symbol in the same way it would do171        for an untyped literal string.  Also, the query can use parameter172        symbols with numbers higher than <em class="parameter"><code>nParams</code></em>; data types173        will be inferred for these symbols as well.  (See174        <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a> for a means to find out175        what data types were inferred.)176       </p><p>177        As with <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>, the result is normally a178        <code class="structname">PGresult</code> object whose contents indicate179        server-side success or failure.  A null result indicates180        out-of-memory or inability to send the command at all.  Use181        <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to get more information about182        such errors.183       </p></dd></dl></div><p>184 185    Prepared statements for use with <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a> can also186    be created by executing SQL <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a>187    statements.  Also, although there is no <span class="application">libpq</span>188    function for deleting a prepared statement, the SQL <a class="xref" href="sql-deallocate.html" title="DEALLOCATE"><span class="refentrytitle">DEALLOCATE</span></a> statement189    can be used for that purpose.190   </p><p>191    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQEXECPREPARED"><span class="term"><code class="function">PQexecPrepared</code><a id="id-1.7.3.10.3.8.1.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQEXECPREPARED" class="id_link">#</a></dt><dd><p>192        Sends a request to execute a prepared statement with given193        parameters, and waits for the result.194</p><pre class="synopsis">195PGresult *PQexecPrepared(PGconn *conn,196                         const char *stmtName,197                         int nParams,198                         const char * const *paramValues,199                         const int *paramLengths,200                         const int *paramFormats,201                         int resultFormat);202</pre><p>203       </p><p>204        <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a> is like <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>,205        but the command to be executed is specified by naming a206        previously-prepared statement, instead of giving a query string.207        This feature allows commands that will be used repeatedly to be208        parsed and planned just once, rather than each time they are209        executed.  The statement must have been prepared previously in210        the current session.211       </p><p>212        The parameters are identical to <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>, except that the213        name of a prepared statement is given instead of a query string, and the214        <em class="parameter"><code>paramTypes[]</code></em> parameter is not present (it is not needed since215        the prepared statement's parameter types were determined when it was created).216       </p></dd><dt id="LIBPQ-PQDESCRIBEPREPARED"><span class="term"><code class="function">PQdescribePrepared</code><a id="id-1.7.3.10.3.8.1.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQDESCRIBEPREPARED" class="id_link">#</a></dt><dd><p>217        Submits a request to obtain information about the specified218        prepared statement, and waits for completion.219</p><pre class="synopsis">220PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);221</pre><p>222       </p><p>223        <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a> allows an application to obtain224        information about a previously prepared statement.225       </p><p>226        <em class="parameter"><code>stmtName</code></em> can be <code class="literal">""</code> or <code class="symbol">NULL</code> to reference227        the unnamed statement, otherwise it must be the name of an existing228        prepared statement.  On success, a <code class="structname">PGresult</code> with229        status <code class="literal">PGRES_COMMAND_OK</code> is returned.  The230        functions <a class="xref" href="libpq-exec.html#LIBPQ-PQNPARAMS"><code class="function">PQnparams</code></a> and231        <a class="xref" href="libpq-exec.html#LIBPQ-PQPARAMTYPE"><code class="function">PQparamtype</code></a> can be applied to this232        <code class="structname">PGresult</code> to obtain information about the parameters233        of the prepared statement, and the functions234        <a class="xref" href="libpq-exec.html#LIBPQ-PQNFIELDS"><code class="function">PQnfields</code></a>, <a class="xref" href="libpq-exec.html#LIBPQ-PQFNAME"><code class="function">PQfname</code></a>,235        <a class="xref" href="libpq-exec.html#LIBPQ-PQFTYPE"><code class="function">PQftype</code></a>, etc. provide information about the236        result columns (if any) of the statement.237       </p></dd><dt id="LIBPQ-PQDESCRIBEPORTAL"><span class="term"><code class="function">PQdescribePortal</code><a id="id-1.7.3.10.3.8.1.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQDESCRIBEPORTAL" class="id_link">#</a></dt><dd><p>238        Submits a request to obtain information about the specified239        portal, and waits for completion.240</p><pre class="synopsis">241PGresult *PQdescribePortal(PGconn *conn, const char *portalName);242</pre><p>243       </p><p>244        <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a> allows an application to obtain245        information about a previously created portal.246        (<span class="application">libpq</span> does not provide any direct access to247        portals, but you can use this function to inspect the properties248        of a cursor created with a <code class="command">DECLARE CURSOR</code> SQL command.)249       </p><p>250        <em class="parameter"><code>portalName</code></em> can be <code class="literal">""</code> or <code class="symbol">NULL</code> to reference251        the unnamed portal, otherwise it must be the name of an existing252        portal.  On success, a <code class="structname">PGresult</code> with status253        <code class="literal">PGRES_COMMAND_OK</code> is returned.  The functions254        <a class="xref" href="libpq-exec.html#LIBPQ-PQNFIELDS"><code class="function">PQnfields</code></a>, <a class="xref" href="libpq-exec.html#LIBPQ-PQFNAME"><code class="function">PQfname</code></a>,255        <a class="xref" href="libpq-exec.html#LIBPQ-PQFTYPE"><code class="function">PQftype</code></a>, etc. can be applied to the256        <code class="structname">PGresult</code> to obtain information about the result257        columns (if any) of the portal.258       </p></dd></dl></div><p>259   </p><p>260    The <code class="structname">PGresult</code><a id="id-1.7.3.10.3.9.2" class="indexterm"></a>261    structure encapsulates the result returned by the server.262    <span class="application">libpq</span> application programmers should be263    careful to maintain the <code class="structname">PGresult</code> abstraction.264    Use the accessor functions below to get at the contents of265    <code class="structname">PGresult</code>.  Avoid directly referencing the266    fields of the <code class="structname">PGresult</code> structure because they267    are subject to change in the future.268 269    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQRESULTSTATUS"><span class="term"><code class="function">PQresultStatus</code><a id="id-1.7.3.10.3.9.7.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESULTSTATUS" class="id_link">#</a></dt><dd><p>270        Returns the result status of the command.271</p><pre class="synopsis">272ExecStatusType PQresultStatus(const PGresult *res);273</pre><p>274       </p><p>275        <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> can return one of the following values:276 277        </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PGRES-EMPTY-QUERY"><span class="term"><code class="literal">PGRES_EMPTY_QUERY</code></span> <a href="#LIBPQ-PGRES-EMPTY-QUERY" class="id_link">#</a></dt><dd><p>278            The string sent to the server was empty.279           </p></dd><dt id="LIBPQ-PGRES-COMMAND-OK"><span class="term"><code class="literal">PGRES_COMMAND_OK</code></span> <a href="#LIBPQ-PGRES-COMMAND-OK" class="id_link">#</a></dt><dd><p>280            Successful completion of a command returning no data.281           </p></dd><dt id="LIBPQ-PGRES-TUPLES-OK"><span class="term"><code class="literal">PGRES_TUPLES_OK</code></span> <a href="#LIBPQ-PGRES-TUPLES-OK" class="id_link">#</a></dt><dd><p>282            Successful completion of a command returning data (such as283            a <code class="command">SELECT</code> or <code class="command">SHOW</code>).284           </p></dd><dt id="LIBPQ-PGRES-COPY-OUT"><span class="term"><code class="literal">PGRES_COPY_OUT</code></span> <a href="#LIBPQ-PGRES-COPY-OUT" class="id_link">#</a></dt><dd><p>285            Copy Out (from server) data transfer started.286           </p></dd><dt id="LIBPQ-PGRES-COPY-IN"><span class="term"><code class="literal">PGRES_COPY_IN</code></span> <a href="#LIBPQ-PGRES-COPY-IN" class="id_link">#</a></dt><dd><p>287            Copy In (to server) data transfer started.288           </p></dd><dt id="LIBPQ-PGRES-BAD-RESPONSE"><span class="term"><code class="literal">PGRES_BAD_RESPONSE</code></span> <a href="#LIBPQ-PGRES-BAD-RESPONSE" class="id_link">#</a></dt><dd><p>289            The server's response was not understood.290           </p></dd><dt id="LIBPQ-PGRES-NONFATAL-ERROR"><span class="term"><code class="literal">PGRES_NONFATAL_ERROR</code></span> <a href="#LIBPQ-PGRES-NONFATAL-ERROR" class="id_link">#</a></dt><dd><p>291            A nonfatal error (a notice or warning) occurred.292           </p></dd><dt id="LIBPQ-PGRES-FATAL-ERROR"><span class="term"><code class="literal">PGRES_FATAL_ERROR</code></span> <a href="#LIBPQ-PGRES-FATAL-ERROR" class="id_link">#</a></dt><dd><p>293            A fatal error occurred.294           </p></dd><dt id="LIBPQ-PGRES-COPY-BOTH"><span class="term"><code class="literal">PGRES_COPY_BOTH</code></span> <a href="#LIBPQ-PGRES-COPY-BOTH" class="id_link">#</a></dt><dd><p>295            Copy In/Out (to and from server) data transfer started.  This296            feature is currently used only for streaming replication,297            so this status should not occur in ordinary applications.298           </p></dd><dt id="LIBPQ-PGRES-SINGLE-TUPLE"><span class="term"><code class="literal">PGRES_SINGLE_TUPLE</code></span> <a href="#LIBPQ-PGRES-SINGLE-TUPLE" class="id_link">#</a></dt><dd><p>299            The <code class="structname">PGresult</code> contains a single result tuple300            from the current command.  This status occurs only when301            single-row mode has been selected for the query302            (see <a class="xref" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Section 34.6</a>).303           </p></dd><dt id="LIBPQ-PGRES-PIPELINE-SYNC"><span class="term"><code class="literal">PGRES_PIPELINE_SYNC</code></span> <a href="#LIBPQ-PGRES-PIPELINE-SYNC" class="id_link">#</a></dt><dd><p>304            The <code class="structname">PGresult</code> represents a305            synchronization point in pipeline mode, requested by306            <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQPIPELINESYNC"><code class="function">PQpipelineSync</code></a>.307            This status occurs only when pipeline mode has been selected.308           </p></dd><dt id="LIBPQ-PGRES-PIPELINE-ABORTED"><span class="term"><code class="literal">PGRES_PIPELINE_ABORTED</code></span> <a href="#LIBPQ-PGRES-PIPELINE-ABORTED" class="id_link">#</a></dt><dd><p>309            The <code class="structname">PGresult</code> represents a pipeline that has310            received an error from the server.  <code class="function">PQgetResult</code>311            must be called repeatedly, and each time it will return this status code312            until the end of the current pipeline, at which point it will return313            <code class="literal">PGRES_PIPELINE_SYNC</code> and normal processing can314            resume.315           </p></dd></dl></div><p>316 317        If the result status is <code class="literal">PGRES_TUPLES_OK</code> or318        <code class="literal">PGRES_SINGLE_TUPLE</code>, then319        the functions described below can be used to retrieve the rows320        returned by the query.  Note that a <code class="command">SELECT</code>321        command that happens to retrieve zero rows still shows322        <code class="literal">PGRES_TUPLES_OK</code>.323        <code class="literal">PGRES_COMMAND_OK</code> is for commands that can never324        return rows (<code class="command">INSERT</code> or <code class="command">UPDATE</code>325        without a <code class="literal">RETURNING</code> clause,326        etc.). A response of <code class="literal">PGRES_EMPTY_QUERY</code> might327        indicate a bug in the client software.328       </p><p>329        A result of status <code class="symbol">PGRES_NONFATAL_ERROR</code> will330        never be returned directly by <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> or other331        query execution functions; results of this kind are instead passed332        to the notice processor (see <a class="xref" href="libpq-notice-processing.html" title="34.13. Notice Processing">Section 34.13</a>).333       </p></dd><dt id="LIBPQ-PQRESSTATUS"><span class="term"><code class="function">PQresStatus</code><a id="id-1.7.3.10.3.9.7.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESSTATUS" class="id_link">#</a></dt><dd><p>334        Converts the enumerated type returned by335        <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> into a string constant describing the336        status code. The caller should not free the result.337 338</p><pre class="synopsis">339char *PQresStatus(ExecStatusType status);340</pre><p>341       </p></dd><dt id="LIBPQ-PQRESULTERRORMESSAGE"><span class="term"><code class="function">PQresultErrorMessage</code><a id="id-1.7.3.10.3.9.7.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESULTERRORMESSAGE" class="id_link">#</a></dt><dd><p>342        Returns the error message associated with the command, or an empty string343        if there was no error.344</p><pre class="synopsis">345char *PQresultErrorMessage(const PGresult *res);346</pre><p>347        If there was an error, the returned string will include a trailing348        newline.  The caller should not free the result directly. It will349        be freed when the associated <code class="structname">PGresult</code> handle is350        passed to <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.351       </p><p>352        Immediately following a <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> or353        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> call,354        <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> (on the connection) will return355        the same string as <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a> (on356        the result).  However, a <code class="structname">PGresult</code> will357        retain its error message until destroyed, whereas the connection's358        error message will change when subsequent operations are done.359        Use <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a> when you want to360        know the status associated with a particular361        <code class="structname">PGresult</code>; use362        <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> when you want to know the363        status from the latest operation on the connection.364       </p></dd><dt id="LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><span class="term"><code class="function">PQresultVerboseErrorMessage</code><a id="id-1.7.3.10.3.9.7.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESULTVERBOSEERRORMESSAGE" class="id_link">#</a></dt><dd><p>365        Returns a reformatted version of the error message associated with366        a <code class="structname">PGresult</code> object.367</p><pre class="synopsis">368char *PQresultVerboseErrorMessage(const PGresult *res,369                                  PGVerbosity verbosity,370                                  PGContextVisibility show_context);371</pre><p>372        In some situations a client might wish to obtain a more detailed373        version of a previously-reported error.374        <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><code class="function">PQresultVerboseErrorMessage</code></a> addresses this need375        by computing the message that would have been produced376        by <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a> if the specified377        verbosity settings had been in effect for the connection when the378        given <code class="structname">PGresult</code> was generated.  If379        the <code class="structname">PGresult</code> is not an error result,380        <span class="quote">“<span class="quote">PGresult is not an error result</span>”</span> is reported instead.381        The returned string includes a trailing newline.382       </p><p>383        Unlike most other functions for extracting data from384        a <code class="structname">PGresult</code>, the result of this function is a freshly385        allocated string.  The caller must free it386        using <code class="function">PQfreemem()</code> when the string is no longer needed.387       </p><p>388        A NULL return is possible if there is insufficient memory.389       </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> <a href="#LIBPQ-PQRESULTERRORFIELD" class="id_link">#</a></dt><dd><p>390        Returns an individual field of an error report.391</p><pre class="synopsis">392char *PQresultErrorField(const PGresult *res, int fieldcode);393</pre><p>394        <em class="parameter"><code>fieldcode</code></em> is an error field identifier; see the symbols395        listed below.  <code class="symbol">NULL</code> is returned if the396        <code class="structname">PGresult</code> is not an error or warning result,397        or does not include the specified field.  Field values will normally398        not include a trailing newline. The caller should not free the399        result directly. It will be freed when the400        associated <code class="structname">PGresult</code> handle is passed to401        <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.402       </p><p>403        The following field codes are available:404        </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PG-DIAG-SEVERITY"><span class="term"><code class="symbol">PG_DIAG_SEVERITY</code></span> <a href="#LIBPQ-PG-DIAG-SEVERITY" class="id_link">#</a></dt><dd><p>405            The severity; the field contents are <code class="literal">ERROR</code>,406            <code class="literal">FATAL</code>, or <code class="literal">PANIC</code> (in an error message),407            or <code class="literal">WARNING</code>, <code class="literal">NOTICE</code>, <code class="literal">DEBUG</code>,408            <code class="literal">INFO</code>, or <code class="literal">LOG</code> (in a notice message), or409            a localized translation of one of these.  Always present.410           </p></dd><dt id="LIBPQ-PG-DIAG-SEVERITY-NONLOCALIZED"><span class="term"><code class="symbol">PG_DIAG_SEVERITY_NONLOCALIZED</code></span> <a href="#LIBPQ-PG-DIAG-SEVERITY-NONLOCALIZED" class="id_link">#</a></dt><dd><p>411            The severity; the field contents are <code class="literal">ERROR</code>,412            <code class="literal">FATAL</code>, or <code class="literal">PANIC</code> (in an error message),413            or <code class="literal">WARNING</code>, <code class="literal">NOTICE</code>, <code class="literal">DEBUG</code>,414            <code class="literal">INFO</code>, or <code class="literal">LOG</code> (in a notice message).415            This is identical to the <code class="symbol">PG_DIAG_SEVERITY</code> field except416            that the contents are never localized.  This is present only in417            reports generated by <span class="productname">PostgreSQL</span> versions 9.6418            and later.419           </p></dd><dt id="LIBPQ-PG-DIAG-SQLSTATE"><span class="term"><code class="symbol">PG_DIAG_SQLSTATE</code><a id="id-1.7.3.10.3.9.7.5.2.2.1.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PG-DIAG-SQLSTATE" class="id_link">#</a></dt><dd><p>420            The SQLSTATE code for the error. The SQLSTATE code identifies421            the type of error that has occurred; it can be used by422            front-end applications to perform specific operations (such423            as error handling) in response to a particular database error.424            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,425            and is always present.426           </p></dd><dt id="LIBPQ-PG-DIAG-MESSAGE-PRIMARY"><span class="term"><code class="symbol">PG_DIAG_MESSAGE_PRIMARY</code></span> <a href="#LIBPQ-PG-DIAG-MESSAGE-PRIMARY" class="id_link">#</a></dt><dd><p>427            The primary human-readable error message (typically one line).428            Always present.429           </p></dd><dt id="LIBPQ-PG-DIAG-MESSAGE-DETAIL"><span class="term"><code class="symbol">PG_DIAG_MESSAGE_DETAIL</code></span> <a href="#LIBPQ-PG-DIAG-MESSAGE-DETAIL" class="id_link">#</a></dt><dd><p>430            Detail: an optional secondary error message carrying more431            detail about the problem.  Might run to multiple lines.432           </p></dd><dt id="LIBPQ-PG-DIAG-MESSAGE-HINT"><span class="term"><code class="symbol">PG_DIAG_MESSAGE_HINT</code></span> <a href="#LIBPQ-PG-DIAG-MESSAGE-HINT" class="id_link">#</a></dt><dd><p>433            Hint: an optional suggestion what to do about the problem.434            This is intended to differ from detail in that it offers advice435            (potentially inappropriate) rather than hard facts.  Might436            run to multiple lines.437           </p></dd><dt id="LIBPQ-PG-DIAG-STATEMENT-POSITION"><span class="term"><code class="symbol">PG_DIAG_STATEMENT_POSITION</code></span> <a href="#LIBPQ-PG-DIAG-STATEMENT-POSITION" class="id_link">#</a></dt><dd><p>438            A string containing a decimal integer indicating an error cursor439            position as an index into the original statement string.  The440            first character has index 1, and positions are measured in441            characters not bytes.442           </p></dd><dt id="LIBPQ-PG-DIAG-INTERNAL-POSITION"><span class="term"><code class="symbol">PG_DIAG_INTERNAL_POSITION</code></span> <a href="#LIBPQ-PG-DIAG-INTERNAL-POSITION" class="id_link">#</a></dt><dd><p>443            This is defined the same as the444            <code class="symbol">PG_DIAG_STATEMENT_POSITION</code> field, but it is used445            when the cursor position refers to an internally generated446            command rather than the one submitted by the client.  The447            <code class="symbol">PG_DIAG_INTERNAL_QUERY</code> field will always appear when448            this field appears.449           </p></dd><dt id="LIBPQ-PG-DIAG-INTERNAL-QUERY"><span class="term"><code class="symbol">PG_DIAG_INTERNAL_QUERY</code></span> <a href="#LIBPQ-PG-DIAG-INTERNAL-QUERY" class="id_link">#</a></dt><dd><p>450            The text of a failed internally-generated command.  This could451            be, for example, an SQL query issued by a PL/pgSQL function.452           </p></dd><dt id="LIBPQ-PG-DIAG-CONTEXT"><span class="term"><code class="symbol">PG_DIAG_CONTEXT</code></span> <a href="#LIBPQ-PG-DIAG-CONTEXT" class="id_link">#</a></dt><dd><p>453            An indication of the context in which the error occurred.454            Presently this includes a call stack traceback of active455            procedural language functions and internally-generated queries.456            The trace is one entry per line, most recent first.457           </p></dd><dt id="LIBPQ-PG-DIAG-SCHEMA-NAME"><span class="term"><code class="symbol">PG_DIAG_SCHEMA_NAME</code></span> <a href="#LIBPQ-PG-DIAG-SCHEMA-NAME" class="id_link">#</a></dt><dd><p>458            If the error was associated with a specific database object,459            the name of the schema containing that object, if any.460           </p></dd><dt id="LIBPQ-PG-DIAG-TABLE-NAME"><span class="term"><code class="symbol">PG_DIAG_TABLE_NAME</code></span> <a href="#LIBPQ-PG-DIAG-TABLE-NAME" class="id_link">#</a></dt><dd><p>461            If the error was associated with a specific table, the name of the462            table.  (Refer to the schema name field for the name of the463            table's schema.)464           </p></dd><dt id="LIBPQ-PG-DIAG-COLUMN-NAME"><span class="term"><code class="symbol">PG_DIAG_COLUMN_NAME</code></span> <a href="#LIBPQ-PG-DIAG-COLUMN-NAME" class="id_link">#</a></dt><dd><p>465            If the error was associated with a specific table column, the name466            of the column.  (Refer to the schema and table name fields to467            identify the table.)468           </p></dd><dt id="LIBPQ-PG-DIAG-DATATYPE-NAME"><span class="term"><code class="symbol">PG_DIAG_DATATYPE_NAME</code></span> <a href="#LIBPQ-PG-DIAG-DATATYPE-NAME" class="id_link">#</a></dt><dd><p>469            If the error was associated with a specific data type, the name of470            the data type.  (Refer to the schema name field for the name of471            the data type's schema.)472           </p></dd><dt id="LIBPQ-PG-DIAG-CONSTRAINT-NAME"><span class="term"><code class="symbol">PG_DIAG_CONSTRAINT_NAME</code></span> <a href="#LIBPQ-PG-DIAG-CONSTRAINT-NAME" class="id_link">#</a></dt><dd><p>473            If the error was associated with a specific constraint, the name474            of the constraint.  Refer to fields listed above for the475            associated table or domain.  (For this purpose, indexes are476            treated as constraints, even if they weren't created with477            constraint syntax.)478           </p></dd><dt id="LIBPQ-PG-DIAG-SOURCE-FILE"><span class="term"><code class="symbol">PG_DIAG_SOURCE_FILE</code></span> <a href="#LIBPQ-PG-DIAG-SOURCE-FILE" class="id_link">#</a></dt><dd><p>479            The file name of the source-code location where the error was480            reported.481           </p></dd><dt id="LIBPQ-PG-DIAG-SOURCE-LINE"><span class="term"><code class="symbol">PG_DIAG_SOURCE_LINE</code></span> <a href="#LIBPQ-PG-DIAG-SOURCE-LINE" class="id_link">#</a></dt><dd><p>482            The line number of the source-code location where the error483            was reported.484           </p></dd><dt id="LIBPQ-PG-DIAG-SOURCE-FUNCTION"><span class="term"><code class="symbol">PG_DIAG_SOURCE_FUNCTION</code></span> <a href="#LIBPQ-PG-DIAG-SOURCE-FUNCTION" class="id_link">#</a></dt><dd><p>485            The name of the source-code function reporting the error.486           </p></dd></dl></div><p>487       </p><div class="note"><h3 class="title">Note</h3><p>488         The fields for schema name, table name, column name, data type name,489         and constraint name are supplied only for a limited number of error490         types; see <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>.  Do not assume that491         the presence of any of these fields guarantees the presence of492         another field.  Core error sources observe the interrelationships493         noted above, but user-defined functions may use these fields in other494         ways.  In the same vein, do not assume that these fields denote495         contemporary objects in the current database.496        </p></div><p>497        The client is responsible for formatting displayed information to meet498        its needs; in particular it should break long lines as needed.499        Newline characters appearing in the error message fields should be500        treated as paragraph breaks, not line breaks.501       </p><p>502        Errors generated internally by <span class="application">libpq</span> will503        have severity and primary message, but typically no other fields.504       </p><p>505        Note that error fields are only available from506        <code class="structname">PGresult</code> objects, not507        <code class="structname">PGconn</code> objects; there is no508        <code class="function">PQerrorField</code> function.509       </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> <a href="#LIBPQ-PQCLEAR" class="id_link">#</a></dt><dd><p>510        Frees  the  storage  associated with a511        <code class="structname">PGresult</code>.  Every command result should be512        freed via <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> when it  is  no  longer513        needed.514 515</p><pre class="synopsis">516void PQclear(PGresult *res);517</pre><p>518 519        If the argument is a <code class="symbol">NULL</code> pointer, no operation is520        performed.521       </p><p>522        You can keep a <code class="structname">PGresult</code> object around for523        as long as you need it; it does not go away when you issue a new524        command, nor even if you close the connection.  To get rid of it,525        you must call <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.  Failure to do this526        will result in memory leaks in your application.527       </p></dd></dl></div><p>528   </p></div><div class="sect2" id="LIBPQ-EXEC-SELECT-INFO"><div class="titlepage"><div><div><h3 class="title">34.3.2. Retrieving Query Result Information <a href="#LIBPQ-EXEC-SELECT-INFO" class="id_link">#</a></h3></div></div></div><p>529    These functions are used to extract information from a530    <code class="structname">PGresult</code> object that represents a successful531    query result (that is, one that has status532    <code class="literal">PGRES_TUPLES_OK</code> or <code class="literal">PGRES_SINGLE_TUPLE</code>).533    They can also be used to extract534    information from a successful Describe operation: a Describe's result535    has all the same column information that actual execution of the query536    would provide, but it has zero rows.  For objects with other status values,537    these functions will act as though the result has zero rows and zero columns.538   </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQNTUPLES"><span class="term"><code class="function">PQntuples</code><a id="id-1.7.3.10.4.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQNTUPLES" class="id_link">#</a></dt><dd><p>539       Returns the number of rows (tuples) in the query result.540       (Note that <code class="structname">PGresult</code> objects are limited to no more541       than <code class="literal">INT_MAX</code> rows, so an <code class="type">int</code> result is542       sufficient.)543 544</p><pre class="synopsis">545int PQntuples(const PGresult *res);546</pre><p>547 548      </p></dd><dt id="LIBPQ-PQNFIELDS"><span class="term"><code class="function">PQnfields</code><a id="id-1.7.3.10.4.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQNFIELDS" class="id_link">#</a></dt><dd><p>549       Returns the number of columns (fields) in each row of the query550       result.551 552</p><pre class="synopsis">553int PQnfields(const PGresult *res);554</pre><p>555      </p></dd><dt id="LIBPQ-PQFNAME"><span class="term"><code class="function">PQfname</code><a id="id-1.7.3.10.4.3.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFNAME" class="id_link">#</a></dt><dd><p>556       Returns the column name associated with the given column number.557       Column numbers start at 0. The caller should not free the result558       directly. It will be freed when the associated559       <code class="structname">PGresult</code> handle is passed to560       <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.561</p><pre class="synopsis">562char *PQfname(const PGresult *res,563              int column_number);564</pre><p>565      </p><p>566       <code class="symbol">NULL</code> is returned if the column number is out of range.567      </p></dd><dt id="LIBPQ-PQFNUMBER"><span class="term"><code class="function">PQfnumber</code><a id="id-1.7.3.10.4.3.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFNUMBER" class="id_link">#</a></dt><dd><p>568       Returns the column number associated with the given column name.569</p><pre class="synopsis">570int PQfnumber(const PGresult *res,571              const char *column_name);572</pre><p>573      </p><p>574       -1 is returned if the given name does not match any column.575      </p><p>576       The given name is treated like an identifier in an SQL command,577       that is, it is downcased unless double-quoted.  For example, given578       a query result generated from the SQL command:579</p><pre class="programlisting">580SELECT 1 AS FOO, 2 AS "BAR";581</pre><p>582       we would have the results:583</p><pre class="programlisting">584PQfname(res, 0)              <em class="lineannotation"><span class="lineannotation">foo</span></em>585PQfname(res, 1)              <em class="lineannotation"><span class="lineannotation">BAR</span></em>586PQfnumber(res, "FOO")        <em class="lineannotation"><span class="lineannotation">0</span></em>587PQfnumber(res, "foo")        <em class="lineannotation"><span class="lineannotation">0</span></em>588PQfnumber(res, "BAR")        <em class="lineannotation"><span class="lineannotation">-1</span></em>589PQfnumber(res, "\"BAR\"")    <em class="lineannotation"><span class="lineannotation">1</span></em>590</pre><p>591      </p></dd><dt id="LIBPQ-PQFTABLE"><span class="term"><code class="function">PQftable</code><a id="id-1.7.3.10.4.3.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFTABLE" class="id_link">#</a></dt><dd><p>592       Returns the OID of the table from which the given column was593       fetched.  Column numbers start at 0.594</p><pre class="synopsis">595Oid PQftable(const PGresult *res,596             int column_number);597</pre><p>598      </p><p>599       <code class="literal">InvalidOid</code> is returned if the column number is out of range,600       or if the specified column is not a simple reference to a table column.601       You can query the system table <code class="literal">pg_class</code> to determine602       exactly which table is referenced.603      </p><p>604       The type <code class="type">Oid</code> and the constant605       <code class="literal">InvalidOid</code> will be defined when you include606       the <span class="application">libpq</span> header file. They will both607       be some integer type.608      </p></dd><dt id="LIBPQ-PQFTABLECOL"><span class="term"><code class="function">PQftablecol</code><a id="id-1.7.3.10.4.3.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFTABLECOL" class="id_link">#</a></dt><dd><p>609       Returns the column number (within its table) of the column making610       up the specified query result column.  Query-result column numbers611       start at 0, but table columns have nonzero numbers.612</p><pre class="synopsis">613int PQftablecol(const PGresult *res,614                int column_number);615</pre><p>616      </p><p>617       Zero is returned if the column number is out of range, or if the618       specified column is not a simple reference to a table column.619      </p></dd><dt id="LIBPQ-PQFFORMAT"><span class="term"><code class="function">PQfformat</code><a id="id-1.7.3.10.4.3.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFFORMAT" class="id_link">#</a></dt><dd><p>620       Returns the format code indicating the format of the given621       column.  Column numbers start at 0.622</p><pre class="synopsis">623int PQfformat(const PGresult *res,624              int column_number);625</pre><p>626      </p><p>627       Format code zero indicates textual data representation, while format628       code one indicates binary representation.  (Other codes are reserved629       for future definition.)630      </p></dd><dt id="LIBPQ-PQFTYPE"><span class="term"><code class="function">PQftype</code><a id="id-1.7.3.10.4.3.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFTYPE" class="id_link">#</a></dt><dd><p>631       Returns the data type associated with the given  column number.632       The  integer  returned is the internal OID number of the type.633       Column numbers start at 0.634</p><pre class="synopsis">635Oid PQftype(const PGresult *res,636            int column_number);637</pre><p>638      </p><p>639       You can query the system table <code class="literal">pg_type</code> to640       obtain the names and properties of the various data types. The641       <acronym class="acronym">OID</acronym>s of the built-in data types are defined642       in the file <code class="filename">catalog/pg_type_d.h</code>643       in the <span class="productname">PostgreSQL</span>644       installation's <code class="filename">include</code> directory.645      </p></dd><dt id="LIBPQ-PQFMOD"><span class="term"><code class="function">PQfmod</code><a id="id-1.7.3.10.4.3.9.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFMOD" class="id_link">#</a></dt><dd><p>646       Returns  the type modifier of the column associated with the647       given column number.  Column numbers start at 0.648</p><pre class="synopsis">649int PQfmod(const PGresult *res,650           int column_number);651</pre><p>652      </p><p>653       The interpretation of modifier values is type-specific; they654       typically indicate precision or size limits.  The value -1 is655       used to indicate <span class="quote">“<span class="quote">no information available</span>”</span>.  Most data656       types do not use modifiers, in which case the value is always657       -1.658      </p></dd><dt id="LIBPQ-PQFSIZE"><span class="term"><code class="function">PQfsize</code><a id="id-1.7.3.10.4.3.10.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFSIZE" class="id_link">#</a></dt><dd><p>659       Returns  the  size  in bytes of the column associated with the660       given column number.  Column numbers start at 0.661</p><pre class="synopsis">662int PQfsize(const PGresult *res,663            int column_number);664</pre><p>665      </p><p>666       <a class="xref" href="libpq-exec.html#LIBPQ-PQFSIZE"><code class="function">PQfsize</code></a> returns the space allocated for this column667       in a database row, in other words the size of the server's668       internal representation of the data type.  (Accordingly, it is669       not really very useful to clients.) A negative value indicates670       the data type is variable-length.671      </p></dd><dt id="LIBPQ-PQBINARYTUPLES"><span class="term"><code class="function">PQbinaryTuples</code><a id="id-1.7.3.10.4.3.11.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQBINARYTUPLES" class="id_link">#</a></dt><dd><p>672       Returns 1 if the <code class="structname">PGresult</code> contains binary data673       and 0 if it contains text data.674</p><pre class="synopsis">675int PQbinaryTuples(const PGresult *res);676</pre><p>677      </p><p>678       This function is deprecated (except for its use in connection with679       <code class="command">COPY</code>), because it is possible for a single680       <code class="structname">PGresult</code> to contain text data in some columns and681       binary data in others.  <a class="xref" href="libpq-exec.html#LIBPQ-PQFFORMAT"><code class="function">PQfformat</code></a> is preferred.682       <a class="xref" href="libpq-exec.html#LIBPQ-PQBINARYTUPLES"><code class="function">PQbinaryTuples</code></a> returns 1 only if all columns of the683       result are binary (format 1).684      </p></dd><dt id="LIBPQ-PQGETVALUE"><span class="term"><code class="function">PQgetvalue</code><a id="id-1.7.3.10.4.3.12.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETVALUE" class="id_link">#</a></dt><dd><p>685       Returns a single field value of one row of a686       <code class="structname">PGresult</code>.  Row and column numbers start687       at 0.  The caller should not free the result directly.  It will688       be freed when the associated <code class="structname">PGresult</code> handle is689       passed to <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.690</p><pre class="synopsis">691char *PQgetvalue(const PGresult *res,692                 int row_number,693                 int column_number);694</pre><p>695      </p><p>696       For data in text format, the value returned by697       <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a> is a null-terminated character698       string  representation of the field value.  For data in binary699       format, the value is in the binary representation determined by700       the data type's <code class="function">typsend</code> and <code class="function">typreceive</code>701       functions.  (The value is actually followed by a zero byte in702       this case too, but that is not ordinarily useful, since the703       value is likely to contain embedded nulls.)704      </p><p>705       An empty string is returned if the field value is null.  See706       <a class="xref" href="libpq-exec.html#LIBPQ-PQGETISNULL"><code class="function">PQgetisnull</code></a> to distinguish null values from707       empty-string values.708      </p><p>709       The pointer returned  by  <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a> points710       to storage that is part of the <code class="structname">PGresult</code>711       structure.  One should not modify the data it points to, and one712       must explicitly copy the data into other storage if it is to be713       used past the lifetime of the  <code class="structname">PGresult</code>714       structure itself.715      </p></dd><dt id="LIBPQ-PQGETISNULL"><span class="term"><code class="function">PQgetisnull</code><a id="id-1.7.3.10.4.3.13.1.2" class="indexterm"></a><a id="id-1.7.3.10.4.3.13.1.3" class="indexterm"></a></span> <a href="#LIBPQ-PQGETISNULL" class="id_link">#</a></dt><dd><p>716       Tests a field for a null value.  Row and column numbers start717       at 0.718</p><pre class="synopsis">719int PQgetisnull(const PGresult *res,720                int row_number,721                int column_number);722</pre><p>723      </p><p>724       This function returns  1 if the field is null and 0 if it725       contains a non-null value.  (Note that726       <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a> will return an empty string,727       not a null pointer, for a null field.)728      </p></dd><dt id="LIBPQ-PQGETLENGTH"><span class="term"><code class="function">PQgetlength</code><a id="id-1.7.3.10.4.3.14.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETLENGTH" class="id_link">#</a></dt><dd><p>729       Returns the actual length of a field value in bytes.  Row and730       column numbers start at 0.731</p><pre class="synopsis">732int PQgetlength(const PGresult *res,733                int row_number,734                int column_number);735</pre><p>736      </p><p>737       This is the actual data length for the particular data value,738       that is, the size of the object pointed to by739       <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a>.  For text data format this is740       the same as <code class="function">strlen()</code>.  For binary format this is741       essential information.  Note that one should <span class="emphasis"><em>not</em></span>742       rely on <a class="xref" href="libpq-exec.html#LIBPQ-PQFSIZE"><code class="function">PQfsize</code></a> to obtain the actual data743       length.744      </p></dd><dt id="LIBPQ-PQNPARAMS"><span class="term"><code class="function">PQnparams</code><a id="id-1.7.3.10.4.3.15.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQNPARAMS" class="id_link">#</a></dt><dd><p>745       Returns the number of parameters of a prepared statement.746</p><pre class="synopsis">747int PQnparams(const PGresult *res);748</pre><p>749      </p><p>750       This function is only useful when inspecting the result of751       <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>.  For other types of results it752       will return zero.753      </p></dd><dt id="LIBPQ-PQPARAMTYPE"><span class="term"><code class="function">PQparamtype</code><a id="id-1.7.3.10.4.3.16.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPARAMTYPE" class="id_link">#</a></dt><dd><p>754       Returns the data type of the indicated statement parameter.755       Parameter numbers start at 0.756</p><pre class="synopsis">757Oid PQparamtype(const PGresult *res, int param_number);758</pre><p>759      </p><p>760       This function is only useful when inspecting the result of761       <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>.  For other types of results it762       will return zero.763      </p></dd><dt id="LIBPQ-PQPRINT"><span class="term"><code class="function">PQprint</code><a id="id-1.7.3.10.4.3.17.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPRINT" class="id_link">#</a></dt><dd><p>764       Prints out all the rows and,  optionally,  the column names  to765       the specified output stream.766</p><pre class="synopsis">767void PQprint(FILE *fout,      /* output stream */768             const PGresult *res,769             const PQprintOpt *po);770typedef struct771{772    pqbool  header;      /* print output field headings and row count */773    pqbool  align;       /* fill align the fields */774    pqbool  standard;    /* old brain dead format */775    pqbool  html3;       /* output HTML tables */776    pqbool  expanded;    /* expand tables */777    pqbool  pager;       /* use pager for output if needed */778    char    *fieldSep;   /* field separator */779    char    *tableOpt;   /* attributes for HTML table element */780    char    *caption;    /* HTML table caption */781    char    **fieldName; /* null-terminated array of replacement field names */782} PQprintOpt;783</pre><p>784      </p><p>785       This function was formerly used by <span class="application">psql</span>786       to print query results, but this is no longer the case.  Note787       that it assumes all the data is in text format.788      </p></dd></dl></div></div><div class="sect2" id="LIBPQ-EXEC-NONSELECT"><div class="titlepage"><div><div><h3 class="title">34.3.3. Retrieving Other Result Information <a href="#LIBPQ-EXEC-NONSELECT" class="id_link">#</a></h3></div></div></div><p>789    These functions are used to extract other information from790    <code class="structname">PGresult</code> objects.791   </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCMDSTATUS"><span class="term"><code class="function">PQcmdStatus</code><a id="id-1.7.3.10.5.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCMDSTATUS" class="id_link">#</a></dt><dd><p>792       Returns the command status tag from the SQL command that generated793       the <code class="structname">PGresult</code>.794</p><pre class="synopsis">795char *PQcmdStatus(PGresult *res);796</pre><p>797      </p><p>798       Commonly this is just the name of the command, but it might include799       additional data such as the number of rows processed. The caller800       should not free the result directly. It will be freed when the801       associated <code class="structname">PGresult</code> handle is passed to802       <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.803      </p></dd><dt id="LIBPQ-PQCMDTUPLES"><span class="term"><code class="function">PQcmdTuples</code><a id="id-1.7.3.10.5.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCMDTUPLES" class="id_link">#</a></dt><dd><p>804       Returns the number of rows affected by the SQL command.805</p><pre class="synopsis">806char *PQcmdTuples(PGresult *res);807</pre><p>808      </p><p>809       This function returns a string containing the number of rows810       affected by the <acronym class="acronym">SQL</acronym> statement that generated the811       <code class="structname">PGresult</code>. This function can only be used following812       the execution of a <code class="command">SELECT</code>, <code class="command">CREATE TABLE AS</code>,813       <code class="command">INSERT</code>, <code class="command">UPDATE</code>, <code class="command">DELETE</code>,814       <code class="command">MERGE</code>, <code class="command">MOVE</code>, <code class="command">FETCH</code>,815       or <code class="command">COPY</code> statement, or an <code class="command">EXECUTE</code> of a816       prepared query that contains an <code class="command">INSERT</code>,817       <code class="command">UPDATE</code>, <code class="command">DELETE</code>,818       or <code class="command">MERGE</code> statement.819       If the command that generated the <code class="structname">PGresult</code> was anything820       else, <a class="xref" href="libpq-exec.html#LIBPQ-PQCMDTUPLES"><code class="function">PQcmdTuples</code></a> returns an empty string. The caller821       should not free the return value directly. It will be freed when822       the associated <code class="structname">PGresult</code> handle is passed to823       <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.824      </p></dd><dt id="LIBPQ-PQOIDVALUE"><span class="term"><code class="function">PQoidValue</code><a id="id-1.7.3.10.5.3.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQOIDVALUE" class="id_link">#</a></dt><dd><p>825       Returns the OID<a id="id-1.7.3.10.5.3.3.2.1.1" class="indexterm"></a>826       of the inserted row, if the <acronym class="acronym">SQL</acronym> command was an827       <code class="command">INSERT</code> that inserted exactly one row into a table that828       has OIDs, or a <code class="command">EXECUTE</code> of a prepared query containing829       a suitable <code class="command">INSERT</code> statement.  Otherwise, this function830       returns <code class="literal">InvalidOid</code>. This function will also831       return <code class="literal">InvalidOid</code> if the table affected by the832       <code class="command">INSERT</code> statement does not contain OIDs.833</p><pre class="synopsis">834Oid PQoidValue(const PGresult *res);835</pre><p>836      </p></dd><dt id="LIBPQ-PQOIDSTATUS"><span class="term"><code class="function">PQoidStatus</code><a id="id-1.7.3.10.5.3.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQOIDSTATUS" class="id_link">#</a></dt><dd><p>837       This function is deprecated in favor of838       <a class="xref" href="libpq-exec.html#LIBPQ-PQOIDVALUE"><code class="function">PQoidValue</code></a> and is not thread-safe.839       It returns a string with the OID of the inserted row, while840       <a class="xref" href="libpq-exec.html#LIBPQ-PQOIDVALUE"><code class="function">PQoidValue</code></a> returns the OID value.841</p><pre class="synopsis">842char *PQoidStatus(const PGresult *res);843</pre><p>844      </p></dd></dl></div></div><div class="sect2" id="LIBPQ-EXEC-ESCAPE-STRING"><div class="titlepage"><div><div><h3 class="title">34.3.4. Escaping Strings for Inclusion in SQL Commands <a href="#LIBPQ-EXEC-ESCAPE-STRING" class="id_link">#</a></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"><code class="function">PQescapeLiteral</code><a id="id-1.7.3.10.6.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQESCAPELITERAL" class="id_link">#</a></dt><dd><p>845</p><pre class="synopsis">846char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);847</pre><p>848     </p><p>849      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> escapes a string for850      use within an SQL command.  This is useful when inserting data851      values as literal constants in SQL commands.  Certain characters852      (such as quotes and backslashes) must be escaped to prevent them853      from being interpreted specially by the SQL parser.854      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> performs this operation.855     </p><p>856      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> returns an escaped version of the857      <em class="parameter"><code>str</code></em> parameter in memory allocated with858      <code class="function">malloc()</code>.  This memory should be freed using859      <code class="function">PQfreemem()</code> when the result is no longer needed.860      A terminating zero byte is not required, and should not be861      counted in <em class="parameter"><code>length</code></em>.  (If a terminating zero byte is found862      before <em class="parameter"><code>length</code></em> bytes are processed,863      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> stops at the zero; the behavior is864      thus rather like <code class="function">strncpy</code>.) The865      return string has all special characters replaced so that they can866      be properly processed by the <span class="productname">PostgreSQL</span>867      string literal parser.  A terminating zero byte is also added.  The868      single quotes that must surround <span class="productname">PostgreSQL</span>869      string literals are included in the result string.870     </p><p>871      On error, <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> returns <code class="symbol">NULL</code> and a suitable872      message is stored in the <em class="parameter"><code>conn</code></em> object.873     </p><div class="tip"><h3 class="title">Tip</h3><p>874       It is especially important to do proper escaping when handling875       strings that were received from an untrustworthy source.876       Otherwise there is a security risk: you are vulnerable to877       <span class="quote">“<span class="quote">SQL injection</span>”</span> attacks wherein unwanted SQL commands are878       fed to your database.879      </p></div><p>880      Note that it is neither necessary nor correct to do escaping when a data881      value is passed as a separate parameter in <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a> or882      its sibling routines.883     </p></dd><dt id="LIBPQ-PQESCAPEIDENTIFIER"><span class="term"><code class="function">PQescapeIdentifier</code><a id="id-1.7.3.10.6.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQESCAPEIDENTIFIER" class="id_link">#</a></dt><dd><p>884</p><pre class="synopsis">885char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);886</pre><p>887     </p><p>888      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER"><code class="function">PQescapeIdentifier</code></a> escapes a string for889      use as an SQL identifier, such as a table, column, or function name.890      This is useful when a user-supplied identifier might contain891      special characters that would otherwise not be interpreted as part892      of the identifier by the SQL parser, or when the identifier might893      contain upper case characters whose case should be preserved.894     </p><p>895      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER"><code class="function">PQescapeIdentifier</code></a> returns a version of the896      <em class="parameter"><code>str</code></em> parameter escaped as an SQL identifier897      in memory allocated with <code class="function">malloc()</code>.  This memory must be898      freed using <code class="function">PQfreemem()</code> when the result is no longer899      needed.  A terminating zero byte is not required, and should not be900      counted in <em class="parameter"><code>length</code></em>.  (If a terminating zero byte is found901      before <em class="parameter"><code>length</code></em> bytes are processed,902      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER"><code class="function">PQescapeIdentifier</code></a> stops at the zero; the behavior is903      thus rather like <code class="function">strncpy</code>.) The904      return string has all special characters replaced so that it905      will be properly processed as an SQL identifier.  A terminating zero byte906      is also added.  The return string will also be surrounded by double907      quotes.908     </p><p>909      On error, <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER"><code class="function">PQescapeIdentifier</code></a> returns <code class="symbol">NULL</code> and a suitable910      message is stored in the <em class="parameter"><code>conn</code></em> object.911     </p><div class="tip"><h3 class="title">Tip</h3><p>912       As with string literals, to prevent SQL injection attacks,913       SQL identifiers must be escaped when they are received from an914       untrustworthy source.915      </p></div></dd><dt id="LIBPQ-PQESCAPESTRINGCONN"><span class="term"><code class="function">PQescapeStringConn</code><a id="id-1.7.3.10.6.3.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQESCAPESTRINGCONN" class="id_link">#</a></dt><dd><p>916</p><pre class="synopsis">917size_t PQescapeStringConn(PGconn *conn,918                          char *to, const char *from, size_t length,919                          int *error);920</pre><p>921     </p><p>922      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> escapes string literals, much like923      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a>.  Unlike <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a>,924      the caller is responsible for providing an appropriately sized buffer.925      Furthermore, <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> does not generate the926      single quotes that must surround <span class="productname">PostgreSQL</span> string927      literals; they should be provided in the SQL command that the928      result is inserted into.  The parameter <em class="parameter"><code>from</code></em> points to929      the first character of the string that is to be escaped, and the930      <em class="parameter"><code>length</code></em> parameter gives the number of bytes in this931      string.  A terminating zero byte is not required, and should not be932      counted in <em class="parameter"><code>length</code></em>.  (If a terminating zero byte is found933      before <em class="parameter"><code>length</code></em> bytes are processed,934      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> stops at the zero; the behavior is935      thus rather like <code class="function">strncpy</code>.) <em class="parameter"><code>to</code></em> shall point936      to a buffer that is able to hold at least one more byte than twice937      the value of <em class="parameter"><code>length</code></em>, otherwise the behavior is undefined.938      Behavior is likewise undefined if the <em class="parameter"><code>to</code></em> and939      <em class="parameter"><code>from</code></em> strings overlap.940     </p><p>941      If the <em class="parameter"><code>error</code></em> parameter is not <code class="symbol">NULL</code>, then942      <code class="literal">*error</code> is set to zero on success, nonzero on error.943      Presently the only possible error conditions involve invalid multibyte944      encoding in the source string.  The output string is still generated945      on error, but it can be expected that the server will reject it as946      malformed.  On error, a suitable message is stored in the947      <em class="parameter"><code>conn</code></em> object, whether or not <em class="parameter"><code>error</code></em> is <code class="symbol">NULL</code>.948     </p><p>949      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> returns the number of bytes written950      to <em class="parameter"><code>to</code></em>, not including the terminating zero byte.951     </p></dd><dt id="LIBPQ-PQESCAPESTRING"><span class="term"><code class="function">PQescapeString</code><a id="id-1.7.3.10.6.3.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQESCAPESTRING" class="id_link">#</a></dt><dd><p>952       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRING"><code class="function">PQescapeString</code></a> is an older, deprecated version of953       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a>.954</p><pre class="synopsis">955size_t PQescapeString (char *to, const char *from, size_t length);956</pre><p>957     </p><p>958      The only difference from <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> is that959      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRING"><code class="function">PQescapeString</code></a> does not take <code class="structname">PGconn</code>960      or <em class="parameter"><code>error</code></em> parameters.961      Because of this, it cannot adjust its behavior depending on the962      connection properties (such as character encoding) and therefore963      <span class="emphasis"><em>it might give the wrong results</em></span>.  Also, it has no way964      to report error conditions.965     </p><p>966      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRING"><code class="function">PQescapeString</code></a> can be used safely in967      client programs that work with only one <span class="productname">PostgreSQL</span>968      connection at a time (in this case it can find out what it needs to969      know <span class="quote">“<span class="quote">behind the scenes</span>”</span>).  In other contexts it is a security970      hazard and should be avoided in favor of971      <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a>.972     </p></dd><dt id="LIBPQ-PQESCAPEBYTEACONN"><span class="term"><code class="function">PQescapeByteaConn</code><a id="id-1.7.3.10.6.3.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQESCAPEBYTEACONN" class="id_link">#</a></dt><dd><p>973       Escapes binary data for use within an SQL command with the type974       <code class="type">bytea</code>.  As with <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a>,975       this is only used when inserting data directly into an SQL command string.976</p><pre class="synopsis">977unsigned char *PQescapeByteaConn(PGconn *conn,978                                 const unsigned char *from,979                                 size_t from_length,980                                 size_t *to_length);981</pre><p>982      </p><p>983       Certain byte values must be escaped when used as part of a984       <code class="type">bytea</code> literal in an <acronym class="acronym">SQL</acronym> statement.985       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a> escapes bytes using986       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.987      </p><p>988       The <em class="parameter"><code>from</code></em> parameter points to the first989       byte of the string that is to be escaped, and the990       <em class="parameter"><code>from_length</code></em> parameter gives the number of991       bytes in this binary string.  (A terminating zero byte is992       neither necessary nor counted.)  The <em class="parameter"><code>to_length</code></em>993       parameter points to a variable that will hold the resultant994       escaped string length. This result string length includes the terminating995       zero byte of the result.996      </p><p>997       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a> returns an escaped version of the998       <em class="parameter"><code>from</code></em> parameter binary string in memory999       allocated with <code class="function">malloc()</code>.  This memory should be freed using1000       <code class="function">PQfreemem()</code> when the result is no longer needed.  The1001       return string has all special characters replaced so that they can1002       be properly processed by the <span class="productname">PostgreSQL</span>1003       string literal parser, and the <code class="type">bytea</code> input function. A1004       terminating zero byte is also added.  The single quotes that must1005       surround <span class="productname">PostgreSQL</span> string literals are1006       not part of the result string.1007      </p><p>1008       On error, a null pointer is returned, and a suitable error message1009       is stored in the <em class="parameter"><code>conn</code></em> object.  Currently, the only1010       possible error is insufficient memory for the result string.1011      </p></dd><dt id="LIBPQ-PQESCAPEBYTEA"><span class="term"><code class="function">PQescapeBytea</code><a id="id-1.7.3.10.6.3.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQESCAPEBYTEA" class="id_link">#</a></dt><dd><p>1012       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a> is an older, deprecated version of1013       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a>.1014</p><pre class="synopsis">1015unsigned char *PQescapeBytea(const unsigned char *from,1016                             size_t from_length,1017                             size_t *to_length);1018</pre><p>1019      </p><p>1020       The only difference from <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a> is that1021       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a> does not take a <code class="structname">PGconn</code>1022       parameter.  Because of this, <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a> can1023       only be used safely in client programs that use a single1024       <span class="productname">PostgreSQL</span> connection at a time (in this case1025       it can find out what it needs to know <span class="quote">“<span class="quote">behind the1026       scenes</span>”</span>).  It <span class="emphasis"><em>might give the wrong results</em></span> if1027       used in programs that use multiple database connections (use1028       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a> in such cases).1029      </p></dd><dt id="LIBPQ-PQUNESCAPEBYTEA"><span class="term"><code class="function">PQunescapeBytea</code><a id="id-1.7.3.10.6.3.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQUNESCAPEBYTEA" class="id_link">#</a></dt><dd><p>1030       Converts a string representation of binary data into binary data1031       — the reverse of <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a>.  This1032       is needed when retrieving <code class="type">bytea</code> data in text format,1033       but not when retrieving it in binary format.1034 1035</p><pre class="synopsis">1036unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);1037</pre><p>1038      </p><p>1039       The <em class="parameter"><code>from</code></em> parameter points to a string1040       such as might be returned by <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a> when applied1041       to a <code class="type">bytea</code> column. <a class="xref" href="libpq-exec.html#LIBPQ-PQUNESCAPEBYTEA"><code class="function">PQunescapeBytea</code></a>1042       converts this string representation into its binary representation.1043       It returns a pointer to a buffer allocated with1044       <code class="function">malloc()</code>, or <code class="symbol">NULL</code> on error, and puts the size of1045       the buffer in <em class="parameter"><code>to_length</code></em>. The result must be1046       freed using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a> when it is no longer needed.1047      </p><p>1048       This conversion is not exactly the inverse of1049       <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a>, because the string is not expected1050       to be <span class="quote">“<span class="quote">escaped</span>”</span> when received from <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a>.1051       In particular this means there is no need for string quoting considerations,1052       and so no need for a <code class="structname">PGconn</code> parameter.1053      </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" title="34.2. Connection Status Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-async.html" title="34.4. Asynchronous Command Processing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.2. Connection Status Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.4. Asynchronous Command Processing</td></tr></table></div></body></html>
codekingpro/portable-devtools · Team Ai