diff --git a/src/man/libpq.3 b/src/man/libpq.3
index 1675a8ea7a368cf7f14504c68b5aa6277392007e..e89e5ebc01c3a685118ec92c09f8de91ef5c42bd 100644
--- a/src/man/libpq.3
+++ b/src/man/libpq.3
@@ -1,6 +1,6 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.17 1998/06/24 13:21:27 momjian Exp $
+.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.18 1998/07/04 17:50:04 momjian Exp $
.TH LIBPQ INTRO 03/12/94 PostgreSQL PostgreSQL
.SH DESCRIPTION
Libpq is the programmer's interface to Postgres. Libpq is a set of
@@ -109,8 +109,14 @@ The following routines deal with making a connection to a backend
from a C program.
.PP
.B PQsetdb
+.br
+.B PQsetdbLogin
.IP
Makes a new connection to a backend.
+.B PQsetdb
+is the method usually used to
+connect to the database when username/password authentication is not
+needed.
.nf
PGconn *PQsetdb(char *pghost,
char *pgport,
@@ -118,12 +124,30 @@ PGconn *PQsetdb(char *pghost,
char *pgtty,
char *dbName);
.fi
+
+.IP
+.B PQsetdbLogin
+is the method used to
+connect to the database when username/password authentication is
+needed.
+.nf
+PGconn *PQsetdbLogin(char *pghost,
+ char *pgport,
+ char *pgoptions,
+ char *pgtty,
+ char *dbName,
+ char *login,
+ char *pwd);
+.fi
+
If any argument is NULL, then the corresponding environment variable
is checked. If the environment variable is also not set, then hardwired
defaults are used.
.IP
.I PQsetdb
-always returns a valid PGconn pointer. The
+and
+.I PQsetdbLogin
+always return a valid PGconn pointer. The
.I PQstatus
(see below) command should be called to ensure that a connection was
properly made before queries are sent via the connection. Libpq
@@ -132,37 +156,44 @@ the accessor functions below to get at the contents of PGconn. Avoid
directly referencing the fields of the PGconn structure as they are
subject to change in the future.
.IP
+
.B PQdb
returns the database name of the connection.
.nf
char *PQdb(PGconn *conn)
.fi
+
.B PQhost
returns the host name of the connection.
.nf
char *PQhost(PGconn *conn)
.fi
+
.B PQoptions
returns the pgoptions used in the connection.
.nf
char *PQoptions(PGconn *conn)
.fi
+
.B PQport
returns the pgport of the connection.
.nf
char *PQport(PGconn *conn)
.fi
+
.B PQtty
returns the pgtty of the connection.
.nf
char *PQtty(PGconn *conn)
.fi
+
.B PQstatus
Returns the status of the connection. The status can be CONNECTION_OK or
CONNECTION_BAD.
.nf
ConnStatusType *PQstatus(PGconn *conn)
.fi
+
.B PQerrorMessage
returns the error message associated with the connection
.nf
@@ -638,112 +669,129 @@ be silently truncated.
.nf M
/*
* testlibpq.c
- * Test the C version of Libpq, the Postgres frontend library.
+ * Test the C version of Libpq, the Postgres frontend library.
*
*
*/
#include <stdio.h>
#include "libpq-fe.h"
-void
-exit_nicely(PGconn* conn)
+void
+exit_nicely(PGconn *conn)
{
- PQfinish(conn);
- exit(1);
+ PQfinish(conn);
+ exit(1);
}
main()
{
- char *pghost, *pgport, *pgoptions, *pgtty;
- char* dbName;
- int nFields;
- int i,j;
+ 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 */
- pghost = NULL; /* host name of the backend server */
- pgport = NULL; /* port of the backend server */
- pgoptions = NULL; /* special options to start up the backend server */
- pgtty = NULL; /* debugging tty for the backend server */
- dbName = "template1";
-
- /* make a connection to the database */
- conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
-
- /* check to see that the backend connection was successfully made */
- if (PQstatus(conn) == CONNECTION_BAD) {
- fprintf(stderr,"Connection to database '%s' failed.\\n", dbName);
- fprintf(stderr,"%s",PQerrorMessage(conn));
- exit_nicely(conn);
- }
+ 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
+ */
+ pghost = NULL; /* host name of the backend server */
+ pgport = NULL; /* port of the backend server */
+ pgoptions = NULL; /* special options to start up the backend
+ * server */
+ pgtty = NULL; /* debugging tty for the backend server */
+ dbName = "template1";
+
+ /* make a connection to the database */
+ conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
+
+ /* check to see that the backend connection was successfully made */
+ if (PQstatus(conn) == CONNECTION_BAD)
+ {
+ fprintf(stderr, "Connection to database '%s' failed.\\n", dbName);
+ fprintf(stderr, "%s", PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
/* debug = fopen("/tmp/trace.out","w"); */
/* PQtrace(conn, debug); */
- /* start a transaction block */
- res = PQexec(conn,"BEGIN");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"BEGIN command failed\\n");
- PQclear(res);
- exit_nicely(conn);
- }
- /* should PQclear PGresult whenever it is no longer needed to avoid
- memory leaks */
- PQclear(res);
-
- /* fetch instances from the pg_database, the system catalog of databases*/
- res = PQexec(conn,"DECLARE mycursor CURSOR FOR select * from pg_database");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"DECLARE CURSOR command failed\\n");
+ /* start a transaction block */
+ res = PQexec(conn, "BEGIN");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "BEGIN command failed\\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ /*
+ * should PQclear PGresult whenever it is no longer needed to avoid
+ * memory leaks
+ */
PQclear(res);
- exit_nicely(conn);
- }
- PQclear(res);
- res = PQexec(conn,"FETCH ALL in mycursor");
- if (PQresultStatus(res) != PGRES_TUPLES_OK) {
- fprintf(stderr,"FETCH ALL command didn't return tuples properly\\n");
+ /*
+ * fetch instances from the pg_database, the system catalog of
+ * databases
+ */
+ res = PQexec(conn, "DECLARE mycursor CURSOR FOR select * from pg_database");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "DECLARE CURSOR command failed\\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
PQclear(res);
- exit_nicely(conn);
- }
-
- /* first, print out the attribute names */
- nFields = PQnfields(res);
- for (i=0; i < nFields; i++) {
- printf("%-15s",PQfname(res,i));
- }
- printf("\\n\\n");
-
- /* next, print out the instances */
- for (i=0; i < PQntuples(res); i++) {
- for (j=0 ; j < nFields; j++) {
- printf("%-15s", PQgetvalue(res,i,j));
+
+ res = PQexec(conn, "FETCH ALL in mycursor");
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "FETCH ALL command didn't return tuples properly\\n");
+ PQclear(res);
+ exit_nicely(conn);
}
- printf("\\n");
- }
- PQclear(res);
-
- /* close the cursor */
- res = PQexec(conn, "CLOSE mycursor");
- PQclear(res);
+ /* first, print out the attribute names */
+ nFields = PQnfields(res);
+ for (i = 0; i < nFields; i++)
+ printf("%-15s", PQfname(res, i));
+ printf("\\n\\n");
+
+ /* next, print out the instances */
+ for (i = 0; i < PQntuples(res); i++)
+ {
+ for (j = 0; j < nFields; j++)
+ printf("%-15s", PQgetvalue(res, i, j));
+ printf("\\n");
+ }
- /* commit the transaction */
- res = PQexec(conn, "COMMIT");
- PQclear(res);
+ PQclear(res);
+
+ /* close the cursor */
+ res = PQexec(conn, "CLOSE mycursor");
+ PQclear(res);
- /* close the connection to the database and cleanup */
- PQfinish(conn);
+ /* commit the transaction */
+ res = PQexec(conn, "COMMIT");
+ PQclear(res);
+
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
/* fclose(debug); */
}
+
.fi
.bp
.SH "Sample Program 2"
@@ -751,7 +799,7 @@ main()
.nf M
/*
* testlibpq2.c
- * Test of the asynchronous notification interface
+ * Test of the asynchronous notification interface
*
populate a database with the following:
@@ -772,74 +820,91 @@ INSERT INTO TBL1 values (10);
#include <stdio.h>
#include "libpq-fe.h"
-void exit_nicely(PGconn* conn)
+void
+exit_nicely(PGconn *conn)
{
- PQfinish(conn);
- exit(1);
+ PQfinish(conn);
+ exit(1);
}
main()
{
- char *pghost, *pgport, *pgoptions, *pgtty;
- char* dbName;
- int nFields;
- int i,j;
-
- PGconn* conn;
- PGresult* res;
- PGnotify* notify;
-
- /* 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 */
- pghost = NULL; /* host name of the backend server */
- pgport = NULL; /* port of the backend server */
- pgoptions = NULL; /* special options to start up the backend server */
- pgtty = NULL; /* debugging tty for the backend server */
- dbName = getenv("USER"); /* change this to the name of your test database*/
-
- /* make a connection to the database */
- conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
-
- /* check to see that the backend connection was successfully made */
- if (PQstatus(conn) == CONNECTION_BAD) {
- fprintf(stderr,"Connection to database '%s' failed.\\n", dbName);
- fprintf(stderr,"%s",PQerrorMessage(conn));
- exit_nicely(conn);
- }
-
- res = PQexec(conn, "LISTEN TBL2");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"LISTEN command failed\\n");
+ char *pghost,
+ *pgport,
+ *pgoptions,
+ *pgtty;
+ char *dbName;
+ int nFields;
+ int i,
+ j;
+
+ PGconn *conn;
+ PGresult *res;
+ PGnotify *notify;
+
+ /*
+ * 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
+ */
+ pghost = NULL; /* host name of the backend server */
+ pgport = NULL; /* port of the backend server */
+ pgoptions = NULL; /* special options to start up the backend
+ * server */
+ pgtty = NULL; /* debugging tty for the backend server */
+ dbName = getenv("USER"); /* change this to the name of your test
+ * database */
+
+ /* make a connection to the database */
+ conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
+
+ /* check to see that the backend connection was successfully made */
+ if (PQstatus(conn) == CONNECTION_BAD)
+ {
+ fprintf(stderr, "Connection to database '%s' failed.\\n", dbName);
+ fprintf(stderr, "%s", PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ res = PQexec(conn, "LISTEN TBL2");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "LISTEN command failed\\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ /*
+ * should PQclear PGresult whenever it is no longer needed to avoid
+ * memory leaks
+ */
PQclear(res);
- exit_nicely(conn);
- }
- /* should PQclear PGresult whenever it is no longer needed to avoid
- memory leaks */
- PQclear(res);
-
- while (1) {
- /* async notification only come back as a result of a query*/
- /* we can send empty queries */
- res = PQexec(conn, "");
+
+ while (1)
+ {
+ /* async notification only come back as a result of a query */
+ /* we can send empty queries */
+ res = PQexec(conn, "");
/* printf("res->status = %s\\n", pgresStatus[PQresultStatus(res)]); */
- /* check for asynchronous returns */
- notify = PQnotifies(conn);
- if (notify) {
- fprintf(stderr,
- "ASYNC NOTIFY of '%s' from backend pid '%d' received\\n",
- notify->relname, notify->be_pid);
- free(notify);
- break;
- }
- PQclear(res);
- }
-
- /* close the connection to the database and cleanup */
- PQfinish(conn);
+ /* check for asynchronous returns */
+ notify = PQnotifies(conn);
+ if (notify)
+ {
+ fprintf(stderr,
+ "ASYNC NOTIFY of '%s' from backend pid '%d' received\\n",
+ notify->relname, notify->be_pid);
+ free(notify);
+ break;
+ }
+ PQclear(res);
+ }
+
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
}
+
.fi
.bp
.SH "Sample Program 3"
@@ -847,13 +912,13 @@ main()
.nf M
/*
* testlibpq3.c
- * Test the C version of Libpq, the Postgres frontend library.
+ * Test the C version of Libpq, the Postgres frontend library.
* tests the binary cursor interface
*
*
*
populate a database by doing the following:
-
+
CREATE TABLE test1 (i int4, d float4, p polygon);
INSERT INTO test1 values (1, 3.567, '(3.0, 4.0, 1.0, 2.0)'::polygon);
@@ -875,123 +940,149 @@ tuple 1: got
*/
#include <stdio.h>
#include "libpq-fe.h"
-#include "utils/geo-decls.h" /* for the POLYGON type */
+#include "utils/geo-decls.h" /* for the POLYGON type */
-void exit_nicely(PGconn* conn)
+void
+exit_nicely(PGconn *conn)
{
- PQfinish(conn);
- exit(1);
+ PQfinish(conn);
+ exit(1);
}
main()
{
- char *pghost, *pgport, *pgoptions, *pgtty;
- char* dbName;
- int nFields;
- int i,j;
- int i_fnum, d_fnum, p_fnum;
-
- 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 */
- pghost = NULL; /* host name of the backend server */
- pgport = NULL; /* port of the backend server */
- pgoptions = NULL; /* special options to start up the backend server */
- pgtty = NULL; /* debugging tty for the backend server */
-
- dbName = getenv("USER"); /* change this to the name of your test database*/
-
- /* make a connection to the database */
- conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
-
- /* check to see that the backend connection was successfully made */
- if (PQstatus(conn) == CONNECTION_BAD) {
- fprintf(stderr,"Connection to database '%s' failed.\\n", dbName);
- fprintf(stderr,"%s",PQerrorMessage(conn));
- exit_nicely(conn);
- }
-
- /* start a transaction block */
- res = PQexec(conn,"BEGIN");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"BEGIN command failed\\n");
+ char *pghost,
+ *pgport,
+ *pgoptions,
+ *pgtty;
+ char *dbName;
+ int nFields;
+ int i,
+ j;
+ int i_fnum,
+ d_fnum,
+ p_fnum;
+
+ 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
+ */
+ pghost = NULL; /* host name of the backend server */
+ pgport = NULL; /* port of the backend server */
+ pgoptions = NULL; /* special options to start up the backend
+ * server */
+ pgtty = NULL; /* debugging tty for the backend server */
+
+ dbName = getenv("USER"); /* change this to the name of your test
+ * database */
+
+ /* make a connection to the database */
+ conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
+
+ /* check to see that the backend connection was successfully made */
+ if (PQstatus(conn) == CONNECTION_BAD)
+ {
+ fprintf(stderr, "Connection to database '%s' failed.\\n", dbName);
+ fprintf(stderr, "%s", PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ /* start a transaction block */
+ res = PQexec(conn, "BEGIN");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "BEGIN command failed\\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ /*
+ * should PQclear PGresult whenever it is no longer needed to avoid
+ * memory leaks
+ */
PQclear(res);
- exit_nicely(conn);
- }
- /* should PQclear PGresult whenever it is no longer needed to avoid
- memory leaks */
- PQclear(res);
-
- /* fetch instances from the pg_database, the system catalog of databases*/
- res = PQexec(conn,"DECLARE mycursor BINARY CURSOR FOR select * from test1");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"DECLARE CURSOR command failed\\n");
+
+ /*
+ * fetch instances from the pg_database, the system catalog of
+ * databases
+ */
+ res = PQexec(conn, "DECLARE mycursor BINARY CURSOR FOR select * from test1");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "DECLARE CURSOR command failed\\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
PQclear(res);
- exit_nicely(conn);
- }
- PQclear(res);
- res = PQexec(conn,"FETCH ALL in mycursor");
- if (PQresultStatus(res) != PGRES_TUPLES_OK) {
- fprintf(stderr,"FETCH ALL command didn't return tuples properly\\n");
+ res = PQexec(conn, "FETCH ALL in mycursor");
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "FETCH ALL command didn't return tuples properly\\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ i_fnum = PQfnumber(res, "i");
+ d_fnum = PQfnumber(res, "d");
+ p_fnum = PQfnumber(res, "p");
+
+ for (i = 0; i < 3; i++)
+ {
+ printf("type[%d] = %d, size[%d] = %d\\n",
+ i, PQftype(res, i),
+ i, PQfsize(res, i));
+ }
+ for (i = 0; i < PQntuples(res); i++)
+ {
+ int *ival;
+ float *dval;
+ int plen;
+ POLYGON *pval;
+
+ /* we hard-wire this to the 3 fields we know about */
+ ival = (int *) PQgetvalue(res, i, i_fnum);
+ dval = (float *) PQgetvalue(res, i, d_fnum);
+ plen = PQgetlength(res, i, p_fnum);
+
+ /*
+ * plen doesn't include the length field so need to increment by
+ * VARHDSZ
+ */
+ pval = (POLYGON *) malloc(plen + VARHDRSZ);
+ pval->size = plen;
+ memmove((char *) &pval->npts, PQgetvalue(res, i, p_fnum), plen);
+ printf("tuple %d: got\\n", i);
+ printf(" i = (%d bytes) %d,\\n",
+ PQgetlength(res, i, i_fnum), *ival);
+ printf(" d = (%d bytes) %f,\\n",
+ PQgetlength(res, i, d_fnum), *dval);
+ printf(" p = (%d bytes) %d points \\tboundbox = (hi=%f/%f, lo = %f,%f)\\n",
+ PQgetlength(res, i, d_fnum),
+ pval->npts,
+ pval->boundbox.xh,
+ pval->boundbox.yh,
+ pval->boundbox.xl,
+ pval->boundbox.yl);
+ }
+
PQclear(res);
- exit_nicely(conn);
- }
-
- i_fnum = PQfnumber(res,"i");
- d_fnum = PQfnumber(res,"d");
- p_fnum = PQfnumber(res,"p");
-
- for (i=0;i<3;i++) {
- printf("type[%d] = %d, size[%d] = %d\\n",
- i, PQftype(res,i),
- i, PQfsize(res,i));
- }
- for (i=0; i < PQntuples(res); i++) {
- int *ival;
- float *dval;
- int plen;
- POLYGON* pval;
- /* we hard-wire this to the 3 fields we know about */
- ival = (int*)PQgetvalue(res,i,i_fnum);
- dval = (float*)PQgetvalue(res,i,d_fnum);
- plen = PQgetlength(res,i,p_fnum);
-
- /* plen doesn't include the length field so need to increment by VARHDSZ*/
- pval = (POLYGON*) malloc(plen + VARHDRSZ);
- pval->size = plen;
- memmove((char*)&pval->npts, PQgetvalue(res,i,p_fnum), plen);
- printf("tuple %d: got\\n", i);
- printf(" i = (%d bytes) %d,\\n",
- PQgetlength(res,i,i_fnum), *ival);
- printf(" d = (%d bytes) %f,\\n",
- PQgetlength(res,i,d_fnum), *dval);
- printf(" p = (%d bytes) %d points \\tboundbox = (hi=%f/%f, lo = %f,%f)\\n",
- PQgetlength(res,i,d_fnum),
- pval->npts,
- pval->boundbox.xh,
- pval->boundbox.yh,
- pval->boundbox.xl,
- pval->boundbox.yl);
- }
-
- PQclear(res);
-
- /* close the cursor */
- res = PQexec(conn, "CLOSE mycursor");
- PQclear(res);
-
- /* commit the transaction */
- res = PQexec(conn, "COMMIT");
- PQclear(res);
-
- /* close the connection to the database and cleanup */
- PQfinish(conn);
+
+ /* close the cursor */
+ res = PQexec(conn, "CLOSE mycursor");
+ PQclear(res);
+
+ /* commit the transaction */
+ res = PQexec(conn, "COMMIT");
+ PQclear(res);
+
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
}
.fi
-