-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.241 2007/09/01 22:08:41 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.242 2007/09/01 23:06:29 momjian Exp $ -->
<chapter id="libpq">
<title><application>libpq</application> - C Library</title>
<synopsis>
PGconn *PQconnectdb(const char *conninfo);
</synopsis>
- </para>
-
- <para>
- This function opens a new database connection using the parameters taken
- from the string <literal>conninfo</literal>. Unlike <function>PQsetdbLogin</> below,
- the parameter set can be extended without changing the function signature,
- so use of this function (or its nonblocking analogues <function>PQconnectStart</>
- and <function>PQconnectPoll</function>) is preferred for new application programming.
</para>
- <para>
- The passed string
- can be empty to use all default parameters, or it can contain one or more
- parameter settings separated by whitespace.
- Each parameter setting is in the form <literal>keyword = value</literal>.
- Spaces around the equal sign are optional.
- To write an empty value or a value containing
- spaces, surround it with single quotes, e.g.,
- <literal>keyword = 'a value'</literal>.
- Single quotes and backslashes within the value must be escaped with a
- backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
- </para>
-
- <para>
- The currently recognized parameter key words are:
-
- <variablelist>
- <varlistentry>
- <term><literal>host</literal></term>
- <listitem>
- <para>
- Name of host to connect to.<indexterm><primary>host name</></>
- If this begins with a slash, it specifies Unix-domain
- communication rather than TCP/IP communication; the value is the
- name of the directory in which the socket file is stored. The
- default behavior when <literal>host</literal> is not specified
- is to connect to a Unix-domain
- socket<indexterm><primary>Unix domain socket</></> in
- <filename>/tmp</filename> (or whatever socket directory was specified
- when <productname>PostgreSQL</> was built). On machines without
- Unix-domain sockets, the default is to connect to <literal>localhost</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>hostaddr</literal></term>
- <listitem>
- <para>
- Numeric IP address of host to connect to. This should be in the
- standard IPv4 address format, e.g., <literal>172.28.40.9</>. If
- your machine supports IPv6, you can also use those addresses.
- TCP/IP communication is
- always used when a nonempty string is specified for this parameter.
- </para>
- <para>
- Using <literal>hostaddr</> instead of <literal>host</> allows the
- application to avoid a host name look-up, which might be important in
- applications with time constraints. However, Kerberos and GSSAPI authentication
- requires the host name. The following therefore applies: If
- <literal>host</> is specified without <literal>hostaddr</>, a host name
- lookup occurs. If <literal>hostaddr</> is specified without
- <literal>host</>, the value for <literal>hostaddr</> gives the remote
- address. When Kerberos is used, a reverse name query occurs to obtain
- the host name for Kerberos. If both
- <literal>host</> and <literal>hostaddr</> are specified, the value for
- <literal>hostaddr</> gives the remote address; the value for
- <literal>host</> is ignored, unless Kerberos is used, in which case that
- value is used for Kerberos authentication. (Note that authentication is
- likely to fail if <application>libpq</application> is passed a host name
- that is not the name of the machine at <literal>hostaddr</>.) Also,
- <literal>host</> rather than <literal>hostaddr</> is used to identify
- the connection in <filename>~/.pgpass</> (see
- <xref linkend="libpq-pgpass">).
- </para>
- <para>
- Without either a host name or host address,
- <application>libpq</application> will connect using a
- local Unix-domain socket; or on machines without Unix-domain
- sockets, it will attempt to connect to <literal>localhost</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>port</literal></term>
- <listitem>
- <para>
- Port number to connect to at the server host, or socket file
- name extension for Unix-domain
- connections.<indexterm><primary>port</></>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>dbname</literal></term>
- <listitem>
- <para>
- The database name. Defaults to be the same as the user name.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>user</literal></term>
- <listitem>
- <para>
- <productname>PostgreSQL</productname> user name to connect as.
- Defaults to be the same as the operating system name of the user
- running the application.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>password</literal></term>
- <listitem>
- <para>
- Password to be used if the server demands password authentication.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>connect_timeout</literal></term>
- <listitem>
- <para>
- Maximum wait for connection, in seconds (write as a decimal integer
- string). Zero or not specified means wait indefinitely. It is not
- recommended to use a timeout of less than 2 seconds.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>options</literal></term>
- <listitem>
- <para>
- Command-line options to be sent to the server.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>tty</literal></term>
- <listitem>
- <para>
- Ignored (formerly, this specified where to send server debug output).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>sslmode</literal></term>
- <listitem>
- <para>
- This option determines whether or with what priority an
- <acronym>SSL</> connection will be negotiated with the
- server. There are four modes: <literal>disable</> will attempt
- only an unencrypted <acronym>SSL</> connection;
- <literal>allow</> will negotiate, trying first a
- non-<acronym>SSL</> connection, then if that fails, trying an
- <acronym>SSL</> connection; <literal>prefer</> (the default)
- will negotiate, trying first an <acronym>SSL</> connection,
- then if that fails, trying a regular non-<acronym>SSL</>
- connection; <literal>require</> will try only an
- <acronym>SSL</> connection.
- </para>
-
+ <para>
+ This function opens a new database connection using the parameters taken
+ from the string <literal>conninfo</literal>. Unlike <function>PQsetdbLogin</> below,
+ the parameter set can be extended without changing the function signature,
+ so use of this function (or its nonblocking analogues <function>PQconnectStart</>
+ and <function>PQconnectPoll</function>) is preferred for new application programming.
+ </para>
+
+ <para>
+ The passed string
+ can be empty to use all default parameters, or it can contain one or more
+ parameter settings separated by whitespace.
+ Each parameter setting is in the form <literal>keyword = value</literal>.
+ Spaces around the equal sign are optional.
+ To write an empty value or a value containing
+ spaces, surround it with single quotes, e.g.,
+ <literal>keyword = 'a value'</literal>.
+ Single quotes and backslashes within the value must be escaped with a
+ backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
+ </para>
+
+ <para>
+ The currently recognized parameter key words are:
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>host</literal></term>
+ <listitem>
+ <para>
+ Name of host to connect to.<indexterm><primary>host name</></>
+ If this begins with a slash, it specifies Unix-domain
+ communication rather than TCP/IP communication; the value is the
+ name of the directory in which the socket file is stored. The
+ default behavior when <literal>host</literal> is not specified
+ is to connect to a Unix-domain
+ socket<indexterm><primary>Unix domain socket</></> in
+ <filename>/tmp</filename> (or whatever socket directory was specified
+ when <productname>PostgreSQL</> was built). On machines without
+ Unix-domain sockets, the default is to connect to <literal>localhost</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>hostaddr</literal></term>
+ <listitem>
+ <para>
+ Numeric IP address of host to connect to. This should be in the
+ standard IPv4 address format, e.g., <literal>172.28.40.9</>. If
+ your machine supports IPv6, you can also use those addresses.
+ TCP/IP communication is
+ always used when a nonempty string is specified for this parameter.
+ </para>
+
+ <para>
+ Using <literal>hostaddr</> instead of <literal>host</> allows the
+ application to avoid a host name look-up, which might be important in
+ applications with time constraints. However, Kerberos and GSSAPI authentication
+ requires the host name. The following therefore applies: If
+ <literal>host</> is specified without <literal>hostaddr</>, a host name
+ lookup occurs. If <literal>hostaddr</> is specified without
+ <literal>host</>, the value for <literal>hostaddr</> gives the remote
+ address. When Kerberos is used, a reverse name query occurs to obtain
+ the host name for Kerberos. If both
+ <literal>host</> and <literal>hostaddr</> are specified, the value for
+ <literal>hostaddr</> gives the remote address; the value for
+ <literal>host</> is ignored, unless Kerberos is used, in which case that
+ value is used for Kerberos authentication. (Note that authentication is
+ likely to fail if <application>libpq</application> is passed a host name
+ that is not the name of the machine at <literal>hostaddr</>.) Also,
+ <literal>host</> rather than <literal>hostaddr</> is used to identify
+ the connection in <filename>~/.pgpass</> (see
+ <xref linkend="libpq-pgpass">).
+ </para>
+
+ <para>
+ Without either a host name or host address,
+ <application>libpq</application> will connect using a
+ local Unix-domain socket; or on machines without Unix-domain
+ sockets, it will attempt to connect to <literal>localhost</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>port</literal></term>
+ <listitem>
+ <para>
+ Port number to connect to at the server host, or socket file
+ name extension for Unix-domain
+ connections.<indexterm><primary>port</></>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>dbname</literal></term>
+ <listitem>
<para>
- If <productname>PostgreSQL</> is compiled without SSL support,
- using option <literal>require</> will cause an error, while
- options <literal>allow</> and <literal>prefer</> will be
- accepted but <application>libpq</> will not in fact attempt
- an <acronym>SSL</>
- connection.<indexterm><primary>SSL</><secondary
- sortas="libpq">with libpq</></indexterm>
+ The database name. Defaults to be the same as the user name.
</para>
- </listitem>
- </varlistentry>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term><literal>requiressl</literal></term>
- <listitem>
+ <varlistentry>
+ <term><literal>user</literal></term>
+ <listitem>
<para>
- This option is deprecated in favor of the <literal>sslmode</>
- setting.
+ <productname>PostgreSQL</productname> user name to connect as.
+ Defaults to be the same as the operating system name of the user
+ running the application.
</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>password</literal></term>
+ <listitem>
<para>
- If set to 1, an <acronym>SSL</acronym> connection to the server
- is required (this is equivalent to <literal>sslmode</>
- <literal>require</>). <application>libpq</> will then refuse
- to connect if the server does not accept an
- <acronym>SSL</acronym> connection. If set to 0 (default),
- <application>libpq</> will negotiate the connection type with
- the server (equivalent to <literal>sslmode</>
- <literal>prefer</>). This option is only available if
- <productname>PostgreSQL</> is compiled with SSL support.
+ Password to be used if the server demands password authentication.
</para>
- </listitem>
- </varlistentry>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term><literal>krbsrvname</literal></term>
- <listitem>
+ <varlistentry>
+ <term><literal>connect_timeout</literal></term>
+ <listitem>
<para>
- Kerberos service name to use when authenticating with Kerberos 5
- or GSSAPI.
- This must match the service name specified in the server
- configuration for Kerberos authentication to succeed. (See also
- <xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.)
+ Maximum wait for connection, in seconds (write as a decimal integer
+ string). Zero or not specified means wait indefinitely. It is not
+ recommended to use a timeout of less than 2 seconds.
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>gsslib</literal></term>
- <listitem>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>options</literal></term>
+ <listitem>
+ <para>
+ Command-line options to be sent to the server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>tty</literal></term>
+ <listitem>
<para>
- GSS library to use for GSSAPI authentication. Only used on Windows.
- Set to <literal>gssapi</literal> to force libpq to use the GSSAPI
- library for authentication instead of the default SSPI.
+ Ignored (formerly, this specified where to send server debug output).
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>service</literal></term>
- <listitem>
- <para>
- Service name to use for additional parameters. It specifies a service
- name in <filename>pg_service.conf</filename> that holds additional connection parameters.
- This allows applications to specify only a service name so connection parameters
- can be centrally maintained. See <xref linkend="libpq-pgservice">.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- If any parameter is unspecified, then the corresponding
- environment variable (see <xref linkend="libpq-envars">)
- is checked. If the environment variable is not set either,
- then the indicated built-in defaults are used.
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>sslmode</literal></term>
+ <listitem>
+ <para>
+ This option determines whether or with what priority an
+ <acronym>SSL</> connection will be negotiated with the
+ server. There are four modes: <literal>disable</> will attempt
+ only an unencrypted <acronym>SSL</> connection;
+ <literal>allow</> will negotiate, trying first a
+ non-<acronym>SSL</> connection, then if that fails, trying an
+ <acronym>SSL</> connection; <literal>prefer</> (the default)
+ will negotiate, trying first an <acronym>SSL</> connection,
+ then if that fails, trying a regular non-<acronym>SSL</>
+ connection; <literal>require</> will try only an
+ <acronym>SSL</> connection.
+ </para>
+
+ <para>
+ If <productname>PostgreSQL</> is compiled without SSL support,
+ using option <literal>require</> will cause an error, while
+ options <literal>allow</> and <literal>prefer</> will be
+ accepted but <application>libpq</> will not in fact attempt
+ an <acronym>SSL</>
+ connection.<indexterm><primary>SSL</><secondary
+ sortas="libpq">with libpq</></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>requiressl</literal></term>
+ <listitem>
+ <para>
+ This option is deprecated in favor of the <literal>sslmode</>
+ setting.
+ </para>
+
+ <para>
+ If set to 1, an <acronym>SSL</acronym> connection to the server
+ is required (this is equivalent to <literal>sslmode</>
+ <literal>require</>). <application>libpq</> will then refuse
+ to connect if the server does not accept an
+ <acronym>SSL</acronym> connection. If set to 0 (default),
+ <application>libpq</> will negotiate the connection type with
+ the server (equivalent to <literal>sslmode</>
+ <literal>prefer</>). This option is only available if
+ <productname>PostgreSQL</> is compiled with SSL support.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>krbsrvname</literal></term>
+ <listitem>
+ <para>
+ Kerberos service name to use when authenticating with Kerberos 5
+ or GSSAPI.
+ This must match the service name specified in the server
+ configuration for Kerberos authentication to succeed. (See also
+ <xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>gsslib</literal></term>
+ <listitem>
+ <para>
+ GSS library to use for GSSAPI authentication. Only used on Windows.
+ Set to <literal>gssapi</literal> to force libpq to use the GSSAPI
+ library for authentication instead of the default SSPI.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>service</literal></term>
+ <listitem>
+ <para>
+ Service name to use for additional parameters. It specifies a service
+ name in <filename>pg_service.conf</filename> that holds additional connection parameters.
+ This allows applications to specify only a service name so connection parameters
+ can be centrally maintained. See <xref linkend="libpq-pgservice">.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ If any parameter is unspecified, then the corresponding
+ environment variable (see <xref linkend="libpq-envars">)
+ is checked. If the environment variable is not set either,
+ then the indicated built-in defaults are used.
</para>
</listitem>
</varlistentry>
<term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</></></term>
<term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</></></term>
<listitem>
- <para>
- <indexterm><primary>nonblocking connection</primary></indexterm>
- Make a connection to the database server in a nonblocking manner.
-
- <synopsis>
- PGconn *PQconnectStart(const char *conninfo);
- </synopsis>
-
- <synopsis>
- PostgresPollingStatusType PQconnectPoll(PGconn *conn);
- </synopsis>
- </para>
-
- <para>
- These two functions are used to open a connection to a database server such
- that your application's thread of execution is not blocked on remote I/O
- whilst doing so.
- The point of this approach is that the waits for I/O to complete can occur
- in the application's main loop, rather than down inside
- <function>PQconnectdb</>, and so the application can manage this
- operation in parallel with other activities.
- </para>
-
- <para>
- The database connection is made using the parameters taken from the string
- <literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
- the same format as described above for <function>PQconnectdb</function>.
- </para>
- <para>
- Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
- restrictions are met:
- <itemizedlist>
- <listitem>
- <para>
- The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
- name and reverse name queries are not made. See the documentation of
- these parameters under <function>PQconnectdb</function> above for details.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you call <function>PQtrace</function>, ensure that the stream object
- into which you trace will not block.
- </para>
- </listitem>
-
- <listitem>
- <para>
- You ensure that the socket is in the appropriate state
- before calling <function>PQconnectPoll</function>, as described below.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
- If <varname>conn</varname> is null, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
- structure. Otherwise, a valid <structname>PGconn</> pointer is returned (though not yet
- representing a valid connection to the database). On return from
- <function>PQconnectStart</function>, call <literal>status = PQstatus(conn)</literal>. If <varname>status</varname> equals
- <symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
- </para>
-
- <para>
- If <function>PQconnectStart</> succeeds, the next stage is to poll
- <application>libpq</> so that it can proceed with the connection sequence.
- Use <function>PQsocket(conn)</function> to obtain the descriptor of the
- socket underlying the database connection.
- Loop thus: If <function>PQconnectPoll(conn)</function> last returned
- <symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to
- read (as indicated by <function>select()</>, <function>poll()</>, or
- similar system function).
- Then call <function>PQconnectPoll(conn)</function> again.
- Conversely, if <function>PQconnectPoll(conn)</function> last returned
- <symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready
- to write, then call <function>PQconnectPoll(conn)</function> again.
- If you have yet to call
- <function>PQconnectPoll</function>, i.e., just after the call to
- <function>PQconnectStart</function>, behave as if it last returned
- <symbol>PGRES_POLLING_WRITING</symbol>. Continue this loop until
- <function>PQconnectPoll(conn)</function> returns
- <symbol>PGRES_POLLING_FAILED</symbol>, indicating the connection procedure
- has failed, or <symbol>PGRES_POLLING_OK</symbol>, indicating the connection
- has been successfully made.
- </para>
-
- <para>
- At any time during connection, the status of the connection can be
- checked by calling <function>PQstatus</>. If this gives <symbol>CONNECTION_BAD</>, then the
- connection procedure has failed; if it gives <function>CONNECTION_OK</>, then the
- connection is ready. Both of these states are equally detectable
- from the return value of <function>PQconnectPoll</>, described above. Other states might also occur
- during (and only during) an asynchronous connection procedure. These
- indicate the current stage of the connection procedure and might be useful
- to provide feedback to the user for example. These statuses are:
-
- <variablelist>
- <varlistentry>
- <term><symbol>CONNECTION_STARTED</symbol></term>
- <listitem>
- <para>
- Waiting for connection to be made.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>CONNECTION_MADE</symbol></term>
- <listitem>
- <para>
- Connection OK; waiting to send.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
- <listitem>
- <para>
- Waiting for a response from the server.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>CONNECTION_AUTH_OK</symbol></term>
+ <para>
+ <indexterm><primary>nonblocking connection</primary></indexterm>
+ Make a connection to the database server in a nonblocking manner.
+
+ <synopsis>
+ PGconn *PQconnectStart(const char *conninfo);
+ </synopsis>
+
+ <synopsis>
+ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
+ </synopsis>
+ </para>
+
+ <para>
+ These two functions are used to open a connection to a database server such
+ that your application's thread of execution is not blocked on remote I/O
+ whilst doing so.
+ The point of this approach is that the waits for I/O to complete can occur
+ in the application's main loop, rather than down inside
+ <function>PQconnectdb</>, and so the application can manage this
+ operation in parallel with other activities.
+ </para>
+
+ <para>
+ The database connection is made using the parameters taken from the string
+ <literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
+ the same format as described above for <function>PQconnectdb</function>.
+ </para>
+ <para>
+ Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
+ restrictions are met:
+ <itemizedlist>
<listitem>
<para>
- Received authentication; waiting for backend start-up to finish.
+ The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
+ name and reverse name queries are not made. See the documentation of
+ these parameters under <function>PQconnectdb</function> above for details.
</para>
</listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
+
<listitem>
<para>
- Negotiating SSL encryption.
+ If you call <function>PQtrace</function>, ensure that the stream object
+ into which you trace will not block.
</para>
</listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>CONNECTION_SETENV</symbol></term>
+
<listitem>
<para>
- Negotiating environment-driven parameter settings.
+ You ensure that the socket is in the appropriate state
+ before calling <function>PQconnectPoll</function>, as described below.
</para>
</listitem>
- </varlistentry>
- </variablelist>
-
- Note that, although these constants will remain (in order to maintain
- compatibility), an application should never rely upon these occurring in a
- particular order, or at all, or on the status always being one of these
- documented values. An application might do something like this:
+ </itemizedlist>
+ </para>
+
+ <para>
+ To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
+ If <varname>conn</varname> is null, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
+ structure. Otherwise, a valid <structname>PGconn</> pointer is returned (though not yet
+ representing a valid connection to the database). On return from
+ <function>PQconnectStart</function>, call <literal>status = PQstatus(conn)</literal>. If <varname>status</varname> equals
+ <symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
+ </para>
+
+ <para>
+ If <function>PQconnectStart</> succeeds, the next stage is to poll
+ <application>libpq</> so that it can proceed with the connection sequence.
+ Use <function>PQsocket(conn)</function> to obtain the descriptor of the
+ socket underlying the database connection.
+ Loop thus: If <function>PQconnectPoll(conn)</function> last returned
+ <symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to
+ read (as indicated by <function>select()</>, <function>poll()</>, or
+ similar system function).
+ Then call <function>PQconnectPoll(conn)</function> again.
+ Conversely, if <function>PQconnectPoll(conn)</function> last returned
+ <symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready
+ to write, then call <function>PQconnectPoll(conn)</function> again.
+ If you have yet to call
+ <function>PQconnectPoll</function>, i.e., just after the call to
+ <function>PQconnectStart</function>, behave as if it last returned
+ <symbol>PGRES_POLLING_WRITING</symbol>. Continue this loop until
+ <function>PQconnectPoll(conn)</function> returns
+ <symbol>PGRES_POLLING_FAILED</symbol>, indicating the connection procedure
+ has failed, or <symbol>PGRES_POLLING_OK</symbol>, indicating the connection
+ has been successfully made.
+ </para>
+
+ <para>
+ At any time during connection, the status of the connection can be
+ checked by calling <function>PQstatus</>. If this gives <symbol>CONNECTION_BAD</>, then the
+ connection procedure has failed; if it gives <function>CONNECTION_OK</>, then the
+ connection is ready. Both of these states are equally detectable
+ from the return value of <function>PQconnectPoll</>, described above. Other states might also occur
+ during (and only during) an asynchronous connection procedure. These
+ indicate the current stage of the connection procedure and might be useful
+ to provide feedback to the user for example. These statuses are:
+
+ <variablelist>
+ <varlistentry>
+ <term><symbol>CONNECTION_STARTED</symbol></term>
+ <listitem>
+ <para>
+ Waiting for connection to be made.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_MADE</symbol></term>
+ <listitem>
+ <para>
+ Connection OK; waiting to send.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
+ <listitem>
+ <para>
+ Waiting for a response from the server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_AUTH_OK</symbol></term>
+ <listitem>
+ <para>
+ Received authentication; waiting for backend start-up to finish.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
+ <listitem>
+ <para>
+ Negotiating SSL encryption.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_SETENV</symbol></term>
+ <listitem>
+ <para>
+ Negotiating environment-driven parameter settings.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ Note that, although these constants will remain (in order to maintain
+ compatibility), an application should never rely upon these occurring in a
+ particular order, or at all, or on the status always being one of these
+ documented values. An application might do something like this:
<programlisting>
switch(PQstatus(conn))
{
feedback = "Connecting...";
}
</programlisting>
- </para>
-
- <para>
- The <literal>connect_timeout</literal> connection parameter is ignored
- when using <function>PQconnectPoll</function>; it is the application's
- responsibility to decide whether an excessive amount of time has elapsed.
- Otherwise, <function>PQconnectStart</function> followed by a
- <function>PQconnectPoll</function> loop is equivalent to
- <function>PQconnectdb</function>.
- </para>
-
- <para>
- Note that if <function>PQconnectStart</function> returns a non-null pointer, you must call
- <function>PQfinish</function> when you are finished with it, in order to dispose of
- the structure and any associated memory blocks. This must be done even if
- the connection attempt fails or is abandoned.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></term>
- <listitem>
- <para>
- Returns the default connection options.
+ </para>
+
+ The <literal>connect_timeout</literal> connection parameter is ignored
+ when using <function>PQconnectPoll</function>; it is the application's
+ responsibility to decide whether an excessive amount of time has elapsed.
+ Otherwise, <function>PQconnectStart</function> followed by a
+ <function>PQconnectPoll</function> loop is equivalent to
+ <function>PQconnectdb</function>.
+ </para>
+
+ Note that if <function>PQconnectStart</function> returns a non-null pointer, you must call
+ <function>PQfinish</function> when you are finished with it, in order to dispose of
+ the structure and any associated memory blocks. This must be done even if
+ the connection attempt fails or is abandoned.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+
<term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></term>
+ <listitem>
+ Returns the default connection options.
<synopsis>
PQconninfoOption *PQconndefaults(void);
int dispsize; /* Field size in characters for dialog */
} PQconninfoOption;
</synopsis>
- </para>
-
- <para>
- Returns a connection options array. This can be used to determine
- all possible <function>PQconnectdb</function> options and their
- current default values. The return value points to an array of
- <structname>PQconninfoOption</structname> structures, which ends
- with an entry having a null <structfield>keyword</> pointer. The
- null pointer is returned if memory could not be allocated. Note that
- the current default values (<structfield>val</structfield> fields)
- will depend on environment variables and other context. Callers
- must treat the connection options data as read-only.
- </para>
-
- <para>
- After processing the options array, free it by passing it to
- <function>PQconninfoFree</function>. If this is not done, a small amount of memory
- is leaked for each call to <function>PQconndefaults</function>.
- </para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><function>PQfinish</function><indexterm><primary>PQfinish</></></term>
- <listitem>
- <para>
- Closes the connection to the server. Also frees
- memory used by the <structname>PGconn</structname> object.
- <synopsis>
- void PQfinish(PGconn *conn);
- </synopsis>
- </para>
-
- <para>
- Note that even if the server connection attempt fails (as
- indicated by <function>PQstatus</function>), the application should call <function>PQfinish</function>
- to free the memory used by the <structname>PGconn</structname> object.
- The <structname>PGconn</> pointer must not be used again after
- <function>PQfinish</function> has been called.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><function>PQreset</function><indexterm><primary>PQreset</></></term>
- <listitem>
- <para>
- Resets the communication channel to the server.
- <synopsis>
- void PQreset(PGconn *conn);
- </synopsis>
- </para>
-
- <para>
- This function will close the connection
- to the server and attempt to reestablish a new
- connection to the same server, using all the same
- parameters previously used. This might be useful for
- error recovery if a working connection is lost.
+ </para>
+
+ Returns a connection options array. This can be used to determine
+ all possible <function>PQconnectdb</function> options and their
+ current default values. The return value points to an array of
+ <structname>PQconninfoOption</structname> structures, which ends
+ with an entry having a null <structfield>keyword</> pointer. The
+ null pointer is returned if memory could not be allocated. Note that
+ the current default values (<structfield>val</structfield> fields)
+ will depend on environment variables and other context. Callers
+ must treat the connection options data as read-only.
+ </para>
+
+ After processing the options array, free it by passing it to
+ <function>PQconninfoFree</function>. If this is not done, a small amount of memory
+ is leaked for each call to <function>PQconndefaults</function>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+
<term><function>PQfinish</function><indexterm><primary>PQfinish</></></term>
+ <listitem>
+ Closes the connection to the server. Also frees
+ memory used by the <structname>PGconn</structname> object.
+ <synopsis>
+ void PQfinish(PGconn *conn);
+ </synopsis>
+ </para>
+
+ Note that even if the server connection attempt fails (as
+ indicated by <function>PQstatus</function>), the application should call <function>PQfinish</function>
+ to free the memory used by the <structname>PGconn</structname> object.
+ The <structname>PGconn</> pointer must not be used again after
+ <function>PQfinish</function> has been called.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+
<term><function>PQreset</function><indexterm><primary>PQreset</></></term>
+ <listitem>
+ Resets the communication channel to the server.
+ <synopsis>
+ void PQreset(PGconn *conn);
+ </synopsis>
+ </para>
+
+ This function will close the connection
+ to the server and attempt to reestablish a new
+ connection to the same server, using all the same
+ parameters previously used. This might be useful for
+ error recovery if a working connection is lost.
</para>
</listitem>
</varlistentry>
<application>libpq</application> application programmers should be careful to
maintain the <structname>PGconn</structname> abstraction. Use the accessor
functions described below to get at the contents of <structname>PGconn</structname>.
- Reference to internal <structname>PGconn</structname> fields using
+ Reference to internal <structname>PGconn</structname> fields using
<filename>libpq-int.h</> is not recommended because they are subject to change
in the future.
</para>
- </tip>
-
- <para>
- The following functions return parameter values established at connection.
- These values are fixed for the life of the <structname>PGconn</> object.
+ </tip>
- <variablelist>
- <varlistentry>
- <term>
- <function>PQdb</function>
- <indexterm>
- <primary>PQdb</primary>
- </indexterm>
- </term>
+ <para>
+ The following functions return parameter values established at connection.
+ These values are fixed for the life of the <structname>PGconn</> object.
- <listitem>
- <para>
- Returns the database name of the connection.
- <synopsis>
- char *PQdb(const PGconn *conn);
- </synopsis>
- </para>
- </listitem>
- </varlistentry>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQdb</function>
+ <indexterm>
+ <primary>PQdb</primary>
+ </indexterm>
+ </term>
- <varlistentry>
- <term>
- <function>PQuser</function>
- <indexterm>
- <primary>PQuser</primary>
- </indexterm>
- </term>
+ <listitem>
+ <para>
+ Returns the database name of the connection.
+ <synopsis>
+ char *PQdb(const PGconn *conn);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>
- Returns the user name of the connection.
- <synopsis>
- char *PQuser(const PGconn *conn);
- </synopsis>
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>
+ <function>PQuser</function>
+ <indexterm>
+ <primary>PQuser</primary>
+ </indexterm>
+ </term>
- <varlistentry>
- <term>
- <function>PQpass</function>
- <indexterm>
- <primary>PQpass</primary>
- </indexterm>
- </term>
+ <listitem>
+ <para>
+ Returns the user name of the connection.
+ <synopsis>
+ char *PQuser(const PGconn *conn);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>
- Returns the password of the connection.
- <synopsis>
- char *PQpass(const PGconn *conn);
- </synopsis>
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>
+ <function>PQpass</function>
+ <indexterm>
+ <primary>PQpass</primary>
+ </indexterm>
+ </term>
- <varlistentry>
- <term>
- <function>PQhost</function>
- <indexterm>
- <primary>PQhost</primary>
- </indexterm>
- </term>
+ <listitem>
+ <para>
+ Returns the password of the connection.
+ <synopsis>
+ char *PQpass(const PGconn *conn);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>
- Returns the server host name of the connection.
- <synopsis>
- char *PQhost(const PGconn *conn);
- </synopsis>
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>
+ <function>PQhost</function>
+ <indexterm>
+ <primary>PQhost</primary>
+ </indexterm>
+ </term>
- <varlistentry>
+ <listitem>
+ <para>
+ Returns the server host name of the connection.
+ <synopsis>
+ char *PQhost(const PGconn *conn);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>
<function>PQport</function>
<indexterm>
<listitem>
<para>
- Returns the status of the connection.
+ Returns the status of the connection.
<synopsis>
ConnStatusType PQstatus(const PGconn *conn);
</synopsis>
<para>
<indexterm><primary>SSL</><secondary sortas="libpq">in libpq</secondary></indexterm>
Returns the SSL structure used in the connection, or null
- if SSL is not in use.
+ if SSL is not in use.
<synopsis>
SSL *PQgetssl(const PGconn *conn);
<para>
You must define <symbol>USE_SSL</symbol> in order to get the
- correct prototype for this function. Doing this will also
+ correct prototype for this function. Doing this will also
automatically include <filename>ssl.h</filename> from <productname>OpenSSL</productname>.
</para>
</listitem>
connections; it will fail when using protocol 2.0.
</para>
- <para>
- The function creates a prepared statement named
- <parameter>stmtName</> from the <parameter>query</> string, which
- must contain a single SQL command. <parameter>stmtName</> can be
- <literal>""</> 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 <literal>$1</>, <literal>$2</>, etc.
- <parameter>nParams</> is the number of parameters for which types
- are pre-specified in the array <parameter>paramTypes[]</>. (The
- array pointer can be <symbol>NULL</symbol> when
- <parameter>nParams</> is zero.) <parameter>paramTypes[]</>
- specifies, by OID, the data types to be assigned to the parameter
- symbols. If <parameter>paramTypes</> is <symbol>NULL</symbol>,
- 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 can use parameter
- symbols with numbers higher than <parameter>nParams</>; data types
- will be inferred for these symbols as well. (See
- <function>PQdescribePrepared</function> for a means to find out
- what data types were inferred.)
- </para>
-
- <para>
- As with <function>PQexec</>, the result is normally a
- <structname>PGresult</structname> 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
- <function>PQerrorMessage</function> to get more information about
- such errors.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- Prepared statements for use with <function>PQexecPrepared</> can also
- be created by executing SQL <xref linkend="sql-prepare"
- endterm="sql-prepare-title"> statements. (But <function>PQprepare</>
- is more flexible since it does not require parameter types to be
- pre-specified.) Also, although there is no <application>libpq</>
- function for deleting a prepared statement, the SQL <xref
- linkend="sql-deallocate" endterm="sql-deallocate-title"> statement
- can be used for that purpose.
- </para>
+ <para>
+ The function creates a prepared statement named
+ <parameter>stmtName</> from the <parameter>query</> string, which
+ must contain a single SQL command. <parameter>stmtName</> can be
+ <literal>""</> 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 <literal>$1</>, <literal>$2</>, etc.
+ <parameter>nParams</> is the number of parameters for which types
+ are pre-specified in the array <parameter>paramTypes[]</>. (The
+ array pointer can be <symbol>NULL</symbol> when
+ <parameter>nParams</> is zero.) <parameter>paramTypes[]</>
+ specifies, by OID, the data types to be assigned to the parameter
+ symbols. If <parameter>paramTypes</> is <symbol>NULL</symbol>,
+ 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 can use parameter
+ symbols with numbers higher than <parameter>nParams</>; data types
+ will be inferred for these symbols as well. (See
+ <function>PQdescribePrepared</function> for a means to find out
+ what data types were inferred.)
+ </para>
- <para>
- <variablelist>
- <varlistentry>
- <term>
- <function>PQexecPrepared</function>
- <indexterm>
- <primary>PQexecPrepared</primary>
- </indexterm>
- </term>
-
- <listitem>
- <para>
- Sends a request to execute a prepared statement with given
- parameters, and waits for the result.
+ <para>
+ As with <function>PQexec</>, the result is normally a
+ <structname>PGresult</structname> 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
+ <function>PQerrorMessage</function> to get more information about
+ such errors.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ Prepared statements for use with <function>PQexecPrepared</> can also
+ be created by executing SQL <xref linkend="sql-prepare"
+ endterm="sql-prepare-title"> statements. (But <function>PQprepare</>
+ is more flexible since it does not require parameter types to be
+ pre-specified.) Also, although there is no <application>libpq</>
+ function for deleting a prepared statement, the SQL <xref
+ linkend="sql-deallocate" endterm="sql-deallocate-title"> statement
+ can be used for that purpose.
+ </para>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQexecPrepared</function>
+ <indexterm>
+ <primary>PQexecPrepared</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Sends a request to execute a prepared statement with given
+ parameters, and waits for the result.
<synopsis>
PGresult *PQexecPrepared(PGconn *conn,
const char *stmtName,
const int *paramFormats,
int resultFormat);
</synopsis>
- </para>
-
- <function>PQexecPrepared</> is like <function>PQexecParams</>,
- 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. <function>PQexecPrepared</> is supported
- only in protocol 3.0 and later connections; it will fail when
- using protocol 2.0.
- </para>
-
- The parameters are identical to <function>PQexecParams</>, except that the
- name of a prepared statement is given instead of a query string, and the
-
<parameter>paramTypes[]</> parameter is not present (it is not needed since
- the prepared statement's parameter types were determined when it was created).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <function>PQdescribePrepared</function>
- <indexterm>
-
<primary>PQdescribePrepared</primary>
- </indexterm>
- </term>
-
- <listitem>
- Submits a request to obtain information about the specified
- prepared statement, and waits for completion.
+ </para>
+
+ <para>
+ <function>PQexecPrepared</> is like <function>PQexecParams</>,
+ 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. <function>PQexecPrepared</> is supported
+ only in protocol 3.0 and later connections; it will fail when
+ using protocol 2.0.
+ </para>
+
+ <para>
+ The parameters are identical to <function>PQexecParams</>, except that the
+ name of a prepared statement is given instead of a query string, and the
+ <parameter>paramTypes[]</> parameter is not present (it is not needed since
+ the prepared statement's parameter types were determined when it was created).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQdescribePrepared</function>
+ <indexterm>
+ <primary>PQdescribePrepared</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Submits a request to obtain information about the specified
+ prepared statement, and waits for completion.
<synopsis>
PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
</synopsis>
- </para>
-
- <function>PQdescribePrepared</> allows an application to obtain
- information about a previously prepared statement.
- <function>PQdescribePrepared</> is supported only in protocol 3.0
- and later connections; it will fail when using protocol 2.0.
- </para>
-
-
<parameter>stmtName</> can be <literal>""</> or NULL to reference
- the unnamed statement, otherwise it must be the name of an existing
- prepared statement. On success, a <structname>PGresult</> with
- status <literal>PGRES_COMMAND_OK</literal> is returned. The
- functions <function>PQnparams</function> and
- <function>PQparamtype</function> can be applied to this
- <structname>PGresult</> to obtain information about the parameters
- of the prepared statement, and the functions
- <function>PQnfields</function>, <function>PQfname</function>,
- <function>PQftype</function>, etc provide information about the
- result columns (if any) of the statement.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <function>PQdescribePortal</function>
- <indexterm>
-
<primary>PQdescribePortal</primary>
- </indexterm>
- </term>
-
- <listitem>
- Submits a request to obtain information about the specified
- portal, and waits for completion.
+ </para>
+
+ <para>
+ <function>PQdescribePrepared</> allows an application to obtain
+ information about a previously prepared statement.
+ <function>PQdescribePrepared</> is supported only in protocol 3.0
+ and later connections; it will fail when using protocol 2.0.
+ </para>
+
+ <para>
+ <parameter>stmtName</> can be <literal>""</> or NULL to reference
+ the unnamed statement, otherwise it must be the name of an existing
+ prepared statement. On success, a <structname>PGresult</> with
+ status <literal>PGRES_COMMAND_OK</literal> is returned. The
+ functions <function>PQnparams</function> and
+ <function>PQparamtype</function> can be applied to this
+ <structname>PGresult</> to obtain information about the parameters
+ of the prepared statement, and the functions
+ <function>PQnfields</function>, <function>PQfname</function>,
+ <function>PQftype</function>, etc provide information about the
+ result columns (if any) of the statement.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQdescribePortal</function>
+ <indexterm>
+ <primary>PQdescribePortal</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Submits a request to obtain information about the specified
+ portal, and waits for completion.
<synopsis>
PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
</synopsis>
- </para>
-
- <para>
- <function>PQdescribePortal</> allows an application to obtain
- information about a previously created portal.
- (<application>libpq</> does not provide any direct access to
- portals, but you can use this function to inspect the properties
- of a cursor created with a <command>DECLARE CURSOR</> SQL command.)
- <function>PQdescribePortal</> is supported only in protocol 3.0
- and later connections; it will fail when using protocol 2.0.
- </para>
-
- <para>
- <parameter>portalName</> can be <literal>""</> or NULL to reference
- the unnamed portal, otherwise it must be the name of an existing
- portal. On success, a <structname>PGresult</> with status
- <literal>PGRES_COMMAND_OK</literal> is returned. The functions
- <function>PQnfields</function>, <function>PQfname</function>,
- <function>PQftype</function>, etc can be applied to the
- <structname>PGresult</> to obtain information about the result
- columns (if any) of the portal.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ </para>
- <para>
- The <structname>PGresult</structname><indexterm><primary>PGresult</></>
- structure encapsulates the result returned by the server.
- <application>libpq</application> application programmers should be
- careful to maintain the <structname>PGresult</structname> abstraction.
- Use the accessor functions below to get at the contents of
- <structname>PGresult</structname>. Avoid directly referencing the
- fields of the <structname>PGresult</structname> structure because they
- are subject to change in the future.
-
- <variablelist>
- <varlistentry>
- <term>
- <function>PQresultStatus</function>
- <indexterm>
- <primary>PQresultStatus</primary>
- </indexterm>
- </term>
-
- <listitem>
- <para>
- Returns the result status of the command.
- <synopsis>
- ExecStatusType PQresultStatus(const PGresult *res);
- </synopsis>
- </para>
-
- <para>
- <function>PQresultStatus</function> can return one of the following values:
-
- <variablelist>
- <varlistentry>
- <term><literal>PGRES_EMPTY_QUERY</literal></term>
- <listitem>
- <para>
- The string sent to the server was empty.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>PGRES_COMMAND_OK</literal></term>
- <listitem>
- <para>
- Successful completion of a command returning no data.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>PGRES_TUPLES_OK</literal></term>
- <listitem>
- <para>
- Successful completion of a command returning data (such as
- a <command>SELECT</> or <command>SHOW</>).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>PGRES_COPY_OUT</literal></term>
- <listitem>
- <para>
- Copy Out (from server) data transfer started.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>PGRES_COPY_IN</literal></term>
- <listitem>
- <para>
- Copy In (to server) data transfer started.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>PGRES_BAD_RESPONSE</literal></term>
- <listitem>
- <para>
- The server's response was not understood.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>PGRES_NONFATAL_ERROR</literal></term>
- <listitem>
- <para>
- A nonfatal error (a notice or warning) occurred.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>PGRES_FATAL_ERROR</literal></term>
- <listitem>
- <para>
- A fatal error occurred.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- If the result status is <literal>PGRES_TUPLES_OK</literal>, then
- the functions described below can be used to retrieve the rows
- returned by the query. Note that a <command>SELECT</command>
- command that happens to retrieve zero rows still shows
- <literal>PGRES_TUPLES_OK</literal>.
- <literal>PGRES_COMMAND_OK</literal> is for commands that can never
- return rows (<command>INSERT</command>, <command>UPDATE</command>,
- etc.). A response of <literal>PGRES_EMPTY_QUERY</literal> might
- indicate a bug in the client software.
- </para>
-
- <para>
- A result of status <symbol>PGRES_NONFATAL_ERROR</symbol> will
- never be returned directly by <function>PQexec</function> or other
- query execution functions; results of this kind are instead passed
- to the notice processor (see <xref
- linkend="libpq-notice-processing">).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <function>PQresStatus</function>
- <indexterm>
- <primary>PQresStatus</primary>
- </indexterm>
- </term>
-
- <listitem>
- <para>
- Converts the enumerated type returned by
- <function>PQresultStatus</> into a string constant describing the
- status code. The caller should not free the result.
-
- <synopsis>
- char *PQresStatus(ExecStatusType status);
- </synopsis>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <function>PQresultErrorMessage</function>
- <indexterm>
- <primary>PQresultErrorMessage</primary>
- </indexterm>
- </term>
-
- <listitem>
- <para>
- Returns the error message associated with the command, or an empty string
- if there was no error.
- <synopsis>
- char *PQresultErrorMessage(const PGresult *res);
- </synopsis>
- 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 <structname>PGresult</> handle is
- passed to <function>PQclear</function>.
- </para>
-
- <para>
- Immediately following a <function>PQexec</function> or
- <function>PQgetResult</function> call,
- <function>PQerrorMessage</function> (on the connection) will return
- the same string as <function>PQresultErrorMessage</function> (on
- the result). However, a <structname>PGresult</structname> will
- retain its error message until destroyed, whereas the connection's
- error message will change when subsequent operations are done.
- Use <function>PQresultErrorMessage</function> when you want to
- know the status associated with a particular
- <structname>PGresult</structname>; use
- <function>PQerrorMessage</function> when you want to know the
- status from the latest operation on the connection.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><function>PQresultErrorField</function><indexterm><primary>PQresultErrorField</></></term>
- <listitem>
- <para>
- Returns an individual field of an error report.
- <synopsis>
- char *PQresultErrorField(const PGresult *res, int fieldcode);
- </synopsis>
- <parameter>fieldcode</> is an error field identifier; see the symbols
- listed below. <symbol>NULL</symbol> is returned if the
- <structname>PGresult</structname> 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 <structname>PGresult</> handle is passed to
- <function>PQclear</function>.
- </para>
-
- <para>
- The following field codes are available:
- <variablelist>
- <varlistentry>
- <term><symbol>PG_DIAG_SEVERITY</></term>
- <listitem>
- <para>
- The severity; the field contents are <literal>ERROR</>,
- <literal>FATAL</>, or <literal>PANIC</> (in an error message),
- or <literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>,
- <literal>INFO</>, or <literal>LOG</> (in a notice message), or
- a localized translation of one of these. Always present.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <indexterm>
- <primary>error codes</primary>
- <secondary>libpq</secondary>
- </indexterm>
- <term><symbol>PG_DIAG_SQLSTATE</></term>
- <listitem>
- <para>
- 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 <xref
- linkend="errcodes-appendix">. This field is not localizable,
- and is always present.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>PG_DIAG_MESSAGE_PRIMARY</></term>
- <listitem>
- <para>
- The primary human-readable error message (typically one line).
- Always present.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>PG_DIAG_MESSAGE_DETAIL</></term>
- <listitem>
- <para>
- Detail: an optional secondary error message carrying more
- detail about the problem. Might run to multiple lines.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>PG_DIAG_MESSAGE_HINT</></term>
- <listitem>
- <para>
- 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. Might
- run to multiple lines.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>PG_DIAG_STATEMENT_POSITION</></term>
- <listitem>
+ <para>
+ <function>PQdescribePortal</> allows an application to obtain
+ information about a previously created portal.
+ (<application>libpq</> does not provide any direct access to
+ portals, but you can use this function to inspect the properties
+ of a cursor created with a <command>DECLARE CURSOR</> SQL command.)
+ <function>PQdescribePortal</> is supported only in protocol 3.0
+ and later connections; it will fail when using protocol 2.0.
+ </para>
+
+ <para>
+ <parameter>portalName</> can be <literal>""</> or NULL to reference
+ the unnamed portal, otherwise it must be the name of an existing
+ portal. On success, a <structname>PGresult</> with status
+ <literal>PGRES_COMMAND_OK</literal> is returned. The functions
+ <function>PQnfields</function>, <function>PQfname</function>,
+ <function>PQftype</function>, etc can be applied to the
+ <structname>PGresult</> to obtain information about the result
+ columns (if any) of the portal.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ The <structname>PGresult</structname><indexterm><primary>PGresult</></>
+ structure encapsulates the result returned by the server.
+ <application>libpq</application> application programmers should be
+ careful to maintain the <structname>PGresult</structname> abstraction.
+ Use the accessor functions below to get at the contents of
+ <structname>PGresult</structname>. Avoid directly referencing the
+ fields of the <structname>PGresult</structname> structure because they
+ are subject to change in the future.
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQresultStatus</function>
+ <indexterm>
+ <primary>PQresultStatus</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns the result status of the command.
+ <synopsis>
+ ExecStatusType PQresultStatus(const PGresult *res);
+ </synopsis>
+ </para>
+
+ <para>
+ <function>PQresultStatus</function> can return one of the following values:
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>PGRES_EMPTY_QUERY</literal></term>
+ <listitem>
+ <para>
+ The string sent to the server was empty.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGRES_COMMAND_OK</literal></term>
+ <listitem>
+ <para>
+ Successful completion of a command returning no data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGRES_TUPLES_OK</literal></term>
+ <listitem>
+ <para>
+ Successful completion of a command returning data (such as
+ a <command>SELECT</> or <command>SHOW</>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGRES_COPY_OUT</literal></term>
+ <listitem>
+ <para>
+ Copy Out (from server) data transfer started.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGRES_COPY_IN</literal></term>
+ <listitem>
+ <para>
+ Copy In (to server) data transfer started.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGRES_BAD_RESPONSE</literal></term>
+ <listitem>
+ <para>
+ The server's response was not understood.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGRES_NONFATAL_ERROR</literal></term>
+ <listitem>
+ <para>
+ A nonfatal error (a notice or warning) occurred.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGRES_FATAL_ERROR</literal></term>
+ <listitem>
+ <para>
+ A fatal error occurred.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ If the result status is <literal>PGRES_TUPLES_OK</literal>, then
+ the functions described below can be used to retrieve the rows
+ returned by the query. Note that a <command>SELECT</command>
+ command that happens to retrieve zero rows still shows
+ <literal>PGRES_TUPLES_OK</literal>.
+ <literal>PGRES_COMMAND_OK</literal> is for commands that can never
+ return rows (<command>INSERT</command>, <command>UPDATE</command>,
+ etc.). A response of <literal>PGRES_EMPTY_QUERY</literal> might
+ indicate a bug in the client software.
+ </para>
+
+ <para>
+ A result of status <symbol>PGRES_NONFATAL_ERROR</symbol> will
+ never be returned directly by <function>PQexec</function> or other
+ query execution functions; results of this kind are instead passed
+ to the notice processor (see <xref
+ linkend="libpq-notice-processing">).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQresStatus</function>
+ <indexterm>
+ <primary>PQresStatus</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Converts the enumerated type returned by
+ <function>PQresultStatus</> into a string constant describing the
+ status code. The caller should not free the result.
+
+ <synopsis>
+ char *PQresStatus(ExecStatusType status);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQresultErrorMessage</function>
+ <indexterm>
+ <primary>PQresultErrorMessage</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns the error message associated with the command, or an empty string
+ if there was no error.
+ <synopsis>
+ char *PQresultErrorMessage(const PGresult *res);
+ </synopsis>
+ 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 <structname>PGresult</> handle is
+ passed to <function>PQclear</function>.
+ </para>
+
+ <para>
+ Immediately following a <function>PQexec</function> or
+ <function>PQgetResult</function> call,
+ <function>PQerrorMessage</function> (on the connection) will return
+ the same string as <function>PQresultErrorMessage</function> (on
+ the result). However, a <structname>PGresult</structname> will
+ retain its error message until destroyed, whereas the connection's
+ error message will change when subsequent operations are done.
+ Use <function>PQresultErrorMessage</function> when you want to
+ know the status associated with a particular
+ <structname>PGresult</structname>; use
+ <function>PQerrorMessage</function> when you want to know the
+ status from the latest operation on the connection.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>PQresultErrorField</function><indexterm><primary>PQresultErrorField</></></term>
+ <listitem>
+ <para>
+ Returns an individual field of an error report.
+ <synopsis>
+ char *PQresultErrorField(const PGresult *res, int fieldcode);
+ </synopsis>
+ <parameter>fieldcode</> is an error field identifier; see the symbols
+ listed below. <symbol>NULL</symbol> is returned if the
+ <structname>PGresult</structname> 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 <structname>PGresult</> handle is passed to
+ <function>PQclear</function>.
+ </para>
+
+ <para>
+ The following field codes are available:
+ <variablelist>
+ <varlistentry>
+ <term><symbol>PG_DIAG_SEVERITY</></term>
+ <listitem>
+ <para>
+ The severity; the field contents are <literal>ERROR</>,
+ <literal>FATAL</>, or <literal>PANIC</> (in an error message),
+ or <literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>,
+ <literal>INFO</>, or <literal>LOG</> (in a notice message), or
+ a localized translation of one of these. Always present.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <indexterm>
+ <primary>error codes</primary>
+ <secondary>libpq</secondary>
+ </indexterm>
+ <term><symbol>PG_DIAG_SQLSTATE</></term>
+ <listitem>
+ <para>
+ 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 <xref
+ linkend="errcodes-appendix">. This field is not localizable,
+ and is always present.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>PG_DIAG_MESSAGE_PRIMARY</></term>
+ <listitem>
+ <para>
+ The primary human-readable error message (typically one line).
+ Always present.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>PG_DIAG_MESSAGE_DETAIL</></term>
+ <listitem>
+ <para>
+ Detail: an optional secondary error message carrying more
+ detail about the problem. Might run to multiple lines.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>PG_DIAG_MESSAGE_HINT</></term>
+ <listitem>
+ <para>
+ 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. Might
+ run to multiple lines.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>PG_DIAG_STATEMENT_POSITION</></term>
+ <listitem>
<para>
A string containing a decimal integer indicating an error cursor
position as an index into the original statement string. The
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><symbol>PG_DIAG_INTERNAL_POSITION</></term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><symbol>PG_DIAG_INTERNAL_QUERY</></term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><symbol>PG_DIAG_CONTEXT</></term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><symbol>PG_DIAG_SOURCE_FILE</></term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><symbol>PG_DIAG_SOURCE_LINE</></term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><symbol>PG_DIAG_SOURCE_FUNCTION</></term>
<listitem>
</varlistentry>
</variablelist>
</para>
-
+
<para>
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.
</para>
-
+
<para>
Errors generated internally by <application>libpq</application> 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.
</para>
-
+
<para>
Note that error fields are only available from
<structname>PGresult</structname> objects, not
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><function>PQclear</function><indexterm><primary>PQclear</></></term>
<listitem>
void PQclear(PGresult *res);
</synopsis>
</para>
-
+
<para>
You can keep a <structname>PGresult</structname> object around for
as long as you need it; it does not go away when you issue a new
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQmakeEmptyPGresult</function>
PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
</synopsis>
</para>
-
+
<para>
This is <application>libpq</>'s internal function to allocate and
initialize an empty <structname>PGresult</structname> object. This
</variablelist>
</para>
</sect2>
-
+
<sect2 id="libpq-exec-select-info">
<title>Retrieving Query Result Information</title>
-
+
<para>
These functions are used to extract information from a
<structname>PGresult</structname> object that represents a successful
would provide, but it has zero rows. For objects with other status values,
these functions will act as though the result has zero rows and zero columns.
</para>
-
+
<variablelist>
<varlistentry>
<term>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQnfields</function>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQfname</function>
int column_number);
</synopsis>
</para>
-
+
<para>
<symbol>NULL</symbol> is returned if the column number is out of range.
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQfnumber</function>
const char *column_name);
</synopsis>
</para>
-
+
<para>
-1 is returned if the given name does not match any column.
</para>
-
+
<para>
The given name is treated like an identifier in an SQL command,
that is, it is downcased unless double-quoted. For example, given
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQftable</function>
int column_number);
</synopsis>
</para>
-
+
<para>
<literal>InvalidOid</> is returned if the column number is out of range,
or if the specified column is not a simple reference to a table column,
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQftablecol</function>
int column_number);
</synopsis>
</para>
-
+
<para>
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
int column_number);
</synopsis>
</para>
-
+
<para>
Format code zero indicates textual data representation, while format
code one indicates binary representation. (Other codes are reserved
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQftype</function>
int column_number);
</synopsis>
</para>
-
+
<para>
You can query the system table <literal>pg_type</literal> to
obtain the names and properties of the various data types. The
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQfmod</function>
int column_number);
</synopsis>
</para>
-
+
<para>
The interpretation of modifier values is type-specific; they
typically indicate precision or size limits. The value -1 is
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQfsize</function>
int column_number);
</synopsis>
</para>
-
+
<para>
<function>PQfsize</> returns the space allocated for this column
in a database row, in other words the size of the server's
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQbinaryTuples</function>
</term>
<listitem>
- <para>
- Returns 1 if the <structname>PGresult</> contains binary data
- and 0 if it contains text data.
- <synopsis>
- int PQbinaryTuples(const PGresult *res);
- </synopsis>
- </para>
-
- <para>
- This function is deprecated (except for its use in connection with
- <command>COPY</>), because it is possible for a single
- <structname>PGresult</> to contain text data in some columns and
- binary data in others. <function>PQfformat</> is preferred.
- <function>PQbinaryTuples</> returns 1 only if all columns of the
- result are binary (format 1).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <function>PQgetvalue</function>
- <indexterm>
- <primary>PQgetvalue</primary>
- </indexterm>
- </term>
+ <para>
+ Returns 1 if the <structname>PGresult</> contains binary data
+ and 0 if it contains text data.
+ <synopsis>
+ int PQbinaryTuples(const PGresult *res);
+ </synopsis>
+ </para>
- <listitem>
- <para>
- Returns a single field value of one row of a
- <structname>PGresult</structname>. Row and column numbers start
- at 0. The caller should not free the result directly. It will
- be freed when the associated <structname>PGresult</> handle is
- passed to <function>PQclear</function>.
- <synopsis>
- char *PQgetvalue(const PGresult *res,
- int row_number,
- int column_number);
- </synopsis>
- </para>
-
- <para>
- For data in text format, the value returned by
- <function>PQgetvalue</function> 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 <function>typsend</> and <function>typreceive</>
- 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.)
- </para>
-
- <para>
- An empty string is returned if the field value is null. See
- <function>PQgetisnull</> to distinguish null values from
- empty-string values.
- </para>
-
- <para>
- The pointer returned by <function>PQgetvalue</function> points
- to storage that is part of the <structname>PGresult</structname>
- 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 <structname>PGresult</structname>
- structure itself.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <function>PQgetisnull</function>
- <indexterm>
- <primary>PQgetisnull</primary>
- </indexterm>
- <indexterm>
- <primary>null value</primary>
- <secondary sortas="libpq">in libpq</secondary>
- </indexterm>
- </term>
-
- <listitem>
- <para>
- Tests a field for a null value. Row and column numbers start
- at 0.
- <synopsis>
- int PQgetisnull(const PGresult *res,
- int row_number,
- int column_number);
- </synopsis>
- </para>
-
- <para>
- This function returns 1 if the field is null and 0 if it
- contains a non-null value. (Note that
- <function>PQgetvalue</function> will return an empty string,
- not a null pointer, for a null field.)
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ This function is deprecated (except for its use in connection with
+ <command>COPY</>), because it is possible for a single
+ <structname>PGresult</> to contain text data in some columns and
+ binary data in others. <function>PQfformat</> is preferred.
+ <function>PQbinaryTuples</> returns 1 only if all columns of the
+ result are binary (format 1).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQgetvalue</function>
+ <indexterm>
+ <primary>PQgetvalue</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns a single field value of one row of a
+ <structname>PGresult</structname>. Row and column numbers start
+ at 0. The caller should not free the result directly. It will
+ be freed when the associated <structname>PGresult</> handle is
+ passed to <function>PQclear</function>.
+ <synopsis>
+ char *PQgetvalue(const PGresult *res,
+ int row_number,
+ int column_number);
+ </synopsis>
+ </para>
+
+ <para>
+ For data in text format, the value returned by
+ <function>PQgetvalue</function> 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 <function>typsend</> and <function>typreceive</>
+ 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.)
+ </para>
+
+ <para>
+ An empty string is returned if the field value is null. See
+ <function>PQgetisnull</> to distinguish null values from
+ empty-string values.
+ </para>
+
+ <para>
+ The pointer returned by <function>PQgetvalue</function> points
+ to storage that is part of the <structname>PGresult</structname>
+ 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 <structname>PGresult</structname>
+ structure itself.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQgetisnull</function>
+ <indexterm>
+ <primary>PQgetisnull</primary>
+ </indexterm>
+ <indexterm>
+ <primary>null value</primary>
+ <secondary sortas="libpq">in libpq</secondary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Tests a field for a null value. Row and column numbers start
+ at 0.
+ <synopsis>
+ int PQgetisnull(const PGresult *res,
+ int row_number,
+ int column_number);
+ </synopsis>
+ </para>
+
+ <para>
+ This function returns 1 if the field is null and 0 if it
+ contains a non-null value. (Note that
+ <function>PQgetvalue</function> will return an empty string,
+ not a null pointer, for a null field.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQgetlength</function>
+ <indexterm>
+ <primary>PQgetlength</primary>
+ </indexterm></term>
+
+ <listitem>
+ <para>
+ Returns the actual length of a field value in bytes. Row and
+ column numbers start at 0.
+ <synopsis>
+ int PQgetlength(const PGresult *res,
+ int row_number,
+ int column_number);
+ </synopsis>
+ </para>
- <varlistentry>
- <term>
- <function>PQgetlength</function>
- <indexterm>
- <primary>PQgetlength</primary>
- </indexterm></term>
-
- <listitem>
- <para>
- Returns the actual length of a field value in bytes. Row and
- column numbers start at 0.
- <synopsis>
- int PQgetlength(const PGresult *res,
- int row_number,
- int column_number);
- </synopsis>
- </para>
+ <para>
+ This is the actual data length for the particular data value,
+ that is, the size of the object pointed to by
+ <function>PQgetvalue</function>. For text data format this is
+ the same as <function>strlen()</>. For binary format this is
+ essential information. Note that one should <emphasis>not</>
+ rely on <function>PQfsize</function> to obtain the actual data
+ length.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- This is the actual data length for the particular data value,
- that is, the size of the object pointed to by
- <function>PQgetvalue</function>. For text data format this is
- the same as <function>strlen()</>. For binary format this is
- essential information. Note that one should <emphasis>not</>
- rely on <function>PQfsize</function> to obtain the actual data
- length.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>
+ <function>PQnparams</function>
+ <indexterm>
+ <primary>PQnparams</primary>
+ </indexterm>
+ </term>
- <varlistentry>
- <term>
- <function>PQnparams</function>
- <indexterm>
- <primary>PQnparams</primary>
- </indexterm>
- </term>
-
- <listitem>
- <para>
- Returns the number of parameters of a prepared statement.
- <synopsis>
- int PQnparams(const PGresult *res);
- </synopsis>
- </para>
+ <listitem>
+ <para>
+ Returns the number of parameters of a prepared statement.
+ <synopsis>
+ int PQnparams(const PGresult *res);
+ </synopsis>
+ </para>
- <para>
- This function is only useful when inspecting the result of
- <function>PQdescribePrepared</>. For other types of queries it
- will return zero.
- </para>
- </listitem>
- </varlistentry>
+ This function is only useful when inspecting the result of
+ <function>PQdescribePrepared</>. For other types of queries it
+ will return zero.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- <function>PQparamtype</function>
- <indexterm>
- <primary>PQparamtype</primary>
- </indexterm></term>
-
- <listitem>
- <para>
- Returns the data type of the indicated statement parameter.
- Parameter numbers start at 0.
- <synopsis>
- Oid PQparamtype(const PGresult *res, int param_number);
- </synopsis>
- </para>
-
- <para>
- This function is only useful when inspecting the result of
- <function>PQdescribePrepared</>. For other types of queries it
- will return zero.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <function>PQprint</function>
- <indexterm>
- <primary>PQprint</primary>
- </indexterm>
- </term>
-
- <listitem>
- <para>
- Prints out all the rows and, optionally, the column names to
- the specified output stream.
- <synopsis>
+ <varlistentry>
+ <term>
+ <function>PQparamtype</function>
+ <indexterm>
+ <primary>PQparamtype</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns the data type of the indicated statement parameter.
+ Parameter numbers start at 0.
+ <synopsis>
+ Oid PQparamtype(const PGresult *res, int param_number);
+ </synopsis>
+ </para>
+
+ <para>
+ This function is only useful when inspecting the result of
+ <function>PQdescribePrepared</>. For other types of queries it
+ will return zero.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQprint</function>
+ <indexterm>
+ <primary>PQprint</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Prints out all the rows and, optionally, the column names to
+ the specified output stream.
+ <synopsis>
void PQprint(FILE *fout, /* output stream */
const PGresult *res,
const PQprintOpt *po);
} PQprintOpt;
</synopsis>
</para>
-
+
<para>
This function was formerly used by <application>psql</application>
to print query results, but this is no longer the case. Note
</varlistentry>
</variablelist>
</sect2>
-
+
<sect2 id="libpq-exec-nonselect">
<title>Retrieving Result Information for Other Commands</title>
-
+
<para>
These functions are used to extract information from
<structname>PGresult</structname> objects that are not
<command>SELECT</> results.
</para>
-
+
<variablelist>
<varlistentry>
<term>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQcmdTuples</function>
char *PQcmdTuples(PGresult *res);
</synopsis>
</para>
-
+
<para>
This function returns a string containing the number of rows
affected by the <acronym>SQL</> statement that generated the
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQoidValue</function>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQoidStatus</function>
char *PQoidStatus(const PGresult *res);
</synopsis>
</para>
-
+
<para>
This function is deprecated in favor of
<function>PQoidValue</function>. It is not thread-safe.
</listitem>
</varlistentry>
</variablelist>
-
+
</sect2>
-
+
<sect2 id="libpq-exec-escape-string">
<title>Escaping Strings for Inclusion in SQL Commands</title>
-
+
<indexterm zone="libpq-exec-escape-string">
<primary>PQescapeStringConn</primary>
</indexterm>
<primary>escaping strings</primary>
<secondary>in libpq</secondary>
</indexterm>
-
+
<para>
<function>PQescapeStringConn</function> escapes a string for use within an SQL
command. This is useful when inserting data values as literal constants
be escaped to prevent them from being interpreted specially by the SQL parser.
<function>PQescapeStringConn</> performs this operation.
</para>
-
+
<tip>
<para>
It is especially important to do proper escaping when handling strings that
SQL commands are fed to your database.
</para>
</tip>
-
+
<para>
Note that it is not necessary nor correct to do escaping when a data
value is passed as a separate parameter in <function>PQexecParams</> or
its sibling routines.
-
+
<synopsis>
size_t PQescapeStringConn (PGconn *conn,
char *to, const char *from, size_t length,
int *error);
</synopsis>
</para>
-
+
<para>
<function>PQescapeStringConn</> writes an escaped version of the
<parameter>from</> string to the <parameter>to</> buffer, escaping
<function>PQescapeStringConn</> returns the number of bytes written
to <parameter>to</>, not including the terminating zero byte.
</para>
-
+
<para>
<synopsis>
size_t PQescapeString (char *to, const char *from, size_t length);
</synopsis>
</para>
-
+
<para>
<function>PQescapeString</> is an older, deprecated version of
<function>PQescapeStringConn</>; the difference is that it does
<function>PQescapeStringConn</>.
</para>
</sect2>
-
-
+
+
<sect2 id="libpq-exec-escape-bytea">
<title>Escaping Binary Strings for Inclusion in SQL Commands</title>
-
+
<indexterm zone="libpq-exec-escape-bytea">
<primary>bytea</primary>
<secondary sortas="libpq">in libpq</secondary>
</indexterm>
-
+
<variablelist>
<varlistentry>
<term>
size_t *to_length);
</synopsis>
</para>
-
+
<para>
Certain byte values <emphasis>must</emphasis> be escaped (but all
byte values <emphasis>can</emphasis> be escaped) when used as part
information. <function>PQescapeByteaConn</function> performs this
operation, escaping only the minimally required bytes.
</para>
-
+
<para>
The <parameter>from</parameter> parameter points to the first
byte of the string that is to be escaped, and the
escaped string length. This result string length includes the terminating
zero byte of the result.
</para>
-
+
<para>
<function>PQescapeByteaConn</> returns an escaped version of the
<parameter>from</parameter> parameter binary string in memory
surround <productname>PostgreSQL</productname> string literals are
not part of the result string.
</para>
-
+
<para>
On error, a NULL pointer is returned, and a suitable error message
is stored in the <parameter>conn</> object. Currently, the only
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQescapeBytea</function>
size_t *to_length);
</synopsis>
</para>
-
+
<para>
The only difference from <function>PQescapeByteaConn</> is that
<function>PQescapeBytea</> does not take a <structname>PGconn</>
<emphasis>it might give the wrong results</>. Also, it has no
way to return an error message on failure.
</para>
-
+
<para>
<function>PQescapeBytea</> can be used safely in single-threaded
client programs that work with only one <productname>PostgreSQL</>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQunescapeBytea</function>
— the reverse of <function>PQescapeBytea</function>. This
is needed when retrieving <type>bytea</type> data in text format,
but not when retrieving it in binary format.
-
+
<synopsis>
unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
</synopsis>
</para>
-
+
<para>
The <parameter>from</parameter> parameter points to a string
such as might be returned by <function>PQgetvalue</function> when applied
the buffer in <parameter>to_length</parameter>. The result must be
freed using <function>PQfreemem</> when it is no longer needed.
</para>
-
+
<para>
This conversion is not exactly the inverse of
<function>PQescapeBytea</function>, because the string is not expected
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQfreemem</function>
void PQfreemem(void *ptr);
</synopsis>
</para>
-
+
<para>
Frees memory allocated by <application>libpq</>, particularly
<function>PQescapeByteaConn</function>,
</listitem>
</varlistentry>
</variablelist>
-
+
</sect2>
</sect1>
-
+
<sect1 id="libpq-async">
<title>Asynchronous Command Processing</title>
-
+
<indexterm zone="libpq-async">
<primary>nonblocking connection</primary>
</indexterm>
-
+
<para>
The <function>PQexec</function> function is adequate for submitting
commands in normal, synchronous applications. It has a couple of
deficiencies, however, that can be of importance to some users:
-
+
<itemizedlist>
<listitem>
<para>
from a signal handler, but not otherwise.)
</para>
</listitem>
-
+
<listitem>
<para>
<function>PQexec</function> can return only one
</listitem>
</itemizedlist>
</para>
-
+
<para>
Applications that do not like these limitations can instead use the
underlying functions that <function>PQexec</function> is built from:
<function>PQdescribePrepared</function>, and
<function>PQdescribePortal</function>
respectively.
-
+
<variablelist>
<varlistentry>
<term>
<synopsis>
int PQsendQuery(PGconn *conn, const char *command);
</synopsis>
-
+
After successfully calling <function>PQsendQuery</function>, call
<function>PQgetResult</function> one or more times to obtain the
results. <function>PQsendQuery</function> cannot be called again
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQsendQueryParams</function>
const int *paramFormats,
int resultFormat);
</synopsis>
-
+
This is equivalent to <function>PQsendQuery</function> except that
query parameters can be specified separately from the query string.
The function's parameters are handled identically to
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQsendPrepare</>
int nParams,
const Oid *paramTypes);
</synopsis>
-
+
This is an asynchronous version of <function>PQprepare</>: it
returns 1 if it was able to dispatch the request, and 0 if not.
After a successful call, call <function>PQgetResult</function> to
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQsendQueryPrepared</function>
const int *paramFormats,
int resultFormat);
</synopsis>
-
+
This is similar to <function>PQsendQueryParams</function>, but
the command to be executed is specified by naming a
previously-prepared statement, instead of giving a query string.
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQsendDescribePrepared</>
<synopsis>
int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
</synopsis>
-
+
This is an asynchronous version of <function>PQdescribePrepared</>:
it returns 1 if it was able to dispatch the request, and 0 if not.
After a successful call, call <function>PQgetResult</function> to
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQsendDescribePortal</>
<synopsis>
int PQsendDescribePortal(PGconn *conn, const char *portalName);
</synopsis>
-
+
This is an asynchronous version of <function>PQdescribePortal</>:
it returns 1 if it was able to dispatch the request, and 0 if not.
After a successful call, call <function>PQgetResult</function> to
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQgetResult</function>
PGresult *PQgetResult(PGconn *conn);
</synopsis>
</para>
-
+
<para>
<function>PQgetResult</function> must be called repeatedly until
it returns a null pointer, indicating that the command is done.
</varlistentry>
</variablelist>
</para>
-
+
<para>
Using <function>PQsendQuery</function> and
<function>PQgetResult</function> solves one of
will still cause the client to block until the server completes the
next <acronym>SQL</acronym> command. This can be avoided by proper
use of two more functions:
-
+
<variablelist>
<varlistentry>
<term>
int PQconsumeInput(PGconn *conn);
</synopsis>
</para>
-
+
<para>
<function>PQconsumeInput</function> normally returns 1 indicating
<quote>no error</quote>, but returns 0 if there was some kind of
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQisBusy</function>
int PQisBusy(PGconn *conn);
</synopsis>
</para>
-
+
<para>
<function>PQisBusy</function> will not itself attempt to read data
from the server; therefore <function>PQconsumeInput</function>
</varlistentry>
</variablelist>
</para>
-
+
<para>
A typical application using these functions will have a main loop that
uses <function>select()</function> or <function>poll()</> to wait for
to detect <command>NOTIFY</> messages (see <xref
linkend="libpq-notify">).
</para>
-
+
<para>
A client that uses
<function>PQsendQuery</function>/<function>PQgetResult</function>
simply cause the command to terminate sooner than it would have
otherwise.
</para>
-
+
<para>
By using the functions described above, it is possible to avoid
blocking while waiting for input from the database server. However,
however.) To prevent this possibility and achieve completely
nonblocking database operation, the following additional functions
can be used.
-
+
<variablelist>
<varlistentry>
<term>
int PQsetnonblocking(PGconn *conn, int arg);
</synopsis>
</para>
-
+
<para>
Sets the state of the connection to nonblocking if
<parameter>arg</parameter> is 1, or blocking if
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQisnonblocking</function>
int PQisnonblocking(const PGconn *conn);
</synopsis>
</para>
-
+
<para>
Returns 1 if the connection is set to nonblocking mode and 0 if
blocking.
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQflush</function>
</varlistentry>
</variablelist>
</para>
-
+
<para>
After sending any command or data on a nonblocking connection, call
<function>PQflush</function>. If it returns 1, wait for the socket
<function>PQflush</function> returns 0, wait for the socket to be
read-ready and then read the response as described above.
</para>
-
+
</sect1>
-
+
<sect1 id="libpq-cancel">
<title>Cancelling Queries in Progress</title>
-
+
<indexterm zone="libpq-cancel">
<primary>canceling</primary>
<secondary>SQL command</secondary>
</indexterm>
-
+
<para>
A client application can request cancellation of a command that is
still being processed by the server, using the functions described in
this section.
-
+
<variablelist>
<varlistentry>
<term>
PGcancel *PQgetCancel(PGconn *conn);
</synopsis>
</para>
-
+
<para>
<function>PQgetCancel</function> creates a
<structname>PGcancel</><indexterm><primary>PGcancel</></> object
void PQfreeCancel(PGcancel *cancel);
</synopsis>
</para>
-
+
<para>
<function>PQfreeCancel</function> frees a data object previously created
by <function>PQgetCancel</function>.
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQcancel</function>
int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
</synopsis>
</para>
-
+
<para>
The return value is 1 if the cancel request was successfully
dispatched and 0 if not. If not, <parameter>errbuf</> is filled
must be a char array of size <parameter>errbufsize</> (the
recommended size is 256 bytes).
</para>
-
+
<para>
Successful dispatch is no guarantee that the request will have
any effect, however. If the cancellation is effective, the current
processing the command), then there will be no visible result at
all.
</para>
-
+
<para>
<function>PQcancel</function> can safely be invoked from a signal
handler, if the <parameter>errbuf</> is a local variable in the
</listitem>
</varlistentry>
</variablelist>
-
+
<variablelist>
<varlistentry>
<term>
int PQrequestCancel(PGconn *conn);
</synopsis>
</para>
-
+
<para>
<function>PQrequestCancel</function> is a deprecated variant of
<function>PQcancel</function>. It operates directly on the
</varlistentry>
</variablelist>
</para>
-
+
</sect1>
-
+
<sect1 id="libpq-fastpath">
<title>The Fast-Path Interface</title>
-
+
<indexterm zone="libpq-fastpath">
<primary>fast path</primary>
</indexterm>
-
+
<para>
<productname>PostgreSQL</productname> provides a fast-path interface
to send simple function calls to the server.
</para>
-
+
<tip>
<para>
This interface is somewhat obsolete, as one can achieve similar
fast-path function call.
</para>
</tip>
-
+
<para>
The function <function>PQfn</function><indexterm><primary>PQfn</></>
requests execution of a server function via the fast-path interface:
int result_is_int,
const PQArgBlock *args,
int nargs);
-
+
typedef struct {
int len;
int isint;
} PQArgBlock;
</synopsis>
</para>
-
+
<para>
The <parameter>fnid</> argument is the OID of the function to be
executed. <parameter>args</> and <parameter>nargs</> define the
When <parameter>result_is_int</> is 0, the binary-format byte string
sent by the server is returned unmodified.
</para>
-
+
<para>
<function>PQfn</function> always returns a valid
<structname>PGresult</structname> pointer. The result status should be
freeing the <structname>PGresult</structname> with
<function>PQclear</function> when it is no longer needed.
</para>
-
+
<para>
Note that it is not possible to handle null arguments, null results,
nor set-valued results when using this interface.
</para>
-
+
</sect1>
-
+
<sect1 id="libpq-notify">
<title>Asynchronous Notification</title>
-
+
<indexterm zone="libpq-notify">
<primary>NOTIFY</primary>
<secondary>in libpq</secondary>
</indexterm>
-
+
<para>
<productname>PostgreSQL</productname> offers asynchronous notification
via the <command>LISTEN</command> and <command>NOTIFY</command>
associated table, but it is not necessary for there to be any associated
table.
</para>
-
+
<para>
<application>libpq</application> applications submit
<command>LISTEN</command> and <command>UNLISTEN</command> commands as
messages can subsequently be detected by calling
<function>PQnotifies</function>.<indexterm><primary>PQnotifies</></>
</para>
-
+
<para>
The function <function>PQnotifies</function>
returns the next notification from a list of unhandled
removed from the list of notifications.
<synopsis>
PGnotify *PQnotifies(PGconn *conn);
-
+
typedef struct pgNotify {
char *relname; /* notification condition name */
int be_pid; /* process ID of notifying server process */
<structfield>extra</structfield> field is unused and will always point
to an empty string.)
</para>
-
+
<para>
<xref linkend="libpq-example-2"> gives a sample program that illustrates
the use of asynchronous notification.
</para>
-
+
<para>
<function>PQnotifies</function> does not actually read data from the
server; it just returns messages previously absorbed by another
<function>PQexec</function>. While this still works, it is deprecated
as a waste of processing power.
</para>
-
+
<para>
A better way to check for <command>NOTIFY</> messages when you have no
useful commands to execute is to call
<function>PQgetResult</function> or <function>PQexec</function>, to
see if any notifications came in during the processing of the command.
</para>
-
+
</sect1>
-
+
<sect1 id="libpq-copy">
<title>Functions Associated with the <command>COPY</command> Command</title>
-
+
<indexterm zone="libpq-copy">
<primary>COPY</primary>
<secondary>with libpq</secondary>
</indexterm>
-
+
<para>
The <command>COPY</command> command in
<productname>PostgreSQL</productname> has options to read from or write
The functions described in this section allow applications to take
advantage of this capability by supplying or consuming copied data.
</para>
-
+
<para>
The overall process is that the application first issues the SQL
<command>COPY</command> command via <function>PQexec</function> or one
commands using the same connection while the <command>COPY</command>
operation is in progress.)
</para>
-
+
<para>
If a <command>COPY</command> command is issued via
<function>PQexec</function> in a string that could contain additional
<symbol>NULL</symbol> is it certain that the <function>PQexec</function>
command string is done and it is safe to issue more commands.
</para>
-
+
<para>
The functions of this section should be executed only after obtaining
a result status of <literal>PGRES_COPY_OUT</literal> or
<literal>PGRES_COPY_IN</literal> from <function>PQexec</function> or
<function>PQgetResult</function>.
</para>
-
+
<para>
A <structname>PGresult</> object bearing one of these status values
carries some additional data about the <command>COPY</command> operation
that is starting. This additional data is available using functions
that are also used in connection with query results:
-
+
<variablelist>
<varlistentry>
<term>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQbinaryTuples</function>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQfformat</function>
</varlistentry>
</variablelist>
</para>
-
+
<note>
<para>
These additional data values are only available when using protocol
3.0. When using protocol 2.0, all these functions will return 0.
</para>
</note>
-
+
<sect2 id="libpq-copy-send">
<title>Functions for Sending <command>COPY</command> Data</title>
-
+
<para>
These functions are used to send data during <literal>COPY FROM
STDIN</>. They will fail if called when the connection is not in
<literal>COPY_IN</> state.
</para>
-
+
<variablelist>
<varlistentry>
<term>
int nbytes);
</synopsis>
</para>
-
+
<para>
Transmits the <command>COPY</command> data in the specified
<parameter>buffer</>, of length <parameter>nbytes</>, to the server.
the return value is -1. If the value is zero, wait for write-ready
and try again.)
</para>
-
+
<para>
The application can divide the <command>COPY</command> data stream
into buffer loads of any convenient size. Buffer-load boundaries
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQputCopyEnd</function>
const char *errormsg);
</synopsis>
</para>
-
+
<para>
Ends the <literal>COPY_IN</> operation successfully if
<parameter>errormsg</> is <symbol>NULL</symbol>. If
to force failure does not work when using pre-3.0-protocol
connections.)
</para>
-
+
<para>
The result is 1 if the termination data was sent, zero if it was
not sent because the attempt would block (this case is only possible
details if the return value is -1. If the value is zero, wait for
write-ready and try again.)
</para>
-
+
<para>
After successfully calling <function>PQputCopyEnd</>, call
<function>PQgetResult</> to obtain the final result status of the
</listitem>
</varlistentry>
</variablelist>
-
+
</sect2>
-
+
<sect2 id="libpq-copy-receive">
<title>Functions for Receiving <command>COPY</command> Data</title>
-
+
<para>
These functions are used to receive data during <literal>COPY TO
STDOUT</>. They will fail if called when the connection is not in
<literal>COPY_OUT</> state.
</para>
-
+
<variablelist>
<varlistentry>
<term>
int async);
</synopsis>
</para>
-
+
<para>
Attempts to obtain another row of data from the server during a
<command>COPY</command>. Data is always returned one data row at
buffer must be freed using <function>PQfreemem</> when no longer
needed.
</para>
-
+
<para>
When a row is successfully returned, the return value is the number
of data bytes in the row (this will always be greater than zero).
<command>COPY</command> is done. A result of -2 indicates that an
error occurred (consult <function>PQerrorMessage</> for the reason).
</para>
-
+
<para>
When <parameter>async</> is true (not zero),
<function>PQgetCopyData</> will not block waiting for input; it
false (zero), <function>PQgetCopyData</> will block until data is
available or the operation completes.
</para>
-
+
<para>
After <function>PQgetCopyData</> returns -1, call
<function>PQgetResult</> to obtain the final result status of the
</listitem>
</varlistentry>
</variablelist>
-
+
</sect2>
-
+
<sect2 id="libpq-copy-deprecated">
<title>Obsolete Functions for <command>COPY</command></title>
-
+
<para>
These functions represent older methods of handling <command>COPY</>.
Although they still work, they are deprecated due to poor error handling,
inconvenient methods of detecting end-of-data, and lack of support for binary
or nonblocking transfers.
</para>
-
+
<variablelist>
<varlistentry>
<term>
int length);
</synopsis>
</para>
-
+
<para>
This function copies up to <parameter>length</>-1 characters into
the buffer and converts the terminating newline into a zero byte.
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQgetlineAsync</function>
int bufsize);
</synopsis>
</para>
-
+
<para>
This function is similar to <function>PQgetline</function>, but it can be used
by applications
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQputline</function>
const char *string);
</synopsis>
</para>
-
+
<para>
The <command>COPY</command> data stream sent by a series of calls
to <function>PQputline</function> has the same format as that
<function>PQputline</function> call; it is okay to send a partial
line or multiple lines per call.
</para>
-
+
<note>
<para>
Before <productname>PostgreSQL</productname> protocol 3.0, it was necessary
</note>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQputnbytes</function>
int nbytes);
</synopsis>
</para>
-
+
<para>
This is exactly like <function>PQputline</function>, except that the data
buffer need not be null-terminated since the number of bytes to send is
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<function>PQendcopy</function>
nonzero otherwise. (Use <function>PQerrorMessage</function> to
retrieve details if the return value is nonzero.)
</para>
-
+
<para>
When using <function>PQgetResult</function>, the application should
respond to a <literal>PGRES_COPY_OUT</literal> result by executing
ensure that a <command>COPY</command> command embedded in a series
of <acronym>SQL</acronym> commands will be executed correctly.
</para>
-
+
<para>
Older applications are likely to submit a <command>COPY</command>
via <function>PQexec</function> and assume that the transaction
</listitem>
</varlistentry>
</variablelist>
-
+
</sect2>
-
+
</sect1>
-
+
<sect1 id="libpq-control">
<title>Control Functions</title>
-
+
<para>
These functions control miscellaneous details of <application>libpq</>'s
behavior.
</para>
-
+
<variablelist>
<varlistentry>
<term>
</indexterm>
</term>
- <listitem>
- <para>
- Determines the verbosity of messages returned by
- <function>PQerrorMessage</> and <function>PQresultErrorMessage</>.
- <synopsis>
+ <listitem>
+ Determines the verbosity of messages returned by
+ <function>PQerrorMessage</> and <function>PQresultErrorMessage</>.
+ <synopsis>
typedef enum {
PQERRORS_TERSE,
PQERRORS_DEFAULT,
PQERRORS_VERBOSE
} PGVerbosity;
-
+
PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
- </synopsis>
-
- <function>PQsetErrorVerbosity</> sets the verbosity mode, returning
- the connection's previous setting. In <firstterm>TERSE</> mode,
- returned messages include severity, primary text, and position only;
- this will normally fit on a single line. The default mode produces
- messages that include the above plus any detail, hint, or context
- fields (these might span multiple lines). The <firstterm>VERBOSE</>
- mode includes all available fields. Changing the verbosity does not
- affect the messages available from already-existing
- <structname>PGresult</> objects, only subsequently-created ones.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <function>PQtrace</function>
- <indexterm>
- <primary>PQtrace</primary>
- </indexterm>
- </term>
-
- <listitem>
- <para>
- Enables tracing of the client/server communication to a debugging file stream.
- <synopsis>
- void PQtrace(PGconn *conn, FILE *stream);
- </synopsis>
- </para>
+ </synopsis>
- <note>
+ <function>PQsetErrorVerbosity</> sets the verbosity mode, returning
+ the connection's previous setting. In <firstterm>TERSE</> mode,
+ returned messages include severity, primary text, and position only;
+ this will normally fit on a single line. The default mode produces
+ messages that include the above plus any detail, hint, or context
+ fields (these might span multiple lines). The <firstterm>VERBOSE</>
+ mode includes all available fields. Changing the verbosity does not
+ affect the messages available from already-existing
+ <structname>PGresult</> objects, only subsequently-created ones.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQtrace</function>
+ <indexterm>
+ <primary>PQtrace</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
<para>
- On Windows, if the <application>libpq</> library and an application are
- compiled with different flags, this function call will crash the
- application because the internal representation of the <literal>FILE</>
- pointers differ. Specifically, multithreaded/single-threaded,
- release/debug, and static/dynamic flags should be the same for the
- library and all applications using that library.
+ Enables tracing of the client/server communication to a debugging file stream.
+ <synopsis>
+ void PQtrace(PGconn *conn, FILE *stream);
+ </synopsis>
</para>
- </note>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <function>PQuntrace</function>
- <indexterm>
- <primary>PQuntrace</primary>
- </indexterm>
- </term>
-
- <listitem>
- <para>
- Disables tracing started by <function>PQtrace</function>.
- <synopsis>
- void PQuntrace(PGconn *conn);
- </synopsis>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
+
+ <note>
+ <para>
+ On Windows, if the <application>libpq</> library and an application are
+ compiled with different flags, this function call will crash the
+ application because the internal representation of the <literal>FILE</>
+ pointers differ. Specifically, multithreaded/single-threaded,
+ release/debug, and static/dynamic flags should be the same for the
+ library and all applications using that library.
+ </para>
+ </note>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQuntrace</function>
+ <indexterm>
+ <primary>PQuntrace</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Disables tracing started by <function>PQtrace</function>.
+ <synopsis>
+ void PQuntrace(PGconn *conn);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
</sect1>
-
+
<sect1 id="libpq-misc">
<title>Miscellaneous Functions</title>
-
+
<para>
As always, there are some functions that just don't fit anywhere.
</para>
-
+
<variablelist>
<varlistentry>
<term>
</listitem>
</varlistentry>
</variablelist>
-
+
</sect1>
-
+
<sect1 id="libpq-notice-processing">
<title>Notice Processing</title>
-
+
<indexterm zone="libpq-notice-processing">
<primary>notice processing</primary>
<secondary>in libpq</secondary>
</indexterm>
-
+
<para>
Notice and warning messages generated by the server are not returned
by the query execution functions, since they do not imply failure of
<filename>stderr</filename>, but the application can override this
behavior by supplying its own handling function.
</para>
-
+
<para>
For historical reasons, there are two levels of notice handling, called
the notice receiver and notice processor. The default behavior is for
its own notice receiver will typically ignore the notice processor
layer and just do all the work in the notice receiver.
</para>
-
+
<para>
The function <function>PQsetNoticeReceiver</function>
<indexterm><primary>notice
<indexterm><primary>notice
processor</></><indexterm><primary>PQsetNoticeProcessor</></> sets or
examines the current notice processor.
-
+
<synopsis>
typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
-
+
PQnoticeReceiver
PQsetNoticeReceiver(PGconn *conn,
PQnoticeReceiver proc,
void *arg);
-
+
typedef void (*PQnoticeProcessor) (void *arg, const char *message);
-
+
PQnoticeProcessor
PQsetNoticeProcessor(PGconn *conn,
PQnoticeProcessor proc,
void *arg);
</synopsis>
-
+
Each of these functions returns the previous notice receiver or
processor function pointer, and sets the new value. If you supply a
null function pointer, no action is taken, but the current pointer is
returned.
</para>
-
+
<para>
When a notice or warning message is received from the server, or
generated internally by <application>libpq</application>, the notice
passed. (This pointer can be used to access application-specific state
if needed.)
</para>
-
+
<para>
The default notice receiver simply extracts the message (using
<function>PQresultErrorMessage</>) and passes it to the notice
processor.
</para>
-
+
<para>
The notice processor is responsible for handling a notice or warning
message given in text form. It is passed the string text of the message
one passed to <function>PQsetNoticeProcessor</function>. (This pointer
can be used to access application-specific state if needed.)
</para>
-
+
<para>
The default notice processor is simply:
<programlisting>
}
</programlisting>
</para>
-
+
<para>
Once you have set a notice receiver or processor, you should expect
that that function could be called as long as either the
into the <structname>PGresult</> for possible use by functions like
<function>PQgetvalue</function>.
</para>
-
+
</sect1>
-
+
<sect1 id="libpq-envars">
<title>Environment Variables</title>
-
+
<indexterm zone="libpq-envars">
<primary>environment variable</primary>
</indexterm>
-
+
<para>
The following environment variables can be used to select default
connection parameter values, which will be used by
<function>PQsetdb</> if no value is directly specified by the calling
code. These are useful to avoid hard-coding database connection
information into simple client applications, for example.
-
+
<itemizedlist>
<listitem>
<para>
<listitem>
<para>
- <indexterm>
+ <indexterm>
<primary><envar>PGDATABASE</envar></primary>
</indexterm>
<envar>PGDATABASE</envar> sets the
</listitem>
<listitem>
- <para>
+ <para>
<indexterm>
<primary><envar>PGPASSWORD</envar></primary>
</indexterm>
(see <xref linkend="libpq-pgpass">).
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
of setting all the parameters.
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
selected by the server.
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
<productname>PostgreSQL</productname> server.
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
connection.
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
if <productname>PostgreSQL</> is compiled with SSL support.
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
file.
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
when authenticating with Kerberos 5 or GSSAPI.
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
authentication.
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
</listitem>
</itemizedlist>
</para>
-
+
<para>
The following environment variables can be used to specify default
behavior for each <productname>PostgreSQL</productname> session. (See
and <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">
commands for ways to set default behavior on a per-user or per-database
basis.)
-
+
<itemizedlist>
<listitem>
<para>
...</literal>.)
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
<literal>SET timezone TO ...</literal>.)
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
...</literal>.)
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
</para>
</listitem>
</itemizedlist>
-
+
Refer to the <acronym>SQL</acronym> command <xref linkend="sql-set"
endterm="sql-set-title"> for information on correct values for these
environment variables.
</para>
-
+
<para>
The following environment variables determine internal behavior of
<application>libpq</application>; they override compiled-in defaults.
-
+
<itemizedlist>
<listitem>
<para>
<filename>pg_service.conf</> file.
</para>
</listitem>
-
+
<listitem>
<para>
<indexterm>
</listitem>
</itemizedlist>
</para>
-
+
</sect1>
-
-
+
+
<sect1 id="libpq-pgpass">
<title>The Password File</title>
-
+
<indexterm zone="libpq-pgpass">
<primary>password file</primary>
</indexterm>
<indexterm zone="libpq-pgpass">
<primary>.pgpass</primary>
</indexterm>
-
+
<para>
The file <filename>.pgpass</filename> in a user's home directory or the
file referenced by <envar>PGPASSFILE</envar> can contain passwords to
<filename>%APPDATA%</> refers to the Application Data subdirectory in
the user's profile).
</para>
-
+
<para>
This file should contain lines of the following format:
<synopsis>
or the default socket directory) connections coming from the local
machine.
</para>
-
+
<para>
On Unix systems, the permissions on <filename>.pgpass</filename> must
disallow any access to world or group; achieve this by the command
no special permissions check is made.
</para>
</sect1>
-
-
+
+
<sect1 id="libpq-pgservice">
<title>The Connection Service File</title>
-
+
<indexterm zone="libpq-pgservice">
<primary>connection service file</primary>
</indexterm>
<indexterm zone="libpq-pgservice">
<primary>pg_service.conf</primary>
</indexterm>
-
+
<para>
The connection service file allows libpq connection parameters to be
associated with a single service name. That service name can then be
<envar>PGSYSCONFDIR</envar> environment variable.
</para>
</sect1>
-
-
+
+
<sect1 id="libpq-ldap">
<title>LDAP Lookup of Connection Parameters</title>
-
+
<indexterm zone="libpq-ldap">
<primary>LDAP connection parameter lookup</primary>
</indexterm>
-
+
<para>
If <application>libpq</application> has been compiled with LDAP support (option
<literal><option>--with-ldap</option></literal> for <command>configure</command>)
The advantage is that if the connection parameters for a database change,
the connection information doesn't have to be updated on all client machines.
</para>
-
+
<para>
LDAP connection parameter lookup uses the connection service file
<filename>pg_service.conf</filename> (see <xref
<literal>localhost</literal> and <replaceable>port</replaceable>
defaults to 389.
</para>
-
+
<para>
Processing of <filename>pg_service.conf</filename> is terminated after
a successful LDAP lookup, but is continued if the LDAP server cannot
rather get an error message in this case, add a syntactically incorrect
line after the LDAP URL.
</para>
-
+
<para>
A sample LDAP entry that has been created with the LDIF file
<synopsis>
</synopsis>
</para>
</sect1>
-
-
+
+
<sect1 id="libpq-ssl">
<title>SSL Support</title>
-
+
<indexterm zone="libpq-ssl">
<primary>SSL</primary>
</indexterm>
-
+
<para>
<productname>PostgreSQL</> has native support for using <acronym>SSL</>
connections to encrypt client/server communications for increased
security. See <xref linkend="ssl-tcp"> for details about the server-side
<acronym>SSL</> functionality.
</para>
-
+
<para>
<application>libpq</application> reads the system-wide
<productname>OpenSSL</productname> configuration file. By default, this
<envar>OPENSSL_CONF</envar> to the name of the desired configuration
file.
</para>
-
+
<para>
If the server demands a client certificate,
<application>libpq</application> will send the certificate stored in
</sect1>
-
-
+
+
<sect1 id="libpq-threading">
<title>Behavior in Threaded Programs</title>
-
+
<indexterm zone="libpq-threading">
<primary>threads</primary>
<secondary>with libpq</secondary>
</indexterm>
-
+
<para>
<application>libpq</application> is reentrant and thread-safe if the
<filename>configure</filename> command-line option
addition, you might need to use additional compiler command-line
options when you compile your application code. Refer to your
system's documentation for information about how to build
- thread-enabled applications, or look in
+ thread-enabled applications, or look in
<filename>src/Makefile.global</filename> for <literal>PTHREAD_CFLAGS</>
and <literal>PTHREAD_LIBS</>. This function allows the querying of
<application>libpq</application>'s thread-safe status:
</para>
-
+
<variablelist>
<varlistentry>
<term>
int PQisthreadsafe();
</synopsis>
</para>
-
+
<para>
Returns 1 if the <application>libpq</application> is thread-safe
and 0 if it is not.
</listitem>
</varlistentry>
</variablelist>
-
+
<para>
One thread restriction is that no two threads attempt to manipulate
the same <structname>PGconn</> object at the same time. In particular,
the same connection object. (If you need to run concurrent commands,
use multiple connections.)
</para>
-
+
<para>
<structname>PGresult</> objects are read-only after creation, and so
can be passed around freely between threads.
</para>
-
+
<para>
The deprecated functions <function>PQrequestCancel</function> and
<function>PQoidStatus</function> are not thread-safe and should not be
<function>PQoidStatus</function> can be replaced by
<function>PQoidValue</function>.
</para>
-
+
<para>
If you are using Kerberos inside your application (in addition to inside
<application>libpq</application>), you will need to do locking around
<application>libpq</application> source code for a way to do cooperative
locking between <application>libpq</application> and your application.
</para>
-
+
<para>
If you experience problems with threaded applications, run the program
in <filename>src/tools/thread</> to see if your platform has
library might not match the library used to build the binaries.
</para>
</sect1>
-
-
+
+
<sect1 id="libpq-build">
<title>Building <application>libpq</application> Programs</title>
-
+
<indexterm zone="libpq-build">
<primary>compiling</primary>
<secondary>libpq applications</secondary>
</indexterm>
-
+
<para>
To build (i.e., compile and link) a program using
<application>libpq</application> you need to do all of the following
things:
-
+
<itemizedlist>
<listitem>
<para>
</screen>
</para>
</listitem>
-
+
<listitem>
<para>
Point your compiler to the directory where the <productname>PostgreSQL</> header
CPPFLAGS += -I/usr/local/pgsql/include
</programlisting>
</para>
-
+
<para>
If there is any chance that your program might be compiled by
other users then you should not hardcode the directory location
<computeroutput>/usr/local/include</computeroutput>
</screen>
</para>
-
+
<para>
Failure to specify the correct option to the compiler will
result in an error message such as
</screen>
</para>
</listitem>
-
+
<listitem>
<para>
When linking the final program, specify the option
cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq
</programlisting>
</para>
-
+
<para>
You can find out the library directory using
<command>pg_config</command> as well:
<computeroutput>/usr/local/pgsql/lib</computeroutput>
</screen>
</para>
-
+
<para>
Error messages that point to problems in this area could look like
the following.
</listitem>
</itemizedlist>
</para>
-
+
</sect1>
-
-
+
+
<sect1 id="libpq-example">
<title>Example Programs</title>
-
+
<para>
These examples and others can be found in the
directory <filename>src/test/examples</filename> in the source code
OSDN Git Service
