*conninfo);

PostgresPollingStatusType PQconnectPoll(PGconn *conn);
</synopsis>
      </para>

      <para>
       These three 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
       <xref linkend="libpq-PQconnectdbParams"/> or <xref linkend="libpq-PQconnectdb"/>, and so the
       application can manage this operation in parallel with other activities.
      </para>

      <para>
       With <xref linkend="libpq-PQconnectStartParams"/>, the database connection is made
       using the parameters taken from the <literal>keywords</literal> and
       <literal>values</literal> arrays, and controlled by <literal>expand_dbname</literal>,
       as described above for <xref linkend="libpq-PQconnectdbParams"/>.
      </para>

      <para>
       With <function>PQconnectStart</function>, the database connection is made
       using the parameters taken from the string <literal>conninfo</literal> as
       described above for <xref linkend="libpq-PQconnectdb"/>.
      </para>

      <para>
       Neither <xref linkend="libpq-PQconnectStartParams"/> nor <function>PQconnectStart</function>
       nor <function>PQconnectPoll</function> will block, so long as a number of
       restrictions are met:
       <itemizedlist>
        <listitem>
         <para>
          The <literal>hostaddr</literal> parameter must be used appropriately
          to prevent DNS queries from being made.  See the documentation of
          this parameter in <xref linkend="libpq-paramkeywords"/> for details.
         </para>
        </listitem>

        <listitem>
         <para>
          If you call <xref linkend="libpq-PQtrace"/>, ensure that the stream object
          into which you trace will not block.
         </para>
        </listitem>

        <listitem>
         <para>
          You must 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 <function>PQconnectStart</function>
       or <xref linkend="libpq-PQconnectStartParams"/>.  If the result is null,
       then <application>libpq</application> has been unable to allocate a
       new <structname>PGconn</structname> structure.  Otherwise, a
       valid <structname>PGconn</structname> pointer is returned (though not
       yet representing a valid connection to the database).  Next
       call <literal>PQstatus(conn)</literal>.  If the result
       is <symbol>CONNECTION_BAD</symbol>, the connection attempt has already
       failed, typically because of invalid connection parameters.
      </para>

      <para>
       If <function>PQconnectStart</function>
       or <xref linkend="libpq-PQconnectStartParams"/> succeeds, the next stage
       is to poll <application>libpq</application> 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.
       (Caution: do not assume that the socket remains the same
       across <function>PQconnectPoll</function> calls.)
       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>, <function>poll()</function>, or
       similar system function).  Note that <function>PQsocketPoll</function>
       can help reduce boilerplate by abstracting the setup of
       <function>select(2)</function> or <function>poll(2)</function> if it is
       available on your system.
       Then call <function>PQconnectPoll(conn)</function>