<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Command Execution Functions</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REV="MADE" HREF="mailto:pgsql-docs@postgresql.org"><LINK REL="HOME" TITLE="PostgreSQL 8.0.11 Documentation" HREF="index.html"><LINK REL="UP" TITLE="libpq - C Library" HREF="libpq.html"><LINK REL="PREVIOUS" TITLE="Connection Status Functions" HREF="libpq-status.html"><LINK REL="NEXT" TITLE="Asynchronous Command Processing" HREF="libpq-async.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"><META NAME="creation" CONTENT="2007-02-02T03:57:22"></HEAD ><BODY CLASS="SECT1" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="5" ALIGN="center" VALIGN="bottom" >PostgreSQL 8.0.11 Documentation</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="libpq-status.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="libpq.html" >Fast Backward</A ></TD ><TD WIDTH="60%" ALIGN="center" VALIGN="bottom" >Chapter 27. <SPAN CLASS="APPLICATION" >libpq</SPAN > - C Library</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="top" ><A HREF="libpq.html" >Fast Forward</A ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="top" ><A HREF="libpq-async.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="LIBPQ-EXEC" >27.3. Command Execution Functions</A ></H1 ><P >Once a connection to a database server has been successfully established, the functions described here are used to perform SQL queries and commands.</P ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-EXEC-MAIN" >27.3.1. Main Functions</A ></H2 ><P ><P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><CODE CLASS="FUNCTION" >PQexec</CODE ><A NAME="AEN23144" ></A ></DT ><DD ><P > Submits a command to the server and waits for the result. </P><PRE CLASS="SYNOPSIS" >PGresult *PQexec(PGconn *conn, const char *command);</PRE ><P></P ><P > Returns a <TT CLASS="STRUCTNAME" >PGresult</TT > pointer or possibly a null pointer. A non-null pointer will generally be returned except in out-of-memory conditions or serious errors such as inability to send the command to the server. If a null pointer is returned, it should be treated like a <TT CLASS="SYMBOL" >PGRES_FATAL_ERROR</TT > result. Use <CODE CLASS="FUNCTION" >PQerrorMessage</CODE > to get more information about such errors.</P ></DD ></DL ></DIV ><P> It is allowed to include multiple SQL commands (separated by semicolons) in the command string. Multiple queries sent in a single <CODE CLASS="FUNCTION" >PQexec</CODE > call are processed in a single transaction, unless there are explicit <TT CLASS="COMMAND" >BEGIN</TT >/<TT CLASS="COMMAND" >COMMIT</TT > commands included in the query string to divide it into multiple transactions. Note however that the returned <TT CLASS="STRUCTNAME" >PGresult</TT > structure describes only the result of the last command executed from the string. Should one of the commands fail, processing of the string stops with it and the returned <TT CLASS="STRUCTNAME" >PGresult</TT > describes the error condition.</P ><P ><P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><CODE CLASS="FUNCTION" >PQexecParams</CODE ><A NAME="AEN23163" ></A ></DT ><DD ><P > Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text. </P><PRE CLASS="SYNOPSIS" >PGresult *PQexecParams(PGconn *conn, const char *command, int nParams, const Oid *paramTypes, const char * const *paramValues, const int *paramLengths, const int *paramFormats, int resultFormat);</PRE ><P></P ><P ><CODE CLASS="FUNCTION" >PQexecParams</CODE > is like <CODE CLASS="FUNCTION" >PQexec</CODE >, but offers additional functionality: parameter values can be specified separately from the command string proper, and query results can be requested in either text or binary format. <CODE CLASS="FUNCTION" >PQexecParams</CODE > is supported only in protocol 3.0 and later connections; it will fail when using protocol 2.0.</P ><P >If parameters are used, they are referred to in the command string as <TT CLASS="LITERAL" >$1</TT >, <TT CLASS="LITERAL" >$2</TT >, etc. <TT CLASS="PARAMETER" >nParams</TT > is the number of parameters supplied; it is the length of the arrays <TT CLASS="PARAMETER" >paramTypes[]</TT >, <TT CLASS="PARAMETER" >paramValues[]</TT >, <TT CLASS="PARAMETER" >paramLengths[]</TT >, and <TT CLASS="PARAMETER" >paramFormats[]</TT >. (The array pointers may be <TT CLASS="SYMBOL" >NULL</TT > when <TT CLASS="PARAMETER" >nParams</TT > is zero.) <TT CLASS="PARAMETER" >paramTypes[]</TT > specifies, by OID, the data types to be assigned to the parameter symbols. If <TT CLASS="PARAMETER" >paramTypes</TT > is <TT CLASS="SYMBOL" >NULL</TT >, or any particular element in the array is zero, the server assigns a data type to the parameter symbol in the same way it would do for an untyped literal string. <TT CLASS="PARAMETER" >paramValues[]</TT > specifies the actual values of the parameters. A null pointer in this array means the corresponding parameter is null; otherwise the pointer points to a zero-terminated text string (for text format) or binary data in the format expected by the server (for binary format). <TT CLASS="PARAMETER" >paramLengths[]</TT > specifies the actual data lengths of binary-format parameters. It is ignored for null parameters and text-format parameters. The array pointer may be null when there are no binary parameters. <TT CLASS="PARAMETER" >paramFormats[]</TT > specifies whether parameters are text (put a zero in the array) or binary (put a one in the array). If the array pointer is null then all parameters are presumed to be text. <TT CLASS="PARAMETER" >resultFormat</TT > is zero to obtain results in text format, or one to obtain results in binary format. (There is not currently a provision to obtain different result columns in different formats, although that is possible in the underlying protocol.)</P ></DD ></DL ></DIV ><P> The primary advantage of <CODE CLASS="FUNCTION" >PQexecParams</CODE > over <CODE CLASS="FUNCTION" >PQexec</CODE > is that parameter values may be separated from the command string, thus avoiding the need for tedious and error-prone quoting and escaping. Unlike <CODE CLASS="FUNCTION" >PQexec</CODE >, <CODE CLASS="FUNCTION" >PQexecParams</CODE > allows at most one SQL command in the given string. (There can be semicolons in it, but not more than one nonempty command.) This is a limitation of the underlying protocol, but has some usefulness as an extra defense against SQL-injection attacks.</P ><P ><P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><CODE CLASS="FUNCTION" >PQprepare</CODE ><A NAME="AEN23198" ></A ></DT ><DD ><P > Submits a request to create a prepared statement with the given parameters, and waits for completion. </P><PRE CLASS="SYNOPSIS" >PGresult *PQprepare(PGconn *conn, const char *stmtName, const char *query, int nParams, const Oid *paramTypes);</PRE ><P></P ><P ><CODE CLASS="FUNCTION" >PQprepare</CODE > creates a prepared statement for later execution with <CODE CLASS="FUNCTION" >PQexecPrepared</CODE >. This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed. <CODE CLASS="FUNCTION" >PQprepare</CODE > is supported only in protocol 3.0 and later connections; it will fail when using protocol 2.0.</P ><P >The function creates a prepared statement named <TT CLASS="PARAMETER" >stmtName</TT > from the <TT CLASS="PARAMETER" >query</TT > string, which must contain a single SQL command. <TT CLASS="PARAMETER" >stmtName</TT > may be <TT CLASS="LITERAL" >""</TT > to create an unnamed statement, in which case any pre-existing unnamed statement is automatically replaced; otherwise it is an error if the statement name is already defined in the current session. If any parameters are used, they are referred to in the query as <TT CLASS="LITERAL" >$1</TT >, <TT CLASS="LITERAL" >$2</TT >, etc. <TT CLASS="PARAMETER" >nParams</TT > is the number of parameters for which types are pre-specified in the array <TT CLASS="PARAMETER" >paramTypes[]</TT >. (The array pointer may be <TT CLASS="SYMBOL" >NULL</TT > when <TT CLASS="PARAMETER" >nParams</TT > is zero.) <TT CLASS="PARAMETER" >paramTypes[]</TT > specifies, by OID, the data types to be assigned to the parameter symbols. If <TT CLASS="PARAMETER" >paramTypes</TT > is <TT CLASS="SYMBOL" >NULL</TT >, or any particular element in the array is zero, the server assigns a data type to the parameter symbol in the same way it would do for an untyped literal string. Also, the query may use parameter symbols with numbers higher than <TT CLASS="PARAMETER" >nParams</TT >; data types will be inferred for these symbols as well.</P ><P >As with <CODE CLASS="FUNCTION" >PQexec</CODE >, the result is normally a <TT CLASS="STRUCTNAME" >PGresult</TT > object whose contents indicate server-side success or failure. A null result indicates out-of-memory or inability to send the command at all. Use <CODE CLASS="FUNCTION" >PQerrorMessage</CODE > to get more information about such errors.</P ><P >At present, there is no way to determine the actual data type inferred for any parameters whose types are not specified in <TT CLASS="PARAMETER" >paramTypes[]</TT >. This is a <SPAN CLASS="APPLICATION" >libpq</SPAN > omission that will probably be rectified in a future release.</P ></DD ></DL ></DIV ><P> Prepared statements for use with <CODE CLASS="FUNCTION" >PQexecPrepared</CODE > can also be created by executing SQL <TT CLASS="COMMAND" >PREPARE</TT > statements. (But <CODE CLASS="FUNCTION" >PQprepare</CODE > is more flexible since it does not require parameter types to be pre-specified.) Also, although there is no <SPAN CLASS="APPLICATION" >libpq</SPAN > function for deleting a prepared statement, the SQL <TT CLASS="COMMAND" >DEALLOCATE</TT > statement can be used for that purpose.</P ><P ><P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><CODE CLASS="FUNCTION" >PQexecPrepared</CODE ><A NAME="AEN23239" ></A ></DT ><DD ><P > Sends a request to execute a prepared statement with given parameters, and waits for the result. </P><PRE CLASS="SYNOPSIS" >PGresult *PQexecPrepared(PGconn *conn, const char *stmtName, int nParams, const char * const *paramValues, const int *paramLengths, const int *paramFormats, int resultFormat);</PRE ><P></P ><P ><CODE CLASS="FUNCTION" >PQexecPrepared</CODE > is like <CODE CLASS="FUNCTION" >PQexecParams</CODE >, but the command to be executed is specified by naming a previously-prepared statement, instead of giving a query string. This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed. The statement must have been prepared previously in the current session. <CODE CLASS="FUNCTION" >PQexecPrepared</CODE > is supported only in protocol 3.0 and later connections; it will fail when using protocol 2.0.</P ><P >The parameters are identical to <CODE CLASS="FUNCTION" >PQexecParams</CODE >, except that the name of a prepared statement is given instead of a query string, and the <TT CLASS="PARAMETER" >paramTypes[]</TT > parameter is not present (it is not needed since the prepared statement's parameter types were determined when it was created).</P ></DD ></DL ></DIV ><P></P ><P >The <TT CLASS="STRUCTNAME" >PGresult</TT ><A NAME="AEN23253" ></A > structure encapsulates the result returned by the server. <SPAN CLASS="APPLICATION" >libpq</SPAN > application programmers should be careful to maintain the <TT CLASS="STRUCTNAME" >PGresult</TT > abstraction. Use the accessor functions below to get at the contents of <TT CLASS="STRUCTNAME" >PGresult</TT >. Avoid directly referencing the fields of the <TT CLASS="STRUCTNAME" >PGresult</TT > structure because they are subject to change in the future. <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><CODE CLASS="FUNCTION" >PQresultStatus</CODE ><A NAME="AEN23263" ></A ></DT ><DD ><P > Returns the result status of the command. </P><PRE CLASS="SYNOPSIS" >ExecStatusType PQresultStatus(const PGresult *res);</PRE ><P></P ><P ><CODE CLASS="FUNCTION" >PQresultStatus</CODE > can return one of the following values: <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="LITERAL" >PGRES_EMPTY_QUERY</TT ></DT ><DD ><P >The string sent to the server was empty.</P ></DD ><DT ><TT CLASS="LITERAL" >PGRES_COMMAND_OK</TT ></DT ><DD ><P >Successful completion of a command returning no data.</P ></DD ><DT ><TT CLASS="LITERAL" >PGRES_TUPLES_OK</TT ></DT ><DD ><P >Successful completion of a command returning data (such as a <TT CLASS="COMMAND" >SELECT</TT > or <TT CLASS="COMMAND" >SHOW</TT >).</P ></DD ><DT ><TT CLASS="LITERAL" >PGRES_COPY_OUT</TT ></DT ><DD ><P >Copy Out (from server) data transfer started.</P ></DD ><DT ><TT CLASS="LITERAL" >PGRES_COPY_IN</TT ></DT ><DD ><P >Copy In (to server) data transfer started.</P ></DD ><DT ><TT CLASS="LITERAL" >PGRES_BAD_RESPONSE</TT ></DT ><DD ><P >The server's response was not understood.</P ></DD ><DT ><TT CLASS="LITERAL" >PGRES_NONFATAL_ERROR</TT ></DT ><DD ><P >A nonfatal error (a notice or warning) occurred.</P ></DD ><DT ><TT CLASS="LITERAL" >PGRES_FATAL_ERROR</TT ></DT ><DD ><P >A fatal error occurred.</P ></DD ></DL ></DIV ><P> If the result status is <TT CLASS="LITERAL" >PGRES_TUPLES_OK</TT >, then the functions described below can be used to retrieve the rows returned by the query. Note that a <TT CLASS="COMMAND" >SELECT</TT > command that happens to retrieve zero rows still shows <TT CLASS="LITERAL" >PGRES_TUPLES_OK</TT >. <TT CLASS="LITERAL" >PGRES_COMMAND_OK</TT > is for commands that can never return rows (<TT CLASS="COMMAND" >INSERT</TT >, <TT CLASS="COMMAND" >UPDATE</TT >, etc.). A response of <TT CLASS="LITERAL" >PGRES_EMPTY_QUERY</TT > may indicate a bug in the client software.</P ><P >A result of status <TT CLASS="SYMBOL" >PGRES_NONFATAL_ERROR</TT > will never be returned directly by <CODE CLASS="FUNCTION" >PQexec</CODE > or other query execution functions; results of this kind are instead passed to the notice processor (see <A HREF="libpq-notice-processing.html" >Section 27.10</A >).</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQresStatus</CODE ><A NAME="AEN23327" ></A ></DT ><DD ><P > Converts the enumerated type returned by <CODE CLASS="FUNCTION" >PQresultStatus</CODE > into a string constant describing the status code. The caller should not free the result. </P><PRE CLASS="SYNOPSIS" >char *PQresStatus(ExecStatusType status);</PRE ><P></P ></DD ><DT ><CODE CLASS="FUNCTION" >PQresultErrorMessage</CODE ><A NAME="AEN23336" ></A ></DT ><DD ><P >Returns the error message associated with the command, or an empty string if there was no error. </P><PRE CLASS="SYNOPSIS" >char *PQresultErrorMessage(const PGresult *res);</PRE ><P> If there was an error, the returned string will include a trailing newline. The caller should not free the result directly. It will be freed when the associated <TT CLASS="STRUCTNAME" >PGresult</TT > handle is passed to <CODE CLASS="FUNCTION" >PQclear</CODE >.</P ><P >Immediately following a <CODE CLASS="FUNCTION" >PQexec</CODE > or <CODE CLASS="FUNCTION" >PQgetResult</CODE > call, <CODE CLASS="FUNCTION" >PQerrorMessage</CODE > (on the connection) will return the same string as <CODE CLASS="FUNCTION" >PQresultErrorMessage</CODE > (on the result). However, a <TT CLASS="STRUCTNAME" >PGresult</TT > will retain its error message until destroyed, whereas the connection's error message will change when subsequent operations are done. Use <CODE CLASS="FUNCTION" >PQresultErrorMessage</CODE > when you want to know the status associated with a particular <TT CLASS="STRUCTNAME" >PGresult</TT >; use <CODE CLASS="FUNCTION" >PQerrorMessage</CODE > when you want to know the status from the latest operation on the connection.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQresultErrorField</CODE ><A NAME="AEN23355" ></A ></DT ><DD ><P >Returns an individual field of an error report. </P><PRE CLASS="SYNOPSIS" >char *PQresultErrorField(const PGresult *res, int fieldcode);</PRE ><P> <TT CLASS="PARAMETER" >fieldcode</TT > is an error field identifier; see the symbols listed below. <TT CLASS="SYMBOL" >NULL</TT > is returned if the <TT CLASS="STRUCTNAME" >PGresult</TT > is not an error or warning result, or does not include the specified field. Field values will normally not include a trailing newline. The caller should not free the result directly. It will be freed when the associated <TT CLASS="STRUCTNAME" >PGresult</TT > handle is passed to <CODE CLASS="FUNCTION" >PQclear</CODE >.</P ><P >The following field codes are available: <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="SYMBOL" >PG_DIAG_SEVERITY</TT ></DT ><DD ><P >The severity; the field contents are <TT CLASS="LITERAL" >ERROR</TT >, <TT CLASS="LITERAL" >FATAL</TT >, or <TT CLASS="LITERAL" >PANIC</TT > (in an error message), or <TT CLASS="LITERAL" >WARNING</TT >, <TT CLASS="LITERAL" >NOTICE</TT >, <TT CLASS="LITERAL" >DEBUG</TT >, <TT CLASS="LITERAL" >INFO</TT >, or <TT CLASS="LITERAL" >LOG</TT > (in a notice message), or a localized translation of one of these. Always present.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_SQLSTATE</TT ></DT ><DD ><P >The SQLSTATE code for the error. The SQLSTATE code identifies the type of error that has occurred; it can be used by front-end applications to perform specific operations (such as error handling) in response to a particular database error. For a list of the possible SQLSTATE codes, see <A HREF="errcodes-appendix.html" >Appendix A</A >. This field is not localizable, and is always present.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_MESSAGE_PRIMARY</TT ></DT ><DD ><P >The primary human-readable error message (typically one line). Always present.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_MESSAGE_DETAIL</TT ></DT ><DD ><P >Detail: an optional secondary error message carrying more detail about the problem. May run to multiple lines.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_MESSAGE_HINT</TT ></DT ><DD ><P >Hint: an optional suggestion what to do about the problem. This is intended to differ from detail in that it offers advice (potentially inappropriate) rather than hard facts. May run to multiple lines.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_STATEMENT_POSITION</TT ></DT ><DD ><P >A string containing a decimal integer indicating an error cursor position as an index into the original statement string. The first character has index 1, and positions are measured in characters not bytes.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_INTERNAL_POSITION</TT ></DT ><DD ><P >This is defined the same as the <TT CLASS="SYMBOL" >PG_DIAG_STATEMENT_POSITION</TT > field, but it is used when the cursor position refers to an internally generated command rather than the one submitted by the client. The <TT CLASS="SYMBOL" >PG_DIAG_INTERNAL_QUERY</TT > field will always appear when this field appears.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_INTERNAL_QUERY</TT ></DT ><DD ><P >The text of a failed internally-generated command. This could be, for example, a SQL query issued by a PL/pgSQL function.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_CONTEXT</TT ></DT ><DD ><P >An indication of the context in which the error occurred. Presently this includes a call stack traceback of active procedural language functions and internally-generated queries. The trace is one entry per line, most recent first.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_SOURCE_FILE</TT ></DT ><DD ><P >The file name of the source-code location where the error was reported.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_SOURCE_LINE</TT ></DT ><DD ><P >The line number of the source-code location where the error was reported.</P ></DD ><DT ><TT CLASS="SYMBOL" >PG_DIAG_SOURCE_FUNCTION</TT ></DT ><DD ><P >The name of the source-code function reporting the error.</P ></DD ></DL ></DIV ><P></P ><P >The client is responsible for formatting displayed information to meet its needs; in particular it should break long lines as needed. Newline characters appearing in the error message fields should be treated as paragraph breaks, not line breaks.</P ><P >Errors generated internally by <SPAN CLASS="APPLICATION" >libpq</SPAN > will have severity and primary message, but typically no other fields. Errors returned by a pre-3.0-protocol server will include severity and primary message, and sometimes a detail message, but no other fields.</P ><P >Note that error fields are only available from <TT CLASS="STRUCTNAME" >PGresult</TT > objects, not <TT CLASS="STRUCTNAME" >PGconn</TT > objects; there is no <CODE CLASS="FUNCTION" >PQerrorField</CODE > function.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQclear</CODE ><A NAME="AEN23451" ></A ></DT ><DD ><P > Frees the storage associated with a <TT CLASS="STRUCTNAME" >PGresult</TT >. Every command result should be freed via <CODE CLASS="FUNCTION" >PQclear</CODE > when it is no longer needed. </P><PRE CLASS="SYNOPSIS" >void PQclear(PGresult *res);</PRE ><P></P ><P > You can keep a <TT CLASS="STRUCTNAME" >PGresult</TT > object around for as long as you need it; it does not go away when you issue a new command, nor even if you close the connection. To get rid of it, you must call <CODE CLASS="FUNCTION" >PQclear</CODE >. Failure to do this will result in memory leaks in your application.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQmakeEmptyPGresult</CODE ><A NAME="AEN23464" ></A ></DT ><DD ><P > Constructs an empty <TT CLASS="STRUCTNAME" >PGresult</TT > object with the given status. </P><PRE CLASS="SYNOPSIS" >PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);</PRE ><P></P ><P >This is <SPAN CLASS="APPLICATION" >libpq</SPAN >'s internal function to allocate and initialize an empty <TT CLASS="STRUCTNAME" >PGresult</TT > object. It is exported because some applications find it useful to generate result objects (particularly objects with error status) themselves. If <TT CLASS="PARAMETER" >conn</TT > is not null and <TT CLASS="PARAMETER" >status</TT > indicates an error, the current error message of the specified connection is copied into the <TT CLASS="STRUCTNAME" >PGresult</TT >. Note that <CODE CLASS="FUNCTION" >PQclear</CODE > should eventually be called on the object, just as with a <TT CLASS="STRUCTNAME" >PGresult</TT > returned by <SPAN CLASS="APPLICATION" >libpq</SPAN > itself.</P ></DD ></DL ></DIV ><P></P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-EXEC-SELECT-INFO" >27.3.2. Retrieving Query Result Information</A ></H2 ><P >These functions are used to extract information from a <TT CLASS="STRUCTNAME" >PGresult</TT > object that represents a successful query result (that is, one that has status <TT CLASS="LITERAL" >PGRES_TUPLES_OK</TT >). For objects with other status values they will act as though the result has zero rows and zero columns.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><CODE CLASS="FUNCTION" >PQntuples</CODE ><A NAME="AEN23488" ></A ></DT ><DD ><P > Returns the number of rows (tuples) in the query result. </P><PRE CLASS="SYNOPSIS" >int PQntuples(const PGresult *res);</PRE ><P></P ></DD ><DT ><CODE CLASS="FUNCTION" >PQnfields</CODE ><A NAME="AEN23496" ></A ></DT ><DD ><P > Returns the number of columns (fields) in each row of the query result. </P><PRE CLASS="SYNOPSIS" >int PQnfields(const PGresult *res);</PRE ><P></P ></DD ><DT ><CODE CLASS="FUNCTION" >PQfname</CODE ><A NAME="AEN23504" ></A ></DT ><DD ><P >Returns the column name associated with the given column number. Column numbers start at 0. The caller should not free the result directly. It will be freed when the associated <TT CLASS="STRUCTNAME" >PGresult</TT > handle is passed to <CODE CLASS="FUNCTION" >PQclear</CODE >. </P><PRE CLASS="SYNOPSIS" >char *PQfname(const PGresult *res, int column_number);</PRE ><P></P ><P ><TT CLASS="SYMBOL" >NULL</TT > is returned if the column number is out of range.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQfnumber</CODE ><A NAME="AEN23516" ></A ></DT ><DD ><P > Returns the column number associated with the given column name. </P><PRE CLASS="SYNOPSIS" >int PQfnumber(const PGresult *res, const char *column_name);</PRE ><P></P ><P > -1 is returned if the given name does not match any column.</P ><P > The given name is treated like an identifier in an SQL command, that is, it is downcased unless double-quoted. For example, given a query result generated from the SQL command </P><PRE CLASS="PROGRAMLISTING" >select 1 as FOO, 2 as "BAR";</PRE ><P> we would have the results: </P><PRE CLASS="PROGRAMLISTING" >PQfname(res, 0) <I CLASS="LINEANNOTATION" >foo</I > PQfname(res, 1) <I CLASS="LINEANNOTATION" >BAR</I > PQfnumber(res, "FOO") <I CLASS="LINEANNOTATION" >0</I > PQfnumber(res, "foo") <I CLASS="LINEANNOTATION" >0</I > PQfnumber(res, "BAR") <I CLASS="LINEANNOTATION" >-1</I > PQfnumber(res, "\"BAR\"") <I CLASS="LINEANNOTATION" >1</I ></PRE ><P></P ></DD ><DT ><CODE CLASS="FUNCTION" >PQftable</CODE ><A NAME="AEN23534" ></A ></DT ><DD ><P > Returns the OID of the table from which the given column was fetched. Column numbers start at 0. </P><PRE CLASS="SYNOPSIS" >Oid PQftable(const PGresult *res, int column_number);</PRE ><P></P ><P ><TT CLASS="LITERAL" >InvalidOid</TT > is returned if the column number is out of range, or if the specified column is not a simple reference to a table column, or when using pre-3.0 protocol. You can query the system table <TT CLASS="LITERAL" >pg_class</TT > to determine exactly which table is referenced.</P ><P > The type <TT CLASS="TYPE" >Oid</TT > and the constant <TT CLASS="LITERAL" >InvalidOid</TT > will be defined when you include the <SPAN CLASS="APPLICATION" >libpq</SPAN > header file. They will both be some integer type.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQftablecol</CODE ><A NAME="AEN23549" ></A ></DT ><DD ><P > Returns the column number (within its table) of the column making up the specified query result column. Query-result column numbers start at 0, but table columns have nonzero numbers. </P><PRE CLASS="SYNOPSIS" >int PQftablecol(const PGresult *res, int column_number);</PRE ><P></P ><P >Zero is returned if the column number is out of range, or if the specified column is not a simple reference to a table column, or when using pre-3.0 protocol.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQfformat</CODE ><A NAME="AEN23558" ></A ></DT ><DD ><P > Returns the format code indicating the format of the given column. Column numbers start at 0. </P><PRE CLASS="SYNOPSIS" >int PQfformat(const PGresult *res, int column_number);</PRE ><P></P ><P >Format code zero indicates textual data representation, while format code one indicates binary representation. (Other codes are reserved for future definition.)</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQftype</CODE ><A NAME="AEN23567" ></A ></DT ><DD ><P > Returns the data type associated with the given column number. The integer returned is the internal OID number of the type. Column numbers start at 0. </P><PRE CLASS="SYNOPSIS" >Oid PQftype(const PGresult *res, int column_number);</PRE ><P></P ><P >You can query the system table <TT CLASS="LITERAL" >pg_type</TT > to obtain the names and properties of the various data types. The <ACRONYM CLASS="ACRONYM" >OID</ACRONYM >s of the built-in data types are defined in the file <TT CLASS="FILENAME" >src/include/catalog/pg_type.h</TT > in the source tree.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQfmod</CODE ><A NAME="AEN23579" ></A ></DT ><DD ><P > Returns the type modifier of the column associated with the given column number. Column numbers start at 0. </P><PRE CLASS="SYNOPSIS" >int PQfmod(const PGresult *res, int column_number);</PRE ><P></P ><P >The interpretation of modifier values is type-specific; they typically indicate precision or size limits. The value -1 is used to indicate <SPAN CLASS="QUOTE" >"no information available"</SPAN >. Most data types do not use modifiers, in which case the value is always -1.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQfsize</CODE ><A NAME="AEN23589" ></A ></DT ><DD ><P > Returns the size in bytes of the column associated with the given column number. Column numbers start at 0. </P><PRE CLASS="SYNOPSIS" >int PQfsize(const PGresult *res, int column_number);</PRE ><P></P ><P ><CODE CLASS="FUNCTION" >PQfsize</CODE > returns the space allocated for this column in a database row, in other words the size of the server's internal representation of the data type. (Accordingly, it is not really very useful to clients.) A negative value indicates the data type is variable-length.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQbinaryTuples</CODE ><A NAME="AEN23599" ></A ></DT ><DD ><P >Returns 1 if the <TT CLASS="STRUCTNAME" >PGresult</TT > contains binary data and 0 if it contains text data. </P><PRE CLASS="SYNOPSIS" >int PQbinaryTuples(const PGresult *res);</PRE ><P></P ><P >This function is deprecated (except for its use in connection with <TT CLASS="COMMAND" >COPY</TT >), because it is possible for a single <TT CLASS="STRUCTNAME" >PGresult</TT > to contain text data in some columns and binary data in others. <CODE CLASS="FUNCTION" >PQfformat</CODE > is preferred. <CODE CLASS="FUNCTION" >PQbinaryTuples</CODE > returns 1 only if all columns of the result are binary (format 1).</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQgetvalue</CODE ><A NAME="AEN23613" ></A ></DT ><DD ><P > Returns a single field value of one row of a <TT CLASS="STRUCTNAME" >PGresult</TT >. Row and column numbers start at 0. The caller should not free the result directly. It will be freed when the associated <TT CLASS="STRUCTNAME" >PGresult</TT > handle is passed to <CODE CLASS="FUNCTION" >PQclear</CODE >. </P><PRE CLASS="SYNOPSIS" >char *PQgetvalue(const PGresult *res, int row_number, int column_number);</PRE ><P></P ><P >For data in text format, the value returned by <CODE CLASS="FUNCTION" >PQgetvalue</CODE > is a null-terminated character string representation of the field value. For data in binary format, the value is in the binary representation determined by the data type's <CODE CLASS="FUNCTION" >typsend</CODE > and <CODE CLASS="FUNCTION" >typreceive</CODE > functions. (The value is actually followed by a zero byte in this case too, but that is not ordinarily useful, since the value is likely to contain embedded nulls.)</P ><P >An empty string is returned if the field value is null. See <CODE CLASS="FUNCTION" >PQgetisnull</CODE > to distinguish null values from empty-string values.</P ><P >The pointer returned by <CODE CLASS="FUNCTION" >PQgetvalue</CODE > points to storage that is part of the <TT CLASS="STRUCTNAME" >PGresult</TT > structure. One should not modify the data it points to, and one must explicitly copy the data into other storage if it is to be used past the lifetime of the <TT CLASS="STRUCTNAME" >PGresult</TT > structure itself.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQgetisnull</CODE ><A NAME="AEN23634" ></A ></DT ><DD ><P > Tests a field for a null value. Row and column numbers start at 0. </P><PRE CLASS="SYNOPSIS" >int PQgetisnull(const PGresult *res, int row_number, int column_number);</PRE ><P></P ><P >This function returns 1 if the field is null and 0 if it contains a non-null value. (Note that <CODE CLASS="FUNCTION" >PQgetvalue</CODE > will return an empty string, not a null pointer, for a null field.)</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQgetlength</CODE ><A NAME="AEN23647" ></A ></DT ><DD ><P > Returns the actual length of a field value in bytes. Row and column numbers start at 0. </P><PRE CLASS="SYNOPSIS" >int PQgetlength(const PGresult *res, int row_number, int column_number);</PRE ><P></P ><P >This is the actual data length for the particular data value, that is, the size of the object pointed to by <CODE CLASS="FUNCTION" >PQgetvalue</CODE >. For text data format this is the same as <CODE CLASS="FUNCTION" >strlen()</CODE >. For binary format this is essential information. Note that one should <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >not</I ></SPAN > rely on <CODE CLASS="FUNCTION" >PQfsize</CODE > to obtain the actual data length.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQprint</CODE ><A NAME="AEN23660" ></A ></DT ><DD ><P > Prints out all the rows and, optionally, the column names to the specified output stream. </P><PRE CLASS="SYNOPSIS" >void PQprint(FILE *fout, /* output stream */ const PGresult *res, const PQprintOpt *po); typedef struct { pqbool header; /* print output field headings and row count */ pqbool align; /* fill align the fields */ pqbool standard; /* old brain dead format */ pqbool html3; /* output HTML tables */ pqbool expanded; /* expand tables */ pqbool pager; /* use pager for output if needed */ char *fieldSep; /* field separator */ char *tableOpt; /* attributes for HTML table element */ char *caption; /* HTML table caption */ char **fieldName; /* null-terminated array of replacement field names */ } PQprintOpt;</PRE ><P></P ><P >This function was formerly used by <SPAN CLASS="APPLICATION" >psql</SPAN > to print query results, but this is no longer the case. Note that it assumes all the data is in text format.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-EXEC-NONSELECT" >27.3.3. Retrieving Result Information for Other Commands</A ></H2 ><P >These functions are used to extract information from <TT CLASS="STRUCTNAME" >PGresult</TT > objects that are not <TT CLASS="COMMAND" >SELECT</TT > results.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><CODE CLASS="FUNCTION" >PQcmdStatus</CODE ><A NAME="AEN23676" ></A ></DT ><DD ><P > Returns the command status tag from the SQL command that generated the <TT CLASS="STRUCTNAME" >PGresult</TT >. </P><PRE CLASS="SYNOPSIS" >char *PQcmdStatus(PGresult *res);</PRE ><P></P ><P >Commonly this is just the name of the command, but it may include additional data such as the number of rows processed. The caller should not free the result directly. It will be freed when the associated <TT CLASS="STRUCTNAME" >PGresult</TT > handle is passed to <CODE CLASS="FUNCTION" >PQclear</CODE >.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQcmdTuples</CODE ><A NAME="AEN23688" ></A ></DT ><DD ><P > Returns the number of rows affected by the SQL command. </P><PRE CLASS="SYNOPSIS" >char *PQcmdTuples(PGresult *res);</PRE ><P></P ><P > This function returns a string containing the number of rows affected by the <ACRONYM CLASS="ACRONYM" >SQL</ACRONYM > statement that generated the <TT CLASS="STRUCTNAME" >PGresult</TT >. This function can only be used following the execution of an <TT CLASS="COMMAND" >INSERT</TT >, <TT CLASS="COMMAND" >UPDATE</TT >, <TT CLASS="COMMAND" >DELETE</TT >, <TT CLASS="COMMAND" >MOVE</TT >, or <TT CLASS="COMMAND" >FETCH</TT > statement, or an <TT CLASS="COMMAND" >EXECUTE</TT > of a prepared query that contains a <TT CLASS="COMMAND" >INSERT</TT >, <TT CLASS="COMMAND" >UPDATE</TT >, or <TT CLASS="COMMAND" >DELETE</TT > statement. If the command that generated the <TT CLASS="STRUCTNAME" >PGresult</TT > was anything else, <CODE CLASS="FUNCTION" >PQcmdTuples</CODE > returns the empty string. The caller should not free the return value directly. It will be freed when the associated <TT CLASS="STRUCTNAME" >PGresult</TT > handle is passed to <CODE CLASS="FUNCTION" >PQclear</CODE >.</P ></DD ><DT ><CODE CLASS="FUNCTION" >PQoidValue</CODE ><A NAME="AEN23712" ></A ></DT ><DD ><P > Returns the OID<A NAME="AEN23716" ></A > of the inserted row, if the <ACRONYM CLASS="ACRONYM" >SQL</ACRONYM > command was an <TT CLASS="COMMAND" >INSERT</TT > that inserted exactly one row into a table that has OIDs, or a <TT CLASS="COMMAND" >EXECUTE</TT > of a prepared query containing a suitable <TT CLASS="COMMAND" >INSERT</TT > statement. Otherwise, this function returns <TT CLASS="LITERAL" >InvalidOid</TT >. This function will also return <TT CLASS="LITERAL" >InvalidOid</TT > if the table affected by the <TT CLASS="COMMAND" >INSERT</TT > statement does not contain OIDs. </P><PRE CLASS="SYNOPSIS" >Oid PQoidValue(const PGresult *res);</PRE ><P></P ></DD ><DT ><CODE CLASS="FUNCTION" >PQoidStatus</CODE ><A NAME="AEN23730" ></A ></DT ><DD ><P > Returns a string with the OID of the inserted row, if the <ACRONYM CLASS="ACRONYM" >SQL</ACRONYM > command was an <TT CLASS="COMMAND" >INSERT</TT > that inserted exactly one row, or a <TT CLASS="COMMAND" >EXECUTE</TT > of a prepared statement consisting of a suitable <TT CLASS="COMMAND" >INSERT</TT >. (The string will be <TT CLASS="LITERAL" >0</TT > if the <TT CLASS="COMMAND" >INSERT</TT > did not insert exactly one row, or if the target table does not have OIDs.) If the command was not an <TT CLASS="COMMAND" >INSERT</TT >, returns an empty string. </P><PRE CLASS="SYNOPSIS" >char *PQoidStatus(const PGresult *res);</PRE ><P></P ><P >This function is deprecated in favor of <CODE CLASS="FUNCTION" >PQoidValue</CODE >. It is not thread-safe.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-EXEC-ESCAPE-STRING" >27.3.4. Escaping Strings for Inclusion in SQL Commands</A ></H2 ><A NAME="AEN23746" ></A ><A NAME="AEN23748" ></A ><A NAME="AEN23750" ></A ><P ><CODE CLASS="FUNCTION" >PQescapeStringConn</CODE > escapes a string for use within an SQL command. This is useful when inserting data values as literal constants in SQL commands. Certain characters (such as quotes and backslashes) must be escaped to prevent them from being interpreted specially by the SQL parser. <CODE CLASS="FUNCTION" >PQescapeStringConn</CODE > performs this operation.</P ><DIV CLASS="TIP" ><BLOCKQUOTE CLASS="TIP" ><P ><B >Tip: </B >It is especially important to do proper escaping when handling strings that were received from an untrustworthy source. Otherwise there is a security risk: you are vulnerable to <SPAN CLASS="QUOTE" >"SQL injection"</SPAN > attacks wherein unwanted SQL commands are fed to your database.</P ></BLOCKQUOTE ></DIV ><P >Note that it is not necessary nor correct to do escaping when a data value is passed as a separate parameter in <CODE CLASS="FUNCTION" >PQexecParams</CODE > or its sibling routines. </P><PRE CLASS="SYNOPSIS" >size_t PQescapeStringConn (PGconn *conn, char *to, const char *from, size_t length, int *error);</PRE ><P></P ><P ><CODE CLASS="FUNCTION" >PQescapeStringConn</CODE > writes an escaped version of the <TT CLASS="PARAMETER" >from</TT > string to the <TT CLASS="PARAMETER" >to</TT > buffer, escaping special characters so that they cannot cause any harm, and adding a terminating zero byte. The single quotes that must surround <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > string literals are not included in the result string; they should be provided in the SQL command that the result is inserted into. The parameter <TT CLASS="PARAMETER" >from</TT > points to the first character of the string that is to be escaped, and the <TT CLASS="PARAMETER" >length</TT > parameter gives the number of bytes in this string. A terminating zero byte is not required, and should not be counted in <TT CLASS="PARAMETER" >length</TT >. (If a terminating zero byte is found before <TT CLASS="PARAMETER" >length</TT > bytes are processed, <CODE CLASS="FUNCTION" >PQescapeStringConn</CODE > stops at the zero; the behavior is thus rather like <CODE CLASS="FUNCTION" >strncpy</CODE >.) <TT CLASS="PARAMETER" >to</TT > shall point to a buffer that is able to hold at least one more byte than twice the value of <TT CLASS="PARAMETER" >length</TT >, otherwise the behavior is undefined. Behavior is likewise undefined if the <TT CLASS="PARAMETER" >to</TT > and <TT CLASS="PARAMETER" >from</TT > strings overlap.</P ><P >If the <TT CLASS="PARAMETER" >error</TT > parameter is not NULL, then <TT CLASS="LITERAL" >*error</TT > is set to zero on success, nonzero on error. Presently the only possible error conditions involve invalid multibyte encoding in the source string. The output string is still generated on error, but it can be expected that the server will reject it as malformed. On error, a suitable message is stored in the <TT CLASS="PARAMETER" >conn</TT > object, whether or not <TT CLASS="PARAMETER" >error</TT > is NULL.</P ><P ><CODE CLASS="FUNCTION" >PQescapeStringConn</CODE > returns the number of bytes written to <TT CLASS="PARAMETER" >to</TT >, not including the terminating zero byte.</P ><P ></P><PRE CLASS="SYNOPSIS" >size_t PQescapeString (char *to, const char *from, size_t length);</PRE ><P></P ><P ><CODE CLASS="FUNCTION" >PQescapeString</CODE > is an older, deprecated version of <CODE CLASS="FUNCTION" >PQescapeStringConn</CODE >; the difference is that it does not take <TT CLASS="PARAMETER" >conn</TT > or <TT CLASS="PARAMETER" >error</TT > parameters. Because of this, it cannot adjust its behavior depending on the connection properties (such as character encoding) and therefore <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >it may give the wrong results</I ></SPAN >. Also, it has no way to report error conditions.</P ><P ><CODE CLASS="FUNCTION" >PQescapeString</CODE > can be used safely in single-threaded client programs that work with only one <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > connection at a time (in this case it can find out what it needs to know <SPAN CLASS="QUOTE" >"behind the scenes"</SPAN >). In other contexts it is a security hazard and should be avoided in favor of <CODE CLASS="FUNCTION" >PQescapeStringConn</CODE >.</P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-EXEC-ESCAPE-BYTEA" >27.3.5. Escaping Binary Strings for Inclusion in SQL Commands</A ></H2 ><A NAME="AEN23799" ></A ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><CODE CLASS="FUNCTION" >PQescapeByteaConn</CODE ><A NAME="AEN23806" ></A ></DT ><DD ><P > Escapes binary data for use within an SQL command with the type <TT CLASS="TYPE" >bytea</TT >. As with <CODE CLASS="FUNCTION" >PQescapeStringConn</CODE >, this is only used when inserting data directly into an SQL command string. </P><PRE CLASS="SYNOPSIS" >unsigned char *PQescapeByteaConn(PGconn *conn, const unsigned char *from, size_t from_length, size_t *to_length);</PRE ><P></P ><P > Certain byte values <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >must</I ></SPAN > be escaped (but all byte values <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >can</I ></SPAN > be escaped) when used as part of a <TT CLASS="TYPE" >bytea</TT > literal in an <ACRONYM CLASS="ACRONYM" >SQL</ACRONYM > statement. In general, to escape a byte, it is converted into the three digit octal number equal to the octet value, and preceded by one or two backslashes. The single quote (<TT CLASS="LITERAL" >'</TT >) and backslash (<TT CLASS="LITERAL" >\</TT >) characters have special alternative escape sequences. See <A HREF="datatype-binary.html" >Section 8.4</A > for more information. <CODE CLASS="FUNCTION" >PQescapeByteaConn</CODE > performs this operation, escaping only the minimally required bytes. </P ><P > The <TT CLASS="PARAMETER" >from</TT > parameter points to the first byte of the string that is to be escaped, and the <TT CLASS="PARAMETER" >from_length</TT > parameter gives the number of bytes in this binary string. (A terminating zero byte is neither necessary nor counted.) The <TT CLASS="PARAMETER" >to_length</TT > parameter points to a variable that will hold the resultant escaped string length. This result string length includes the terminating zero byte of the result. </P ><P > <CODE CLASS="FUNCTION" >PQescapeByteaConn</CODE > returns an escaped version of the <TT CLASS="PARAMETER" >from</TT > parameter binary string in memory allocated with <CODE CLASS="FUNCTION" >malloc()</CODE >. This memory must be freed using <CODE CLASS="FUNCTION" >PQfreemem()</CODE > when the result is no longer needed. The return string has all special characters replaced so that they can be properly processed by the <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > string literal parser, and the <TT CLASS="TYPE" >bytea</TT > input function. A terminating zero byte is also added. The single quotes that must surround <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > string literals are not part of the result string. </P ><P > On error, a NULL pointer is returned, and a suitable error message is stored in the <TT CLASS="PARAMETER" >conn</TT > object. Currently, the only possible error is insufficient memory for the result string. </P ></DD ><DT ><CODE CLASS="FUNCTION" >PQescapeBytea</CODE ><A NAME="AEN23839" ></A ></DT ><DD ><P > <CODE CLASS="FUNCTION" >PQescapeBytea</CODE > is an older, deprecated version of <CODE CLASS="FUNCTION" >PQescapeByteaConn</CODE >. </P><PRE CLASS="SYNOPSIS" >unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, size_t *to_length);</PRE ><P></P ><P > The only difference from <CODE CLASS="FUNCTION" >PQescapeByteaConn</CODE > is that <CODE CLASS="FUNCTION" >PQescapeBytea</CODE > does not take a <TT CLASS="STRUCTNAME" >PGconn</TT > parameter. Because of this, it cannot adjust its behavior depending on the connection properties (in particular, whether standard-conforming strings are enabled) and therefore <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >it may give the wrong results</I ></SPAN >. Also, it has no way to return an error message on failure. </P ><P > <CODE CLASS="FUNCTION" >PQescapeBytea</CODE > can be used safely in single-threaded client programs that work with only one <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > connection at a time (in this case it can find out what it needs to know <SPAN CLASS="QUOTE" >"behind the scenes"</SPAN >). In other contexts it is a security hazard and should be avoided in favor of <CODE CLASS="FUNCTION" >PQescapeByteaConn</CODE >. </P ></DD ><DT ><CODE CLASS="FUNCTION" >PQunescapeBytea</CODE ><A NAME="AEN23859" ></A ></DT ><DD ><P > Converts a string representation of binary data into binary data — the reverse of <CODE CLASS="FUNCTION" >PQescapeBytea</CODE >. This is needed when retrieving <TT CLASS="TYPE" >bytea</TT > data in text format, but not when retrieving it in binary format. </P><PRE CLASS="SYNOPSIS" >unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);</PRE ><P></P ><P > The <TT CLASS="PARAMETER" >from</TT > parameter points to a string such as might be returned by <CODE CLASS="FUNCTION" >PQgetvalue</CODE > when applied to a <TT CLASS="TYPE" >bytea</TT > column. <CODE CLASS="FUNCTION" >PQunescapeBytea</CODE > converts this string representation into its binary representation. It returns a pointer to a buffer allocated with <CODE CLASS="FUNCTION" >malloc()</CODE >, or null on error, and puts the size of the buffer in <TT CLASS="PARAMETER" >to_length</TT >. The result must be freed using <CODE CLASS="FUNCTION" >PQfreemem</CODE > when it is no longer needed. </P ><P > This conversion is not exactly the inverse of <CODE CLASS="FUNCTION" >PQescapeBytea</CODE >, because the string is not expected to be <SPAN CLASS="QUOTE" >"escaped"</SPAN > when received from <CODE CLASS="FUNCTION" >PQgetvalue</CODE >. In particular this means there is no need for string quoting considerations, and so no need for a <TT CLASS="STRUCTNAME" >PGconn</TT > parameter. </P ></DD ><DT ><CODE CLASS="FUNCTION" >PQfreemem</CODE ><A NAME="AEN23882" ></A ></DT ><DD ><P > Frees memory allocated by <SPAN CLASS="APPLICATION" >libpq</SPAN >. </P><PRE CLASS="SYNOPSIS" >void PQfreemem(void *ptr);</PRE ><P></P ><P > Frees memory allocated by <SPAN CLASS="APPLICATION" >libpq</SPAN >, particularly <CODE CLASS="FUNCTION" >PQescapeByteaConn</CODE >, <CODE CLASS="FUNCTION" >PQescapeBytea</CODE >, <CODE CLASS="FUNCTION" >PQunescapeBytea</CODE >, and <CODE CLASS="FUNCTION" >PQnotifies</CODE >. It is needed by Microsoft Windows, which cannot free memory across DLLs, unless multithreaded DLLs (<TT CLASS="OPTION" >/MD</TT > in VC6) are used. On other platforms, this function is the same as the standard library function <CODE CLASS="FUNCTION" >free()</CODE >. </P ></DD ></DL ></DIV ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="libpq-status.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="libpq-async.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Connection Status Functions</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="libpq.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Asynchronous Command Processing</TD ></TR ></TABLE ></DIV ></BODY ></HTML >