Add PQsetdbLogin() and cleanup.

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
@@ -654,23 +685,30 @@ exit_nicely(PGconn* conn)
 
 main()
 {
-  char *pghost, *pgport, *pgoptions, *pgtty;
+    char       *pghost,
+               *pgport,
+               *pgoptions,
+               *pgtty;
     char       *dbName;
     int         nFields;
-  int i,j;
+    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
+     * begin, by setting the parameters for a backend connection if the
-     reasonable defaults by looking up environment variables 
+     * parameters are null, then the system will try to use reasonable
-     or, failing that, using hardwired constants */
+     * 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 */
+    pgoptions = NULL;           /* special options to start up the backend
+                                 * server */
     pgtty = NULL;               /* debugging tty for the backend server */
     dbName = "template1";
 
@@ -678,7 +716,8 @@ main()
     conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
 
     /* check to see that the backend connection was successfully made */
-  if (PQstatus(conn) == CONNECTION_BAD) {
+    if (PQstatus(conn) == CONNECTION_BAD)
+    {
         fprintf(stderr, "Connection to database '%s' failed.\\n", dbName);
         fprintf(stderr, "%s", PQerrorMessage(conn));
         exit_nicely(conn);
@@ -689,18 +728,26 @@ main()
 
     /* start a transaction block */
     res = PQexec(conn, "BEGIN");
-  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
+    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 */
+    /*
+     * 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*/
+    /*
+     * 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) {
+    if (PQresultStatus(res) != PGRES_COMMAND_OK)
+    {
         fprintf(stderr, "DECLARE CURSOR command failed\\n");
         PQclear(res);
         exit_nicely(conn);
@@ -708,7 +755,8 @@ main()
     PQclear(res);
 
     res = PQexec(conn, "FETCH ALL in mycursor");
-  if (PQresultStatus(res) != PGRES_TUPLES_OK) {
+    if (PQresultStatus(res) != PGRES_TUPLES_OK)
+    {
         fprintf(stderr, "FETCH ALL command didn't return tuples properly\\n");
         PQclear(res);
         exit_nicely(conn);
@@ -716,16 +764,15 @@ main()
 
     /* first, print out the attribute names */
     nFields = PQnfields(res);
-  for (i=0; i < nFields; i++) {
+    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 (i = 0; i < PQntuples(res); i++)
-    for (j=0  ; j < nFields; j++) {
+    {
+        for (j = 0; j < nFields; j++)
             printf("%-15s", PQgetvalue(res, i, j));
-    }
         printf("\\n");
     }
 
@@ -744,6 +791,7 @@ main()
 
 /*   fclose(debug); */
 }
+
 .fi
 .bp
 .SH "Sample Program 2"
@@ -772,7 +820,8 @@ 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);
@@ -780,53 +829,68 @@ void exit_nicely(PGconn* conn)
 
 main()
 {
-  char *pghost, *pgport, *pgoptions, *pgtty;
+    char       *pghost,
+               *pgport,
+               *pgoptions,
+               *pgtty;
     char       *dbName;
     int         nFields;
-  int i,j;
+    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
+     * begin, by setting the parameters for a backend connection if the
-     reasonable defaults by looking up environment variables 
+     * parameters are null, then the system will try to use reasonable
-     or, failing that, using hardwired constants */
+     * 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 */
+    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*/
+    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) {
+    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) {
+    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 */
+    /*
+     * should PQclear PGresult whenever it is no longer needed to avoid
+     * memory leaks
+     */
     PQclear(res);
 
-  while (1) {
+    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) {
+        if (notify)
+        {
             fprintf(stderr,
                 "ASYNC NOTIFY of '%s' from backend pid '%d' received\\n",
                     notify->relname, notify->be_pid);
@@ -840,6 +904,7 @@ main()
     PQfinish(conn);
 
 }
+
 .fi
 .bp
 .SH "Sample Program 3"
@@ -877,7 +942,8 @@ tuple 1: got
 #include "libpq-fe.h"
 #include "utils/geo-decls.h"    /* for the POLYGON type */
 
-void exit_nicely(PGconn* conn)
+void
+exit_nicely(PGconn *conn)
 {
     PQfinish(conn);
     exit(1);
@@ -885,31 +951,42 @@ void exit_nicely(PGconn* conn)
 
 main()
 {
-  char *pghost, *pgport, *pgoptions, *pgtty;
+    char       *pghost,
+               *pgport,
+               *pgoptions,
+               *pgtty;
     char       *dbName;
     int         nFields;
-  int i,j;
+    int         i,
-  int i_fnum, d_fnum, p_fnum;
+                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
+     * begin, by setting the parameters for a backend connection if the
-     reasonable defaults by looking up environment variables 
+     * parameters are null, then the system will try to use reasonable
-     or, failing that, using hardwired constants */
+     * 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 */
+    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*/
+    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) {
+    if (PQstatus(conn) == CONNECTION_BAD)
+    {
         fprintf(stderr, "Connection to database '%s' failed.\\n", dbName);
         fprintf(stderr, "%s", PQerrorMessage(conn));
         exit_nicely(conn);
@@ -917,18 +994,26 @@ main()
 
     /* start a transaction block */
     res = PQexec(conn, "BEGIN");
-  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
+    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 */
+    /*
+     * 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*/
+    /*
+     * 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) {
+    if (PQresultStatus(res) != PGRES_COMMAND_OK)
+    {
         fprintf(stderr, "DECLARE CURSOR command failed\\n");
         PQclear(res);
         exit_nicely(conn);
@@ -936,7 +1021,8 @@ main()
     PQclear(res);
 
     res = PQexec(conn, "FETCH ALL in mycursor");
-  if (PQresultStatus(res) != PGRES_TUPLES_OK) {
+    if (PQresultStatus(res) != PGRES_TUPLES_OK)
+    {
         fprintf(stderr, "FETCH ALL command didn't return tuples properly\\n");
         PQclear(res);
         exit_nicely(conn);
@@ -946,22 +1032,28 @@ main()
     d_fnum = PQfnumber(res, "d");
     p_fnum = PQfnumber(res, "p");
 
-  for (i=0;i<3;i++) {
+    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++) {
+    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*/
+        /*
+         * 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);
@@ -994,4 +1086,3 @@ main()
 
 }
 .fi
-