libpq.sgml

关系型数据库 Postgresql 6.5.2

actually available.)
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQputline</Function>
Sends  a  null-terminated  string  to  the backend server.
Returns 0 if OK, EOF if unable to send the string.
<synopsis>
int PQputline(PGconn *conn,
              char *string);
</synopsis>
Note the application must explicitly  send  the  two
characters  "\." on a final line  to indicate to the backend that it
has finished sending its data.
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQputnbytes</Function>
Sends  a  non-null-terminated  string  to  the backend server.
Returns 0 if OK, EOF if unable to send the string.
<synopsis>
int PQputnbytes(PGconn *conn,
                const char *buffer,
                int nbytes);
</synopsis>
This is exactly like PQputline, except that the data buffer need
not be null-terminated since the number of bytes to send is
specified directly.
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQendcopy</Function>
          Syncs with the backend.  This function waits until
          the  backend  has  finished  the  copy.  It should
          either be issued when the  last  string  has  been
          sent  to  the  backend using PQputline or when the
          last string has been  received  from  the  backend
          using PGgetline.  It must be issued or the backend
          may get "out of sync"  with  the  frontend.   Upon
          return from this function, the backend is ready to
          receive the next query.
          The return value is 0  on  successful  completion,
          nonzero otherwise.
<synopsis>
int PQendcopy(PGconn *conn);
</synopsis>
</Para>

<Para>
As an example:

<ProgramListing>
PQexec(conn, "create table foo (a int4, b char(16), d float8)");
PQexec(conn, "copy foo from stdin");
PQputline(conn, "3\thello world\t4.5\n");
PQputline(conn,"4\tgoodbye world\t7.11\n");
...
PQputline(conn,"\\.\n");
PQendcopy(conn);
</ProgramListing>
</Para>
</ListItem>
</ItemizedList>
</Para>

<Para>
When using PQgetResult, the application should respond to
a PGRES_COPY_OUT result by executing PQgetline repeatedly,
followed by PQendcopy after the terminator line is seen.
It should then return to the PQgetResult loop until PQgetResult
returns NULL.  Similarly a PGRES_COPY_IN result is processed
by a series of PQputline calls followed by PQendcopy, then
return to the PQgetResult loop.  This arrangement will ensure that
a copy in or copy out command embedded in a series of SQL commands
will be executed correctly.
Older applications are likely to submit a copy in or copy out
via PQexec and assume that the transaction is done after PQendcopy.
This will work correctly only if the copy in/out is the only
SQL command in the query string.
</Para>

</Sect1>

<Sect1>
<Title><FileName>libpq</FileName> Tracing Functions</Title>

<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQtrace</Function>
          Enable  tracing of the frontend/backend communication to a debugging file stream.
<synopsis>
void PQtrace(PGconn *conn
             FILE *debug_port)
</synopsis>
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQuntrace</Function>
          Disable tracing started by PQtrace
<synopsis>
void PQuntrace(PGconn *conn)
</synopsis>
</Para>
</ListItem>
</ItemizedList>
</Para>

</Sect1>

<Sect1>
<Title>
<FileName>libpq</FileName> Control Functions</Title>

<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQsetNoticeProcessor</Function>
Control reporting of notice and warning messages generated by libpq.
<synopsis>
void PQsetNoticeProcessor (PGconn * conn,
        void (*noticeProcessor) (void * arg, const char * message),
        void * arg)
</synopsis>
</Para>
</ListItem>
</ItemizedList>
</Para>

<Para>
By default, <filename>libpq</filename> prints "notice" messages from the backend on stderr,
as well as a few error messages that it generates by itself.
This behavior can be overridden by supplying a callback function that
does something else with the messages.  The callback function is passed
the text of the error message (which includes a trailing newline), plus
a void pointer that is the same one passed to <function>PQsetNoticeProcessor</function>.
(This pointer can be used to access application-specific state if needed.)
The default notice processor is simply
<ProgramListing>
static void
defaultNoticeProcessor(void * arg, const char * message)
{
    fprintf(stderr, "%s", message);
}
</ProgramListing>
</Para>

<Para>
To use a special notice processor, call <function>PQsetNoticeProcessor</function> just after
creation of a new PGconn object.
</Para>

</Sect1>

<Sect1>
<Title>User Authentication Functions</Title>

<Para>
The frontend/backend authentication process is  handled
by  <Function>PQconnectdb</Function>  without any further intervention.
The authentication method is now
determined entirely by the DBA (see pga_hba.conf(5)).  The following
routines no longer have any effect and should not be used.
</Para>

<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>fe_getauthname</Function>
          Returns a pointer to static space containing whatever name the user has authenticated.  Use of this
          routine  in  place  of calls to getenv(3) or getpwuid(3) by applications is highly recommended,  as
          it  is  entirely  possible  that the authenticated
          user name is not the same as  value  of  the  <Acronym>USER</Acronym>
          environment   variable  or  the  user's  entry  in
          <FileName>/etc/passwd</FileName>.
<synopsis>
char *fe_getauthname(char* errorMessage)
</synopsis>
</Para>
</ListItem>

<ListItem>
<Para>
<Function>fe_setauthsvc</Function>
          Specifies that  <FileName>libpq</FileName>  should  use  authentication
          service  name rather than its compiled-in default.
          This value is typically taken from a  command-line
          switch.
<synopsis>
void fe_setauthsvc(char *name,
                   char* errorMessage)
</synopsis>
          Any   error   messages   from  the  authentication
          attempts are returned in  the  errorMessage  argument.
</Para>
</ListItem>
</ItemizedList>
</Para>

</Sect1>

<Sect1 id="libpq-envars">
<Title>Environment Variables</Title>

<Para>
The following environment variables can be used to select default
connection parameter values, which will be used by PQconnectdb or
PQsetdbLogin if no value is directly specified by the calling code.
These are useful to avoid hard-coding database names into simple
application programs.

<ItemizedList>
<ListItem>
<Para>
<Acronym>PGHOST</Acronym> sets the default server name.
If a non-zero-length string is specified, TCP/IP communication is used.
Without a host name, libpq will connect using a local Unix domain socket.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGPORT</Acronym>  sets the default port or local Unix domain socket
file extension for communicating with the <ProductName>Postgres</ProductName>
backend.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGDATABASE</Acronym>  sets the default 
<ProductName>Postgres</ProductName> database name.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGUSER</Acronym>
sets the username used to connect to the database and for authentication.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGPASSWORD</Acronym>
sets the password used if the backend demands password authentication.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGREALM</Acronym> sets the Kerberos realm to  use  with  
<ProductName>Postgres</ProductName>,
  if  it is different from the local realm.  If
<Acronym>PGREALM</Acronym> is set, <ProductName>Postgres</ProductName> 
applications  will  attempt
        authentication  with  servers for this realm and use
        separate ticket files to avoid conflicts with  local
        ticket  files.   This  environment  variable is only
        used if Kerberos authentication is selected by the backend.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGOPTIONS</Acronym> sets additional runtime  options  for  
the <ProductName>Postgres</ProductName> backend.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGTTY</Acronym> sets the file or tty on which  debugging  
messages from the backend server are displayed.
</Para>
</ListItem>
</ItemizedList>
</Para>

<Para>
The following environment variables can be used to specify user-level default
behavior for every Postgres session:

<ItemizedList>
<ListItem>
<Para>
<Acronym>PGDATESTYLE</Acronym>
sets the default style of date/time representation.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGTZ</Acronym>
sets the default time zone.
</Para>
</ListItem>
</ItemizedList>
</Para>

<Para>
The following environment variables can be used to specify default internal
behavior for every Postgres session:

<ItemizedList>
<ListItem>
<Para>
<Acronym>PGGEQO</Acronym>
sets the default mode for the genetic optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGRPLANS</Acronym>
sets the default mode to allow or disable right-sided plans in the optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGCOSTHEAP</Acronym>
sets the default cost for heap searches for the optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGCOSTINDEX</Acronym>
sets the default cost for indexed searches for the optimizer.
</Para>
</ListItem>
</ItemizedList>
</Para>

<Para>
Refer to the <command>SET</command> <acronym>SQL</acronym> command
for information on correct values for these environment variables.
</Para>

</Sect1>

<Sect1>
<Title>Caveats</Title>

<Para>
     The  query  buffer is 8192 bytes long, and queries over
     that length will be rejected.
</Para>
</Sect1>

<Sect1>
<Title>Sample Programs</Title>

<Sect2>
<Title>Sample Program 1</Title>

<Para>
<ProgramListing>
/*
 * testlibpq.c Test the C version of Libpq, the Postgres frontend
 * library.
 *
 *
 */
#include &lt;stdio.h&gt;
#include "libpq-fe.h"

void
exit_nicely(PGconn *conn)
{
    PQfinish(conn);
    exit(1);
}

main()
{
    char       *pghost,
               *pgport,
               *pgoptions,
               *pgtty;
    char       *dbName;
    int         nFields;
    int         i,
                j;

    /* FILE *debug; */

    PGconn     *conn;
    PGresult   *res;

    /*
     * begin, by setting the parameters for a backend connection if the
     * parameters are null, then the system will try to use reasonable
     * defaults by looking up environment variables or, failing that,
     * using hardwired constants
     */