diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/man/libpq.3 | 589 |
1 files changed, 340 insertions, 249 deletions
diff --git a/src/man/libpq.3 b/src/man/libpq.3 index 1675a8ea7a3..e89e5ebc01c 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 - |