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