opensourcemirror
/
postgresql
mirror of git://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Releases Wiki Activity

What I've done: 

1. Rewritten libpq to allow asynchronous clients.

2. Implemented client side of cancel protocol in library,
   and patched psql.c to send a cancel request upon SIGINT.  The
   backend doesn't notice it yet :-(

3. Implemented 'Z' protocol message addition and renaming of
   copy in/out start messages.  These are implemented conditionally,
   ie, the client protocol version is checked; so the code should
   still work with 1.0 clients.

4. Revised protocol and libpq sgml documents (don't have an SGML
   compiler, though, so there may be some markup glitches here).


What remains to be done:

1. Implement addition of atttypmod field to RowDescriptor messages.
   The client-side code is there but ifdef'd out.  I have no idea
   what to change on the backend side.  The field should be sent
   only if protocol >= 2.0, of course.

2. Implement backend response to cancel requests received as OOB
   messages.  (This prolly need not be conditional on protocol
   version; just do it if you get SIGURG.)

3. Update libpq.3.  (I'm hoping this can be generated mechanically
   from libpq.sgml... if not, will do it by hand.)  Is there any
   other doco to fix?

4. Update non-libpq interfaces as necessary.  I patched libpgtcl
   so that it would compile, but haven't tested it.  Dunno what
   needs to be done with the other interfaces.

Have at it!

Tom Lane
This commit is contained in:
Bruce Momjian 1998-05-06 23:51:16 +00:00
parent 2e12331d42
commit edbd51395c
15 changed files with 2664 additions and 2146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

389
doc/src/sgml/libpq.sgml
View File

@ -128,7 +128,7 @@ PGconn *PQsetdb(char *pghost,
<ListItem>
<Para>
<Function>PQconndefaults</Function>
Returns the database name of the connection.
Returns the default connection options.
<ProgramListing>
PQconninfoOption *PQconndefaults(void)
@ -244,7 +244,7 @@ void PQfinish(PGconn *conn)
Reset the communication port with the backend.
This function will close the IPC socket connection
to the backend and attempt to reestablish a new
connection to the same backend.
connection to the same postmaster.
<ProgramListing>
void PQreset(PGconn *conn)
</ProgramListing>
@ -287,11 +287,12 @@ void PQuntrace(PGconn *conn);
<Para>
<Function>PQexec</Function>
Submit a query to <ProductName>Postgres</ProductName>. Returns a PGresult
pointer if the query was successful or a NULL otherwise. If a NULL is returned, PQerrorMessage can
be used to get more information about the error.
pointer or possibly a NULL pointer. If a NULL is returned, it
should be treated like a PGRES_FATAL_ERROR result: use
PQerrorMessage to get more information about the error.
<ProgramListing>
PGresult *PQexec(PGconn *conn,
char *query);
const char *query);
</ProgramListing>
The <Function>PGresult</Function> structure encapsulates the query
result returned by the backend. <Function>libpq</Function> programmers
@ -310,7 +311,7 @@ PGresult *PQexec(PGconn *conn,
Returns the result status of the query. PQresultStatus can return one of the following values:
<ProgramListing>
PGRES_EMPTY_QUERY,
PGRES_COMMAND_OK, /* the query was a command */
PGRES_COMMAND_OK, /* the query was a command returning no data */
PGRES_TUPLES_OK, /* the query successfully returned tuples */
PGRES_COPY_OUT,
PGRES_COPY_IN,
@ -391,7 +392,20 @@ Oid PQftype(PGresult *res,
returned is -1, the field is a variable length
field. Field indices start at 0.
<ProgramListing>
int2 PQfsize(PGresult *res,
short PQfsize(PGresult *res,
int field_index);
</ProgramListing>
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQfmod</Function>
Returns the type-specific modification data of the field
associated with the given field index.
Field indices start at 0.
<ProgramListing>
short PQfmod(PGresult *res,
int field_index);
</ProgramListing>
</Para>
@ -521,7 +535,6 @@ struct _PQprintOpt
<Function>PQprintTuples</Function>
Prints out all the tuples and, optionally, the
attribute names to the specified output stream.
The programs psql and monitor both use PQprintTuples for output.
<ProgramListing>
void PQprintTuples(PGresult* res,
FILE* fout, /* output stream */
@ -566,6 +579,207 @@ void PQclear(PQresult *res);
</Para>
</Sect1>
<Sect1>
<Title>Asynchronous Query Processing</Title>
<Para>
The PQexec function is adequate for submitting queries in simple synchronous
applications. It has a couple of major deficiencies however:
<Para>
<ItemizedList>
<ListItem>
<Para>
PQexec waits for the query to be completed. The application may have other
work to do (such as maintaining a user interface), in which case it won't
want to block waiting for the response.
</Para>
</ListItem>
<ListItem>
<Para>
Since control is buried inside PQexec, there is no way for the frontend
to decide it would like to try to cancel the ongoing query.
</Para>
</ListItem>
<ListItem>
<Para>
PQexec can return only one PGresult structure. If the submitted query
string contains multiple SQL commands, all but the last PGresult are
discarded by PQexec.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
Applications that do not like these limitations can instead use the
underlying functions that PQexec is built from: PQsendQuery and
PQgetResult.
<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQsendQuery</Function>
Submit a query to <ProductName>Postgres</ProductName> without
waiting for the result(s). TRUE is returned if the query was
successfully dispatched, FALSE if not (in which case, use
PQerrorMessage to get more information about the failure).
<ProgramListing>
int PQsendQuery(PGconn *conn,
const char *query);
</ProgramListing>
After successfully calling PQsendQuery, call PQgetResult one or more
times to obtain the query results. PQsendQuery may not be called
again (on the same connection) until PQgetResult has returned NULL,
indicating that the query is done.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQgetResult</Function>
Wait for the next result from a prior PQsendQuery,
and return it. NULL is returned when the query is complete
and there will be no more results.
<ProgramListing>
PGresult *PQgetResult(PGconn *conn);
</ProgramListing>
PQgetResult must be called repeatedly until it returns NULL,
indicating that the query is done. (If called when no query is
active, PQgetResult will just return NULL at once.)
Each non-null result from PQgetResult should be processed using
the same PGresult accessor functions previously described.
Don't forget to free each result object with PQclear when done with it.
Note that PQgetResult will block only if a query is active and the
necessary response data has not yet been read by PQconsumeInput.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
Using PQsendQuery and PQgetResult solves one of PQexec's problems:
if a query string contains multiple SQL commands, the results of those
commands can be obtained individually. (This allows a simple form of
overlapped processing, by the way: the frontend can be handling the
results of one query while the backend is still working on later
queries in the same query string.) However, calling PQgetResult will
still cause the frontend to block until the backend completes the
next SQL command. This can be avoided by proper use of three more
functions:
<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQconsumeInput</Function>
If input is available from the backend, consume it.
<ProgramListing>
void PQconsumeInput(PGconn *conn);
</ProgramListing>
No direct return value is available from PQconsumeInput, but
after calling it, the application may check PQisBusy and/or
PQnotifies to see if their state has changed.
PQconsumeInput may be called even if the application is not
prepared to deal with a result or notification just yet.
It will read available data and save it in a buffer, thereby
causing a select(2) read-ready indication to go away. The
application can thus use PQconsumeInput to clear the select
condition immediately, and then examine the results at leisure.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQisBusy</Function>
Returns TRUE if a query is busy, that is, PQgetResult would block
waiting for input. A FALSE return indicates that PQgetResult can
be called with assurance of not blocking.
<ProgramListing>
int PQisBusy(PGconn *conn);
</ProgramListing>
PQisBusy will not itself attempt to read data from the backend;
therefore PQconsumeInput must be invoked first, or the busy
state will never end.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQsocket</Function>
Obtain the file descriptor number for the backend connection socket.
A valid descriptor will be >= 0; a result of -1 indicates that
no backend connection is currently open.
<ProgramListing>
int PQsocket(PGconn *conn);
</ProgramListing>
PQsocket should be used to obtain the backend socket descriptor
in preparation for executing select(2). This allows an application
to wait for either backend responses or other conditions.
If the result of select(2) indicates that data can be read from
the backend socket, then PQconsumeInput should be called to read the
data; after which, PQisBusy, PQgetResult, and/or PQnotifies can be
used to process the response.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
A typical frontend using these functions will have a main loop that uses
select(2) to wait for all the conditions that it must respond to. One of
the conditions will be input available from the backend, which in select's
terms is readable data on the file descriptor identified by PQsocket.
When the main loop detects input ready, it should call PQconsumeInput
to read the input. It can then call PQisBusy, followed by PQgetResult
if PQisBusy returns FALSE. It can also call PQnotifies to detect NOTIFY
messages (see "Asynchronous Notification", below). An example is given
in the sample programs section.
<Para>
A frontend that uses PQsendQuery/PQgetResult can also attempt to cancel
a query that is still being processed by the backend.
<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQrequestCancel</Function>
Request that <ProductName>Postgres</ProductName> abandon
processing of the current query.
<ProgramListing>
int PQrequestCancel(PGconn *conn);
</ProgramListing>
The return value is TRUE if the cancel request was successfully
dispatched, FALSE if not. (If not, PQerrorMessage tells why not.)
Successful dispatch is no guarantee that the request will have any
effect, however. Regardless of the return value of PQrequestCancel,
the application must continue with the normal result-reading
sequence using PQgetResult. If the cancellation
is effective, the current query will terminate early and return
an error result. If the cancellation fails (say because the
backend was already done processing the query), then there will
be no visible result at all.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
Note that if the current query is part of a transaction, cancellation
will abort the whole transaction.
<Para>
The current implementation of cancel requests uses "out of band" messages.
This feature is supported only on TCP/IP connections. If the backend
communication is being done through a Unix socket, PQrequestCancel will
always fail.
</Sect1>
<Sect1>
<Title>Fast Path</Title>
@ -617,48 +831,60 @@ typedef struct {
<Title>Asynchronous Notification</Title>
<Para>
<ProductName>Postgres</ProductName> supports asynchronous notification via the
LISTEN and NOTIFY commands. A backend registers its
interest in a particular relation with the LISTEN command. All backends listening on a particular relation
will be notified asynchronously when a NOTIFY of that
relation name is executed by another backend. No
additional information is passed from the notifier to
the listener. Thus, typically, any actual data that
needs to be communicated is transferred through the
relation.
<FileName>libpq</FileName> applications are notified whenever a connected
backend has received an asynchronous notification.
However, the communication from the backend to the
frontend is not asynchronous. Notification comes
piggy-backed on other query results. Thus, an application must submit queries, even empty ones, in order to
receive notice of backend notification. In effect, the
<FileName>libpq</FileName> application must poll the backend to see if there
is any pending notification information. After the
execution of a query, a frontend may call PQNotifies to
see if any notification data is available from the
backend.
</Para>
<ProductName>Postgres</ProductName> supports asynchronous notification via the
LISTEN and NOTIFY commands. A backend registers its interest in a particular
notification condition with the LISTEN command. All backends listening on a
particular condition will be notified asynchronously when a NOTIFY of that
condition name is executed by any backend. No additional information is
passed from the notifier to the listener. Thus, typically, any actual data
that needs to be communicated is transferred through a database relation.
Commonly the condition name is the same as the associated relation, but it is
not necessary for there to be any associated relation.
<Para>
<FileName>libpq</FileName> applications submit LISTEN commands as ordinary
SQL queries. Subsequently, arrival of NOTIFY messages can be detected by
calling PQnotifies().
<Para>
<ItemizedList>
<ListItem>
<Para>
<Function>PQNotifies</Function>
returns the notification from a list of unhandled
notifications from the backend. Returns NULL if
there are no pending notifications from the backend. PQNotifies behaves like the popping of a
stack. Once a notification is returned from PQnotifies, it is considered handled and will be
removed from the list of notifications.
<Function>PQnotifies</Function>
Returns the next notification from a list of unhandled
notification messages received from the backend. Returns NULL if
there are no pending notifications. PQnotifies behaves like the
popping of a stack. Once a notification is returned from
PQnotifies, it is considered handled and will be removed from the
list of notifications.
<ProgramListing>
PGnotify* PQNotifies(PGconn *conn);
PGnotify* PQnotifies(PGconn *conn);
</ProgramListing>
The second sample program gives an example of the use
of asynchronous notification.
After processing a PGnotify object returned by PQnotifies,
be sure to free it with free() to avoid a memory leak.
The second sample program gives an example of the use
of asynchronous notification.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
PQnotifies() does not actually read backend data; it just returns messages
previously absorbed by another <FileName>libpq</FileName> function. In prior
releases of <FileName>libpq</FileName>, the only way to ensure timely receipt
of NOTIFY messages was to constantly submit queries, even empty ones, and then
check PQnotifies() after each PQexec(). While this still works, it is
deprecated as a waste of processing power. A better way to check for NOTIFY
messages when you have no useful queries to make is to call PQconsumeInput(),
then check PQnotifies(). You can use select(2) to wait for backend data to
arrive, thereby using no CPU power unless there is something to do. Note that
this will work OK whether you use PQsendQuery/PQgetResult or plain old PQexec
for queries. You should, however, remember to check PQnotifies() after each
PQgetResult or PQexec to see if any notifications came in during the
processing of the query.
</Para>
</Sect1>
<Sect1>
@ -671,6 +897,11 @@ PGnotify* PQNotifies(PGconn *conn);
advantage of this capability.
</Para>
<Para>
These functions should be executed only after obtaining a PGRES_COPY_OUT
or PGRES_COPY_IN result object from PQexec or PQgetResult.
</Para>
<Para>
<ItemizedList>
<ListItem>
@ -685,7 +916,7 @@ PGnotify* PQNotifies(PGconn *conn);
has been read, and 1 if the buffer is full but the
terminating newline has not yet been read.
Notice that the application must check to see if a
new line consists of the single character ".",
new line consists of the two characters "\.",
which indicates that the backend server has finished sending the results of the copy command.
Therefore, if the application ever expects to
receive lines that are more than length-1 characters long, the application must be sure to check
@ -708,8 +939,8 @@ int PQgetline(PGconn *conn,
<Function>PQputline</Function>
Sends a null-terminated string to the backend
server.
The application must explicitly send the single
character "." to indicate to the backend that it
The application must explicitly send the two
characters "\." on a final line to indicate to the backend that it
has finished sending its data.
<ProgramListing>
void PQputline(PGconn *conn,
@ -736,18 +967,35 @@ void PQputline(PGconn *conn,
int PQendcopy(PGconn *conn);
</ProgramListing>
<ProgramListing>
PQexec(conn, "create table foo (a int4, b text, d float8)");
PQexec(conn, "create table foo (a int4, b char16, d float8)");
PQexec(conn, "copy foo from stdin");
PQputline(conn, "3&lt;TAB&gt;hello world&lt;TAB&gt;4.5\n");
PQputline(conn,"4&lt;TAB&gt;goodbye world&lt;TAB&gt;7.11\n");
...
PQputline(conn,".\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>
@ -833,7 +1081,7 @@ void fe_setauthsvc(char *name,
<Para>
The query buffer is 8192 bytes long, and queries over
that length will be silently truncated.
that length will be rejected.
</Para>
</Sect1>
@ -888,7 +1136,7 @@ void fe_setauthsvc(char *name,
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '&percnt;s' failed.0, dbName);
fprintf(stderr,"Connection to database '&percnt;s' failed.\n", dbName);
fprintf(stderr,"&percnt;s",PQerrorMessage(conn));
exit_nicely(conn);
}
@ -900,7 +1148,7 @@ void fe_setauthsvc(char *name,
res = PQexec(conn,"BEGIN");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"BEGIN command failed0);
fprintf(stderr,"BEGIN command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -911,7 +1159,7 @@ void fe_setauthsvc(char *name,
/* fetch instances from the pg_database, the system catalog of databases*/
res = PQexec(conn,"DECLARE myportal CURSOR FOR select * from pg_database");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"DECLARE CURSOR command failed0);
fprintf(stderr,"DECLARE CURSOR command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -919,7 +1167,7 @@ void fe_setauthsvc(char *name,
res = PQexec(conn,"FETCH ALL in myportal");
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
fprintf(stderr,"FETCH ALL command didn't return tuples properly0);
fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
PQclear(res);
exit_nicely(conn);
}
@ -929,14 +1177,14 @@ void fe_setauthsvc(char *name,
for (i=0; i &lt; nFields; i++) {
printf("&percnt;-15s",PQfname(res,i));
}
printf("0);
printf("\n");
/* next, print out the instances */
for (i=0; i &lt; PQntuples(res); i++) {
for (j=0 ; j &lt; nFields; j++) {
printf("&percnt;-15s", PQgetvalue(res,i,j));
}
printf("0);
printf("\n");
}
PQclear(res);
@ -1018,14 +1266,14 @@ void fe_setauthsvc(char *name,
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '&percnt;s' failed.0, dbName);
fprintf(stderr,"Connection to database '&percnt;s' failed.\n", dbName);
fprintf(stderr,"&percnt;s",PQerrorMessage(conn));
exit_nicely(conn);
}
res = PQexec(conn, "LISTEN TBL2");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"LISTEN command failed0);
fprintf(stderr,"LISTEN command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -1034,20 +1282,19 @@ void fe_setauthsvc(char *name,
PQclear(res);
while (1) {
/* async notification only come back as a result of a query*/
/* we can send empty queries */
res = PQexec(conn, " ");
/* printf("res-&gt;status = &percnt;s0, pgresStatus[PQresultStatus(res)]); */
/* check for asynchronous returns */
notify = PQnotifies(conn);
if (notify) {
/* wait a little bit between checks;
* waiting with select() would be more efficient.
*/
sleep(1);
/* collect any asynchronous backend messages */
PQconsumeInput(conn);
/* check for asynchronous notify messages */
while ((notify = PQnotifies(conn)) != NULL) {
fprintf(stderr,
"ASYNC NOTIFY of '&percnt;s' from backend pid '&percnt;d' received0,
"ASYNC NOTIFY of '&percnt;s' from backend pid '&percnt;d' received\n",
notify-&gt;relname, notify-&gt;be_pid);
free(notify);
break;
}
PQclear(res);
}
/* close the connection to the database and cleanup */
@ -1128,7 +1375,7 @@ void fe_setauthsvc(char *name,
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '&percnt;s' failed.0, dbName);
fprintf(stderr,"Connection to database '&percnt;s' failed.\n", dbName);
fprintf(stderr,"&percnt;s",PQerrorMessage(conn));
exit_nicely(conn);
}
@ -1136,7 +1383,7 @@ void fe_setauthsvc(char *name,
/* start a transaction block */
res = PQexec(conn,"BEGIN");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"BEGIN command failed0);
fprintf(stderr,"BEGIN command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -1147,7 +1394,7 @@ void fe_setauthsvc(char *name,
/* 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 failed0);
fprintf(stderr,"DECLARE CURSOR command failed\n");
PQclear(res);
exit_nicely(conn);
}
@ -1155,7 +1402,7 @@ void fe_setauthsvc(char *name,
res = PQexec(conn,"FETCH ALL in mycursor");
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
fprintf(stderr,"FETCH ALL command didn't return tuples properly0);
fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
PQclear(res);
exit_nicely(conn);
}
@ -1165,7 +1412,7 @@ void fe_setauthsvc(char *name,
p_fnum = PQfnumber(res,"p");
for (i=0;i&lt;3;i++) {
printf("type[&percnt;d] = &percnt;d, size[&percnt;d] = &percnt;d0,
printf("type[&percnt;d] = &percnt;d, size[&percnt;d] = &percnt;d\n",
i, PQftype(res,i),
i, PQfsize(res,i));
}
@ -1183,12 +1430,12 @@ void fe_setauthsvc(char *name,
pval = (POLYGON*) malloc(plen + VARHDRSZ);
pval-&gt;size = plen;
memmove((char*)&amp;pval-&gt;npts, PQgetvalue(res,i,p_fnum), plen);
printf("tuple &percnt;d: got0, i);
printf(" i = (&percnt;d bytes) &percnt;d,0,
printf("tuple &percnt;d: got\n", i);
printf(" i = (&percnt;d bytes) &percnt;d,\n",
PQgetlength(res,i,i_fnum), *ival);
printf(" d = (&percnt;d bytes) &percnt;f,0,
printf(" d = (&percnt;d bytes) &percnt;f,\n",
PQgetlength(res,i,d_fnum), *dval);
printf(" p = (&percnt;d bytes) &percnt;d points boundbox = (hi=&percnt;f/&percnt;f, lo = &percnt;f,&percnt;f)0,
printf(" p = (&percnt;d bytes) &percnt;d points boundbox = (hi=&percnt;f/&percnt;f, lo = &percnt;f,&percnt;f)\n",
PQgetlength(res,i,d_fnum),
pval-&gt;npts,
pval-&gt;boundbox.xh,

281
doc/src/sgml/protocol.sgml
View File

@ -4,14 +4,15 @@
<FirstName>Phil</FirstName>
<Surname>Thompson</Surname>
</Author>
<Date>1998-02-02</Date>
<Date>1998-05-04</Date>
</DocInfo>
<Title>Frontend/Backend Protocol</Title>
<Para>
<Note>
<Para>
Written by <ULink url="mailto:phil@river-bank.demon.co.uk">Phil Thompson</ULink>
Written by <ULink url="mailto:phil@river-bank.demon.co.uk">Phil Thompson</ULink>.
Updates for protocol 2.0 by <ULink url="mailto:tgl@sss.pgh.pa.us">Tom Lane</ULink>.
</Para>
</Note>
@ -24,7 +25,7 @@ a way as to still allow connections from earlier versions of frontends, but
this document does not cover the protocol used by those earlier versions.
<Para>
This document describes the initial version-numbered protocol, designated v1.0.
This document describes version 2.0 of the protocol.
Higher level features built on this protocol (for example, how <FileName>libpq</FileName> passes
certain environment variables after the connection is established)
are covered elsewhere.
@ -47,7 +48,9 @@ and responds to the frontend accordingly.
<Para>
The frontend then sends any required authentication information. Once the
postmaster validates this it responds to the frontend that it is authenticated
and hands over to a backend.
and hands over the connection to a backend. The backend then sends a message
indicating successful startup (normal case) or failure (for example, an
invalid database name).
<Para>
Subsequent communications are query and result packets exchanged between the
@ -60,7 +63,7 @@ closes the connection without waiting for a response for the backend.
<Para>
Packets are sent as a data stream. The first byte determines what should be
expected in the rest of the packet. The exception is packets send from a
expected in the rest of the packet. The exception is packets sent from a
frontend to the postmaster, which comprise a packet length then the packet
itself. The difference is historical.
@ -70,15 +73,22 @@ itself. The difference is historical.
<Para>
This section describes the message flow. There are four different types of
flows depending on the state of the connection:
authentication, query, function call, and termination.
startup, query, function call, and termination.
There are also special provisions for notification responses and command
cancellation, which can occur at any time after the startup phase.
<Sect2>
<Title>Authentication</Title>
<Title>Startup</Title>
<Para>
The frontend sends a StartupPacket. The postmaster uses this and the contents
of the pg_hba.conf(5) file to determine what authentication method the frontend
must use. The postmaster then responds with one of the following messages:
Startup is divided into an authentication phase and a backend startup phase.
<Para>
Initially, the frontend sends a StartupPacket. The postmaster uses this info
and the contents of the pg_hba.conf(5) file to determine what authentication
method the frontend must use. The postmaster then responds with one of the
following messages:
<Para>
<VariableList>
@ -162,13 +172,65 @@ must use. The postmaster then responds with one of the following messages:
If the frontend does not support the authentication method requested by the
postmaster, then it should immediately close the connection.
<Para>
After sending AuthenticationOk, the postmaster attempts to launch a backend
process. Since this might fail, or the backend might encounter a failure
during startup, the frontend must wait for the backend to acknowledge
successful startup. The frontend should send no messages at this point.
The possible messages from the backend during this phase are:
<Para>
<VariableList>
<VarListEntry>
<Term>
ReadyForQuery
</Term>
<ListItem>
<Para>
Backend startup is successful. The frontend may now issue
query or function call messages.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
ErrorResponse
</Term>
<ListItem>
<Para>
Backend startup failed. The connection is closed after
sending this message.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
NoticeResponse
</Term>
<ListItem>
<Para>
A warning message has been issued. The frontend should
display the message but continue listening for ReadyForQuery
or ErrorResponse.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
<Sect2>
<Title>Query</Title>
<Para>
The frontend sends a Query message to the backend. The response sent by the
backend depends on the contents of the query. The possible responses are as
follows.
A Query cycle is initiated by the frontend sending a Query message to the
backend. The backend then sends one or more response messages depending
on the contents of the query command string, and finally a ReadyForQuery
response message. ReadyForQuery informs the frontend that it may safely
send a new query or function call.
<Para>
The possible response messages from the backend are:
<Para>
<VariableList>
@ -178,7 +240,7 @@ follows.
</Term>
<ListItem>
<Para>
The query completed normally.
An SQL command completed normally.
</Para>
</ListItem>
</VarListEntry>
@ -240,7 +302,7 @@ follows.
<Para>
For a fetch(l) or select(l) command, the backend sends a
RowDescription message. This is then followed by an AsciiRow
or BinaryRow message (depending on if a binary cursor was
or BinaryRow message (depending on whether a binary cursor was
specified) for each row being returned to the frontend.
Finally, the backend sends a CompletedResponse message with a
tag of "SELECT".
@ -253,7 +315,8 @@ follows.
</Term>
<ListItem>
<Para>
The query was empty.
An empty query string was recognized. (The need to specially
distinguish this case is historical.)
</Para>
</ListItem>
</VarListEntry>
@ -268,6 +331,21 @@ follows.
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
ReadyForQuery
</Term>
<ListItem>
<Para>
Processing of the query string is complete. A separate
message is sent to indicate this because the query string
may contain multiple SQL commands. (CompletedResponse marks
the end of processing one SQL command, not the whole string.)
ReadyForQuery will always be sent, whether processing
terminates successfully or with an error.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
NoticeResponse
</Term>
@ -275,20 +353,7 @@ follows.
<Para>
A warning message has been issued in relation to the query.
Notices are in addition to other responses, ie. the backend
will send another response message immediately afterwards.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
NotificationResponse
</Term>
<ListItem>
<Para>
A notify(l) command has been executed for a relation for
which a previous listen(l) command was executed. Notifications
are in addition to other responses, ie. the backend will send
another response message immediately afterwards.
will continue processing the command.
</Para>
</ListItem>
</VarListEntry>
@ -297,15 +362,23 @@ follows.
<Para>
A frontend must be prepared to accept ErrorResponse and NoticeResponse
messages whenever it is expecting any other type of message.
messages whenever it is expecting any other type of message. Also,
if it issues any listen(l) commands then it must be prepared to accept
NotificationResponse messages at any time; see below.
<Sect2>
<Title>Function Call</Title>
<Para>
The frontend sends a FunctionCall message to the backend. The response sent by
the backend depends on the result of the function call. The possible responses
are as follows.
A Function Call cycle is initiated by the frontend sending a FunctionCall
message to the backend. The backend then sends one or more response messages
depending on the results of the function call, and finally a ReadyForQuery
response message. ReadyForQuery informs the frontend that it may safely send
a new query or function call.
<Para>
The possible response messages from the backend are:
<Para>
<VariableList>
@ -340,15 +413,27 @@ are as follows.
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
ReadyForQuery
</Term>
<ListItem>
<Para>
Processing of the function call is complete.
ReadyForQuery will always be sent, whether processing
terminates successfully or with an error.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
NoticeResponse
</Term>
<ListItem>
<Para>
A warning message has been issued in relation to the function
call. Notices are in addition to other responses, ie. the
backend will send another response message immediately
afterwards.
call.
Notices are in addition to other responses, ie. the backend
will continue processing the command.
</Para>
</ListItem>
</VarListEntry>
@ -357,7 +442,58 @@ are as follows.
<Para>
A frontend must be prepared to accept ErrorResponse and NoticeResponse
messages whenever it is expecting any other type of message.
messages whenever it is expecting any other type of message. Also,
if it issues any listen(l) commands then it must be prepared to accept
NotificationResponse messages at any time; see below.
<Sect2>
<Title>Notification Responses</Title>
<Para>
If a frontend issues a listen(l) command, then the backend will send a
NotificationResponse message (not to be confused with NoticeResponse!)
whenever a notify(l) command is executed for the same relation name.
<Para>
Notification responses are permitted at any point in the protocol (after
startup), except within another backend message. Thus, the frontend
must be prepared to recognize a NotificationResponse message whenever it is
expecting any message. Indeed, it should be able to handle
NotificationResponse messages even when it is not engaged in a query.
<Para>
<VariableList>
<VarListEntry>
<Term>
NotificationResponse
</Term>
<ListItem>
<Para>
A notify(l) command has been executed for a relation for
which a previous listen(l) command was executed. Notifications
may be sent at any time.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
<Sect2>
<Title>Cancelling Requests in Progress</Title>
<Para>
During the processing of a query, the frontend may request cancellation of the
query by sending a single byte of OOB (out-of-band) data. The contents of the
data byte should be zero (although the backend does not currently check this).
If the cancellation is effective, it results in the current command being
terminated with an error message. Note that the backend makes no specific
reply to the cancel request itself. If the cancel request is ineffective
(say, because it arrived after processing was complete) then it will have
no visible effect at all. Thus, the frontend must continue with its normal
processing of query cycle responses after issuing a cancel request.
<Sect2>
<Title>Termination</Title>
@ -409,7 +545,7 @@ This section describes the base data types used in messages.
<Para>
A conventional C '\0' terminated string with no length
limitation. A frontend should always read the full string
even though it may have to discard characters if it's buffers
even though it may have to discard characters if its buffers
aren't big enough.
<Note>
<Para>
@ -458,8 +594,9 @@ AsciiRow (B)
</Term>
<ListItem>
<Para>
Identifies the message, in the context in which it is sent (see
CopyInResponse), as an <Acronym>ASCII</Acronym> row.
Identifies the message as an <Acronym>ASCII</Acronym> data row.
(A prior RowDescription message defines the number of
fields in the row and their data types.)
</Para>
</ListItem>
</VarListEntry>
@ -704,8 +841,9 @@ BinaryRow (B)
</Term>
<ListItem>
<Para>
Identifies the message, in the context in which it is sent (see
CopyOutResponse), as a binary row.
Identifies the message as a binary data row.
(A prior RowDescription message defines the number of
fields in the row and their data types.)
</Para>
</ListItem>
</VarListEntry>
@ -814,12 +952,12 @@ CopyInResponse (B)
<VariableList>
<VarListEntry>
<Term>
Byte1('D')
Byte1('G')
</Term>
<ListItem>
<Para>
Identifies the message, in the context in which it is sent (see
AsciiRow), as a copy in started response.
Identifies the message as a Start Copy In response.
The frontend must now send a CopyDataRows message.
</Para>
</ListItem>
</VarListEntry>
@ -839,12 +977,12 @@ CopyOutResponse (B)
<VariableList>
<VarListEntry>
<Term>
Byte1('B')
Byte1('H')
</Term>
<ListItem>
<Para>
Identifies the message, in the context in which it is sent (see
BinaryRow), as a copy out started response.
Identifies the message as a Start Copy Out response.
This message will be followed by a CopyDataRows message.
</Para>
</ListItem>
</VarListEntry>
@ -903,7 +1041,7 @@ EmptyQueryResponse (B)
</Term>
<ListItem>
<Para>
Identifies the message as an empty query response.
Identifies the message as a response to an empty query string.
</Para>
</ListItem>
</VarListEntry>
@ -954,6 +1092,31 @@ EncryptedPasswordPacket (F)
</VariableList>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
ReadyForQuery (B)
</Term>
<ListItem>
<Para>
<VariableList>
<VarListEntry>
<Term>
Byte1('Z')
</Term>
<ListItem>
<Para>
Identifies the message type. ReadyForQuery is sent
whenever the backend is ready for a new query cycle.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</ListItem>
</VarListEntry>
@ -1099,7 +1262,7 @@ FunctionResultResponse (B)
</Term>
<ListItem>
<Para>
Specifies that an actual result was returned.
Specifies that a nonempty result was returned.
</Para>
</ListItem>
</VarListEntry>
@ -1167,7 +1330,7 @@ FunctionVoidResponse (B)
</Term>
<ListItem>
<Para>
Specifies that no actual result was returned.
Specifies that an empty result was returned.
</Para>
</ListItem>
</VarListEntry>
@ -1269,7 +1432,7 @@ Query (F)
</Term>
<ListItem>
<Para>
Identifies the message as query.
Identifies the message as a query.
</Para>
</ListItem>
</VarListEntry>
@ -1279,7 +1442,7 @@ Query (F)
</Term>
<ListItem>
<Para>
The query itself.
The query string itself.
</Para>
</ListItem>
</VarListEntry>
@ -1348,6 +1511,16 @@ RowDescription (B)
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>
Int16
</Term>
<ListItem>
<Para>
Specifies the type modifier.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>

13
src/backend/commands/async.c
View File

@ -7,7 +7,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/backend/commands/async.c,v 1.31 1998/04/27 04:05:08 momjian Exp $
* $Header: /cvsroot/pgsql/src/backend/commands/async.c,v 1.32 1998/05/06 23:49:52 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -20,8 +20,7 @@
* end of commit),
* 2.a If the process is the same as the backend process that issued
* notification (we are notifying something that we are listening),
* signal the corresponding frontend over the comm channel using the
* out-of-band channel.
* signal the corresponding frontend over the comm channel.
* 2.b For all other listening processes, we send kill(2) to wake up
* the listening backend.
* 3. Upon receiving a kill(2) signal from another backend process notifying
@ -30,7 +29,7 @@
* 3.a We are sleeping, wake up and signal our frontend.
* 3.b We are in middle of another transaction, wait until the end of
* of the current transaction and signal our frontend.
* 4. Each frontend receives this notification and prcesses accordingly.
* 4. Each frontend receives this notification and processes accordingly.
*
* -- jw, 12/28/93
*
@ -547,12 +546,6 @@ Async_UnlistenOnExit(int code, /* from exitpg */
* Results:
* XXX
*
* Side effects:
*
* We make use of the out-of-band channel to transmit the
* notification to the front end. The actual data transfer takes
* place at the front end's request.
*
* --------------------------------------------------------------
*/
GlobalMemory notifyContext = NULL;

107
src/backend/tcop/dest.c
View File

@ -7,7 +7,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/backend/tcop/dest.c,v 1.17 1998/02/26 04:36:24 momjian Exp $
* $Header: /cvsroot/pgsql/src/backend/tcop/dest.c,v 1.18 1998/05/06 23:49:59 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -15,7 +15,8 @@
* INTERFACE ROUTINES
* BeginCommand - prepare destination for tuples of the given type
* EndCommand - tell destination that no more tuples will arrive
* NullCommand - tell dest that the last of a query sequence was processed
* NullCommand - tell dest that an empty query string was recognized
* ReadyForQuery - tell dest that we are ready for a new query
*
* NOTES
* These routines do the appropriate work before and after
@ -115,16 +116,10 @@ EndCommand(char *commandTag, CommandDest dest)
sprintf(buf, "%s%s", commandTag, CommandInfo);
CommandInfo[0] = 0;
pq_putstr(buf);
pq_flush();
break;
case Local:
case Debug:
break;
case CopyEnd:
pq_putnchar("Z", 1);
pq_flush();
break;
case None:
default:
break;
@ -139,28 +134,37 @@ EndCommand(char *commandTag, CommandDest dest)
*
* COPY rel FROM stdin
*
* NOTE: the message code letters are changed at protocol version 2.0
* to eliminate possible confusion with data tuple messages.
*/
void
SendCopyBegin(void)
{
pq_putnchar("B", 1);
/* pq_putint(0, 4); */
pq_flush();
if (PG_PROTOCOL_MAJOR(FrontendProtocol) >= 2)
pq_putnchar("H", 1); /* new way */
else
pq_putnchar("B", 1); /* old way */
}
void
ReceiveCopyBegin(void)
{
pq_putnchar("D", 1);
/* pq_putint(0, 4); */
if (PG_PROTOCOL_MAJOR(FrontendProtocol) >= 2)
pq_putnchar("G", 1); /* new way */
else
pq_putnchar("D", 1); /* old way */
/* We *must* flush here to ensure FE knows it can send. */
pq_flush();
}
/* ----------------
* NullCommand - tell dest that the last of a query sequence was processed
* NullCommand - tell dest that an empty query string was recognized
*
* Necessary to implement the hacky FE/BE interface to handle
* multiple-return queries.
* In FE/BE protocol version 1.0, this hack is necessary to support
* libpq's crufty way of determining whether a multiple-command
* query string is done. In protocol 2.0 it's probably not really
* necessary to distinguish empty queries anymore, but we still do it
* for backwards compatibility with 1.0.
* ----------------
*/
void
@ -168,46 +172,46 @@ NullCommand(CommandDest dest)
{
switch (dest)
{
case RemoteInternal:
case Remote:
case RemoteInternal:
case Remote:
{
#if 0
/*
* Do any asynchronous notification. If front end wants
* to poll, it can send null queries to call this
* function.
*/
PQNotifyList *nPtr;
MemoryContext orig;
if (notifyContext == NULL)
{
notifyContext = CreateGlobalMemory("notify");
}
orig = MemoryContextSwitchTo((MemoryContext) notifyContext);
for (nPtr = PQnotifies();
nPtr != NULL;
nPtr = (PQNotifyList *) SLGetSucc(&nPtr->Node))
{
pq_putnchar("A", 1);
pq_putint(0, sizeof(int4));
pq_putstr(nPtr->relname);
pq_putint(nPtr->be_pid, sizeof(nPtr->be_pid));
PQremoveNotify(nPtr);
}
pq_flush();
PQcleanNotify();/* garbage collect */
MemoryContextSwitchTo(orig);
#endif
/* ----------------
* tell the fe that the last of the queries has finished
* tell the fe that we saw an empty query string
* ----------------
*/
/* pq_putnchar("I", 1); */
pq_putstr("I");
/* pq_putint(0, 4); */
}
break;
case Local:
case Debug:
case None:
default:
break;
}
}
/* ----------------
* ReadyForQuery - tell dest that we are ready for a new query
*
* The ReadyForQuery message is sent in protocol versions 2.0 and up
* so that the FE can tell when we are done processing a query string.
*
* Note that by flushing the stdio buffer here, we can avoid doing it
* most other places and thus reduce the number of separate packets sent.
* ----------------
*/
void
ReadyForQuery(CommandDest dest)
{
switch (dest)
{
case RemoteInternal:
case Remote:
{
if (PG_PROTOCOL_MAJOR(FrontendProtocol) >= 2)
pq_putnchar("Z", 1);
/* Flush output at end of cycle in any case. */
pq_flush();
}
break;
@ -264,7 +268,6 @@ BeginCommand(char *pname,
* send fe info on tuples we're about to send
* ----------------
*/
pq_flush();
pq_putnchar("P", 1);/* new portal.. */
pq_putstr(pname); /* portal name */

3
src/backend/tcop/fastpath.c
View File

@ -7,7 +7,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/backend/tcop/fastpath.c,v 1.16 1998/04/26 04:07:22 momjian Exp $
* $Header: /cvsroot/pgsql/src/backend/tcop/fastpath.c,v 1.17 1998/05/06 23:50:10 momjian Exp $
*
* NOTES
* This cruft is the server side of PQfn.
@ -113,7 +113,6 @@ SendFunctionResult(Oid fid, /* function id */
}
pq_putnchar("0", 1);
pq_flush();
}
/*

12
src/backend/tcop/postgres.c
View File

@ -7,7 +7,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/backend/tcop/postgres.c,v 1.67 1998/02/26 04:36:31 momjian Exp $
* $Header: /cvsroot/pgsql/src/backend/tcop/postgres.c,v 1.68 1998/05/06 23:50:19 momjian Exp $
*
* NOTES
* this is the "main" module of the postgres backend and
@ -1302,7 +1302,7 @@ PostgresMain(int argc, char *argv[])
if (IsUnderPostmaster == false)
{
puts("\nPOSTGRES backend interactive interface");
puts("$Revision: 1.67 $ $Date: 1998/02/26 04:36:31 $");
puts("$Revision: 1.68 $ $Date: 1998/05/06 23:50:19 $");
}
/* ----------------
@ -1316,6 +1316,12 @@ PostgresMain(int argc, char *argv[])
for (;;)
{
/* ----------------
* (0) tell the frontend we're ready for a new query.
* ----------------
*/
ReadyForQuery(Remote);
/* ----------------
* (1) read a command.
* ----------------
@ -1391,8 +1397,8 @@ PostgresMain(int argc, char *argv[])
* ----------------
*/
case 'X':
IsEmptyQuery = true;
pq_close();
exitpg(0);
break;
default:

50
src/bin/psql/psql.c
View File

@ -7,7 +7,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/bin/psql/Attic/psql.c,v 1.139 1998/05/04 02:02:01 momjian Exp $
* $Header: /cvsroot/pgsql/src/bin/psql/Attic/psql.c,v 1.140 1998/05/06 23:50:23 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -283,6 +283,38 @@ PSQLexec(PsqlSettings *pset, char *query)
return NULL;
}
/*
* Code to support command cancellation.
* If interactive, we enable a SIGINT signal catcher that sends
* a cancel request to the backend.
* Note that sending the cancel directly from the signal handler
* is safe only because the cancel is sent as an OOB message.
* If it were inline data, then we'd risk inserting it into the
* middle of a normal data message by doing this.
* (It's probably not too cool to write on stderr, for that matter...
* but for debugging purposes we'll risk that.)
*/
static PGconn * cancelConn = NULL; /* connection to try cancel on */
static void
handle_sigint (SIGNAL_ARGS)
{
if (cancelConn == NULL)
exit(1); /* accept signal if no connection */
/* Try to send cancel request */
if (PQrequestCancel(cancelConn))
{
fprintf(stderr, "\nCANCEL request sent\n");
}
else
{
fprintf(stderr, "\nCannot send cancel request:\n%s\n",
PQerrorMessage(cancelConn));
}
}
/*
* listAllDbs
*
@ -1099,8 +1131,7 @@ SendQuery(bool *success_p, PsqlSettings *pset, const char *query,
exit(2); /* we are out'ta here */
}
/* check for asynchronous returns */
notify = PQnotifies(pset->db);
if (notify)
while ((notify = PQnotifies(pset->db)) != NULL)
{
fprintf(stderr,
"ASYNC NOTIFY of '%s' from backend pid '%d' received\n",
@ -1416,6 +1447,7 @@ do_connect(const char *new_dbname,
}
else
{
cancelConn = pset->db; /* redirect sigint's loving attentions */
PQfinish(olddb);
free(pset->prompt);
pset->prompt = malloc(strlen(PQdb(pset->db)) + 10);
@ -2462,11 +2494,18 @@ main(int argc, char **argv)
settings.opt.fieldSep = strdup(DEFAULT_FIELD_SEP);
settings.opt.pager = 1;
if (!isatty(0) || !isatty(1))
{
/* Noninteractive defaults */
settings.notty = 1;
#ifdef USE_READLINE
}
else
{
/* Interactive defaults */
pqsignal(SIGINT, handle_sigint); /* control-C => cancel */
#ifdef USE_READLINE
settings.useReadline = 1;
#endif
}
#ifdef PSQL_ALWAYS_GET_PASSWORDS
settings.getPassword = 1;
#else
@ -2580,6 +2619,9 @@ main(int argc, char **argv)
PQfinish(settings.db);
exit(1);
}
cancelConn = settings.db; /* enable SIGINT to send cancel */
if (listDatabases)
{
exit(listAllDbs(&settings));

4
src/include/libpq/pqcomm.h
View File

@ -6,7 +6,7 @@
*
* Copyright (c) 1994, Regents of the University of California
*
* $Id: pqcomm.h,v 1.24 1998/03/02 05:42:15 scrappy Exp $
* $Id: pqcomm.h,v 1.25 1998/05/06 23:50:32 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -66,7 +66,7 @@ typedef union SockAddr
/* The earliest and latest frontend/backend protocol version supported. */
#define PG_PROTOCOL_EARLIEST PG_PROTOCOL(0,0)
#define PG_PROTOCOL_LATEST PG_PROTOCOL(1,0)
#define PG_PROTOCOL_LATEST PG_PROTOCOL(2,0)
/*
* All packets sent to the postmaster start with the length. This is omitted

7
src/include/tcop/dest.h
View File

@ -26,7 +26,7 @@
*
* Copyright (c) 1994, Regents of the University of California
*
* $Id: dest.h,v 1.13 1998/02/26 04:43:39 momjian Exp $
* $Id: dest.h,v 1.14 1998/05/06 23:50:49 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -46,10 +46,6 @@ typedef enum
Debug, /* results go to debugging output */
Local, /* results go in local portal buffer */
Remote, /* results sent to frontend process */
CopyBegin, /* results sent to frontend process but
* are strings */
CopyEnd, /* results sent to frontend process but
* are strings */
RemoteInternal, /* results sent to frontend process in
* internal (binary) form */
SPI /* results sent to SPI manager */
@ -70,6 +66,7 @@ extern void EndCommand(char *commandTag, CommandDest dest);
extern void SendCopyBegin(void);
extern void ReceiveCopyBegin(void);
extern void NullCommand(CommandDest dest);
extern void ReadyForQuery(CommandDest dest);
extern void
BeginCommand(char *pname, int operation, TupleDesc attinfo,
bool isIntoRel, bool isIntoPortal, char *tag,

46
src/interfaces/libpgtcl/pgtclId.c
View File

@ -12,7 +12,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/interfaces/libpgtcl/Attic/pgtclId.c,v 1.8 1998/03/15 08:03:00 scrappy Exp $
* $Header: /cvsroot/pgsql/src/interfaces/libpgtcl/Attic/pgtclId.c,v 1.9 1998/05/06 23:51:00 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -48,7 +48,7 @@ int PgInputProc(DRIVER_INPUT_PROTO)
{
Pg_ConnectionId *connid;
PGconn *conn;
int c;
char c;
int avail;
connid = (Pg_ConnectionId *)cData;
@ -64,13 +64,24 @@ int PgInputProc(DRIVER_INPUT_PROTO)
return PgEndCopy(connid, errorCodePtr);
}
/* Try to load any newly arrived data */
errno = 0;
if (pqReadData(conn) < 0) {
*errorCodePtr = errno ? errno : EIO;
return -1;
}
/* Move data from libpq's buffer to tcl's */
conn->inCursor = conn->inStart;
avail = bufSize;
while (avail > 0 &&
(c = pqGetc(conn->Pfin, conn->Pfdebug)) != EOF) {
/* fprintf(stderr, "%d: got char %c\n", bufSize-avail, c); */
pqGetc(&c, conn) == 0) {
*buf++ = c;
--avail;
if (c == '\n' && bufSize-avail > 3) {
if (c == '\n' && bufSize-avail >= 3) {
if ((bufSize-avail == 3 || buf[-4] == '\n') &&
buf[-3] == '\\' && buf[-2] == '.') {
avail += 3;
@ -79,6 +90,8 @@ int PgInputProc(DRIVER_INPUT_PROTO)
}
}
}
/* Accept the data permanently */
conn->inStart = conn->inCursor;
/* fprintf(stderr, "returning %d chars\n", bufSize - avail); */
return bufSize - avail;
}
@ -100,16 +113,15 @@ int PgOutputProc(DRIVER_OUTPUT_PROTO)
return -1;
}
/*
fprintf(stderr, "PgOutputProc called: bufSize=%d: atend:%d <", bufSize,
strncmp(buf, "\\.\n", 3));
fwrite(buf, 1, bufSize, stderr);
fputs(">\n", stderr);
*/
fwrite(buf, 1, bufSize, conn->Pfout);
if (bufSize > 2 && strncmp(&buf[bufSize-3], "\\.\n", 3) == 0) {
/* fprintf(stderr,"checking closure\n"); */
fflush(conn->Pfout);
errno = 0;
if (pqPutnchar(buf, bufSize, conn)) {
*errorCodePtr = errno ? errno : EIO;
return -1;
}
if (bufSize >= 3 && strncmp(&buf[bufSize-3], "\\.\n", 3) == 0) {
(void) pqFlush(conn);
if (PgEndCopy(connid, errorCodePtr) == -1)
return -1;
}
@ -156,10 +168,10 @@ PgSetConnectionId(Tcl_Interp *interp, PGconn *conn)
for (i = 0; i < RES_START; i++) connid->results[i] = NULL;
Tcl_InitHashTable(&connid->notify_hash, TCL_STRING_KEYS);
sprintf(connid->id, "pgsql%d", fileno(conn->Pfout));
sprintf(connid->id, "pgsql%d", PQsocket(conn));
#if TCL_MAJOR_VERSION == 7 && TCL_MINOR_VERSION == 5
conn_chan = Tcl_CreateChannel(&Pg_ConnType, connid->id, conn->Pfin, conn->Pfout, (ClientData)connid);
conn_chan = Tcl_CreateChannel(&Pg_ConnType, connid->id, NULL, NULL, (ClientData)connid);
#else
conn_chan = Tcl_CreateChannel(&Pg_ConnType, connid->id, (ClientData)connid,
TCL_READABLE | TCL_WRITABLE);

12
src/interfaces/libpq/Makefile.in
View File

@ -7,7 +7,7 @@
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/src/interfaces/libpq/Attic/Makefile.in,v 1.16 1998/04/27 14:55:46 scrappy Exp $
# $Header: /cvsroot/pgsql/src/interfaces/libpq/Attic/Makefile.in,v 1.17 1998/05/06 23:51:06 momjian Exp $
#
#-------------------------------------------------------------------------
@ -25,14 +25,13 @@ ifdef KRBVERS
CFLAGS+= $(KRBFLAGS)
endif
OBJS= fe-auth.o fe-connect.o fe-exec.o fe-misc.o fe-lobj.o \
dllist.o pqsignal.o pqcomprim.o
OBJS= fe-auth.o fe-connect.o fe-exec.o fe-misc.o fe-print.o fe-lobj.o \
dllist.o pqsignal.o
# Shared library stuff
shlib :=
install-shlib-dep :=
ifeq ($(PORTNAME), linux)
LINUX_ELF=@LINUX_ELF@
ifdef LINUX_ELF
install-shlib-dep := install-shlib
shlib := libpq.so.$(SO_MAJOR_VERSION).$(SO_MINOR_VERSION)
@ -84,9 +83,6 @@ fe-lobj.o: $(SRCDIR)/backend/fmgr.h
dllist.c: $(SRCDIR)/backend/lib/dllist.c
-ln -s $(SRCDIR)/backend/lib/dllist.c .
pqcomprim.c: $(SRCDIR)/backend/libpq/pqcomprim.c
-ln -s $(SRCDIR)/backend/libpq/pqcomprim.c .
# The following rules cause dependencies in the backend directory to
# get made if they don't exist, but don't cause them to get remade if they
# are out of date.
@ -183,7 +179,7 @@ depend dep:
.PHONY: clean
clean:
rm -f libpq.a $(shlib) $(OBJS) c.h dllist.c pqcomprim.c libpq.so
rm -f libpq.a $(shlib) $(OBJS) c.h dllist.c libpq.so
ifeq (depend,$(wildcard depend))
include depend

625
src/interfaces/libpq/fe-connect.c
View File

@ -7,7 +7,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/interfaces/libpq/fe-connect.c,v 1.65 1998/04/21 04:00:06 scrappy Exp $
* $Header: /cvsroot/pgsql/src/interfaces/libpq/fe-connect.c,v 1.66 1998/05/06 23:51:11 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -41,14 +41,14 @@
#endif
/* use a local version instead of the one found in pqpacket.c */
static ConnStatusType connectDB(PGconn *conn);
static PGconn *makeEmptyPGconn(void);
static void freePGconn(PGconn *conn);
static void closePGconn(PGconn *conn);
static int conninfo_parse(const char *conninfo, char *errorMessage);
static char *conninfo_getval(char *keyword);
static void conninfo_free(void);
/* XXX Why is this not static? */
void PQsetenv(PGconn *conn);
#define NOTIFYLIST_INITIAL_SIZE 10
@ -162,44 +162,30 @@ PGconn *
PQconnectdb(const char *conninfo)
{
PGconn *conn;
char errorMessage[ERROR_MSG_LENGTH];
char *tmp;
/* ----------
* Allocate memory for the conn structure
* ----------
*/
conn = (PGconn *) malloc(sizeof(PGconn));
conn = makeEmptyPGconn();
if (conn == NULL)
{
fprintf(stderr,
"FATAL: PQsetdb() -- unable to allocate memory for a PGconn");
"FATAL: PQconnectdb() -- unable to allocate memory for a PGconn");
return (PGconn *) NULL;
}
MemSet((char *) conn, 0, sizeof(PGconn));
/* ----------
* Parse the conninfo string and get the fallback resources
* Parse the conninfo string and save settings in conn structure
* ----------
*/
if (conninfo_parse(conninfo, errorMessage) < 0)
if (conninfo_parse(conninfo, conn->errorMessage) < 0)
{
conn->status = CONNECTION_BAD;
strcpy(conn->errorMessage, errorMessage);
conninfo_free();
return conn;
}
/* ----------
* Setup the conn structure
* ----------
*/
conn->lobjfuncs = (PGlobjfuncs *) NULL;
conn->Pfout = NULL;
conn->Pfin = NULL;
conn->Pfdebug = NULL;
conn->notifyList = DLNewList();
tmp = conninfo_getval("host");
conn->pghost = tmp ? strdup(tmp) : NULL;
tmp = conninfo_getval("port");
@ -208,12 +194,12 @@ PQconnectdb(const char *conninfo)
conn->pgtty = tmp ? strdup(tmp) : NULL;
tmp = conninfo_getval("options");
conn->pgoptions = tmp ? strdup(tmp) : NULL;
tmp = conninfo_getval("dbname");
conn->dbName = tmp ? strdup(tmp) : NULL;
tmp = conninfo_getval("user");
conn->pguser = tmp ? strdup(tmp) : NULL;
tmp = conninfo_getval("password");
conn->pgpass = tmp ? strdup(tmp) : NULL;
tmp = conninfo_getval("dbname");
conn->dbName = tmp ? strdup(tmp) : NULL;
/* ----------
* Free the connection info - all is in conn now
@ -226,24 +212,6 @@ PQconnectdb(const char *conninfo)
* ----------
*/
conn->status = connectDB(conn);
if (conn->status == CONNECTION_OK)
{
PGresult *res;
/*
* Send a blank query to make sure everything works; in
* particular, that the database exists.
*/
res = PQexec(conn, " ");
if (res == NULL || res->resultStatus != PGRES_EMPTY_QUERY)
{
/* PQexec has put error message in conn->errorMessage */
closePGconn(conn);
}
PQclear(res);
}
PQsetenv(conn);
return conn;
}
@ -311,150 +279,119 @@ PQsetdbLogin(const char *pghost, const char *pgport, const char *pgoptions, cons
{
PGconn *conn;
char *tmp;
char errorMessage[ERROR_MSG_LENGTH];
/* An error message from some service we call. */
bool error;
bool error = FALSE;
/* We encountered an error that prevents successful completion */
int i;
conn = (PGconn *) malloc(sizeof(PGconn));
conn = makeEmptyPGconn();
if (conn == NULL)
{
fprintf(stderr,
"FATAL: PQsetdb() -- unable to allocate memory for a PGconn");
"FATAL: PQsetdbLogin() -- unable to allocate memory for a PGconn");
return (PGconn *) NULL;
}
if ((pghost == NULL) || pghost[0] == '\0')
{
if ((tmp = getenv("PGHOST")) != NULL)
conn->pghost = strdup(tmp);
}
else
conn->pghost = strdup(pghost);
if ((pgport == NULL) || pgport[0] == '\0')
{
if ((tmp = getenv("PGPORT")) == NULL)
tmp = DEF_PGPORT;
conn->pgport = strdup(tmp);
}
else
conn->pgport = strdup(pgport);
if ((pgtty == NULL) || pgtty[0] == '\0')
{
if ((tmp = getenv("PGTTY")) == NULL)
tmp = DefaultTty;
conn->pgtty = strdup(tmp);
}
else
conn->pgtty = strdup(pgtty);
if ((pgoptions == NULL) || pgoptions[0] == '\0')
{
if ((tmp = getenv("PGOPTIONS")) == NULL)
tmp = DefaultOption;
conn->pgoptions = strdup(tmp);
}
else
conn->pgoptions = strdup(pgoptions);
if (login)
{
conn->pguser = strdup(login);
}
else if ((tmp = getenv("PGUSER")) != NULL)
{
conn->pguser = strdup(tmp);
}
else
{
conn->lobjfuncs = (PGlobjfuncs *) NULL;
conn->Pfout = NULL;
conn->Pfin = NULL;
conn->Pfdebug = NULL;
conn->notifyList = DLNewList();
if ((pghost == NULL) || pghost[0] == '\0')
{
conn->pghost = NULL;
if ((tmp = getenv("PGHOST")) != NULL)
conn->pghost = strdup(tmp);
}
else
conn->pghost = strdup(pghost);
if ((pgport == NULL) || pgport[0] == '\0')
{
if ((tmp = getenv("PGPORT")) == NULL)
tmp = DEF_PGPORT;
conn->pgport = strdup(tmp);
}
else
conn->pgport = strdup(pgport);
if ((pgtty == NULL) || pgtty[0] == '\0')
{
if ((tmp = getenv("PGTTY")) == NULL)
tmp = DefaultTty;
conn->pgtty = strdup(tmp);
}
else
conn->pgtty = strdup(pgtty);
if ((pgoptions == NULL) || pgoptions[0] == '\0')
{
if ((tmp = getenv("PGOPTIONS")) == NULL)
tmp = DefaultOption;
conn->pgoptions = strdup(tmp);
}
else
conn->pgoptions = strdup(pgoptions);
if (login)
{
error = FALSE;
conn->pguser = strdup(login);
}
else if ((tmp = getenv("PGUSER")) != NULL)
{
error = FALSE;
conn->pguser = strdup(tmp);
}
else
{
tmp = fe_getauthname(errorMessage);
if (tmp == 0)
{
error = TRUE;
sprintf(conn->errorMessage,
"FATAL: PQsetdb: Unable to determine a Postgres username!\n");
}
else
{
error = FALSE;
conn->pguser = tmp;
}
}
if (pwd)
{
conn->pgpass = strdup(pwd);
}
else if ((tmp = getenv("PGPASSWORD")) != NULL)
{
conn->pgpass = strdup(tmp);
}
else
conn->pgpass = strdup(DefaultPassword);
if (!error)
{
if ((((tmp = (char *) dbName) != NULL) && (dbName[0] != '\0'))
|| ((tmp = getenv("PGDATABASE"))))
conn->dbName = strdup(tmp);
else
conn->dbName = strdup(conn->pguser);
/*
* if the database name is surrounded by double-quotes, then
* don't convert case
*/
if (*conn->dbName == '"')
{
strcpy(conn->dbName, conn->dbName + 1);
*(conn->dbName + strlen(conn->dbName) - 1) = '\0';
}
else
for (i = 0; conn->dbName[i]; i++)
if (isupper(conn->dbName[i]))
conn->dbName[i] = tolower(conn->dbName[i]);
}
else
conn->dbName = NULL;
if (error)
conn->status = CONNECTION_BAD;
else
{
conn->status = connectDB(conn);
/* Puts message in conn->errorMessage */
if (conn->status == CONNECTION_OK)
{
PGresult *res;
/*
* Send a blank query to make sure everything works; in
* particular, that the database exists.
*/
res = PQexec(conn, " ");
if (res == NULL || res->resultStatus != PGRES_EMPTY_QUERY)
{
/* PQexec has put error message in conn->errorMessage */
closePGconn(conn);
}
PQclear(res);
}
PQsetenv(conn);
}
conn->pguser = fe_getauthname(conn->errorMessage);
}
if (conn->pguser == NULL)
{
error = TRUE;
sprintf(conn->errorMessage,
"FATAL: PQsetdbLogin(): Unable to determine a Postgres username!\n");
}
if (pwd)
{
conn->pgpass = strdup(pwd);
}
else if ((tmp = getenv("PGPASSWORD")) != NULL)
{
conn->pgpass = strdup(tmp);
}
else
{
conn->pgpass = strdup(DefaultPassword);
}
if ((dbName == NULL) || dbName[0] == '\0')
{
if ((tmp = getenv("PGDATABASE")) != NULL)
conn->dbName = strdup(tmp);
else if (conn->pguser)
conn->dbName = strdup(conn->pguser);
}
else
conn->dbName = strdup(dbName);
if (conn->dbName)
{
/*
* if the database name is surrounded by double-quotes, then
* don't convert case
*/
if (*conn->dbName == '"')
{
strcpy(conn->dbName, conn->dbName + 1);
conn->dbName[strlen(conn->dbName) - 1] = '\0';
}
else
for (i = 0; conn->dbName[i]; i++)
if (isupper(conn->dbName[i]))
conn->dbName[i] = tolower(conn->dbName[i]);
}
if (error)
conn->status = CONNECTION_BAD;
else
conn->status = connectDB(conn);
return conn;
}
@ -468,6 +405,7 @@ PQsetdbLogin(const char *pghost, const char *pgport, const char *pgoptions, cons
static ConnStatusType
connectDB(PGconn *conn)
{
PGresult *res;
struct hostent *hp;
StartupPacket sp;
@ -476,6 +414,7 @@ connectDB(PGconn *conn)
int portno,
family,
len;
char beresp;
/*
* Initialize the startup packet.
@ -506,16 +445,17 @@ connectDB(PGconn *conn)
conn->pghost);
goto connect_errReturn;
}
family = AF_INET;
}
else
else {
hp = NULL;
family = AF_UNIX;
}
#if FALSE
MemSet((char *) &port->raddr, 0, sizeof(port->raddr));
#endif
portno = atoi(conn->pgport);
family = (conn->pghost != NULL) ? AF_INET : AF_UNIX;
MemSet((char *) &conn->raddr, 0, sizeof(conn->raddr));
conn->raddr.sa.sa_family = family;
portno = atoi(conn->pgport);
if (family == AF_INET)
{
memmove((char *) &(conn->raddr.in.sin_addr),
@ -528,7 +468,8 @@ connectDB(PGconn *conn)
{
len = UNIXSOCK_PATH(conn->raddr.un, portno);
}
/* connect to the server */
/* Connect to the server */
if ((conn->sock = socket(family, SOCK_STREAM, 0)) < 0)
{
(void) sprintf(conn->errorMessage,
@ -545,6 +486,20 @@ connectDB(PGconn *conn)
conn->pgport);
goto connect_errReturn;
}
/*
* Set the right options.
* We need nonblocking I/O, and we don't want delay of outgoing data.
*/
if (fcntl(conn->sock, F_SETFL, O_NONBLOCK) < 0)
{
(void) sprintf(conn->errorMessage,
"connectDB() -- fcntl() failed: errno=%d\n%s\n",
errno, strerror(errno));
goto connect_errReturn;
}
if (family == AF_INET)
{
struct protoent *pe;
@ -561,109 +516,155 @@ connectDB(PGconn *conn)
&on, sizeof(on)) < 0)
{
(void) sprintf(conn->errorMessage,
"connectDB(): setsockopt failed\n");
"connectDB() -- setsockopt failed: errno=%d\n%s\n",
errno, strerror(errno));
goto connect_errReturn;
}
}
/* fill in the client address */
/* Fill in the client address */
if (getsockname(conn->sock, &conn->laddr.sa, &laddrlen) < 0)
{
(void) sprintf(conn->errorMessage,
"connectDB() -- getsockname() failed: errno=%d\n%s\n",
"connectDB() -- getsockname() failed: errno=%d\n%s\n",
errno, strerror(errno));
goto connect_errReturn;
}
/* set up the socket file descriptors */
conn->Pfout = fdopen(conn->sock, "w");
conn->Pfin = fdopen(dup(conn->sock), "r");
if ((conn->Pfout == NULL) || (conn->Pfin == NULL))
{
(void) sprintf(conn->errorMessage,
"connectDB() -- fdopen() failed: errno=%d\n%s\n",
errno, strerror(errno));
goto connect_errReturn;
}
/* Ensure our buffers are empty */
conn->inStart = conn->inCursor = conn->inEnd = 0;
conn->outCount = 0;
/* Send the startup packet. */
if (packetSend(conn, (char *) &sp, sizeof(StartupPacket)) != STATUS_OK)
{
sprintf(conn->errorMessage,
"connectDB() -- couldn't send complete packet: errno=%d\n%s\n", errno, strerror(errno));
"connectDB() -- couldn't send startup packet: errno=%d\n%s\n",
errno, strerror(errno));
goto connect_errReturn;
}
/*
* Get the response from the backend, either an error message or an
* authentication request.
* Perform the authentication exchange:
* wait for backend messages and respond as necessary.
* We fall out of this loop when done talking to the postmaster.
*/
do
for (;;)
{
int beresp;
if ((beresp = pqGetc(conn->Pfin, conn->Pfdebug)) == EOF)
{
(void) sprintf(conn->errorMessage,
"connectDB() -- error getting authentication request\n");
/* Wait for some data to arrive (or for the channel to close) */
if (pqWait(TRUE, FALSE, conn))
goto connect_errReturn;
}
/* Load data, or detect EOF */
if (pqReadData(conn) < 0)
goto connect_errReturn;
/* Scan the message.
* If we run out of data, loop around to try again.
*/
conn->inCursor = conn->inStart;
if (pqGetc(&beresp, conn))
continue; /* no data yet */
/* Handle errors. */
if (beresp == 'E')
{
pqGets(conn->errorMessage, sizeof(conn->errorMessage),
conn->Pfin, conn->Pfdebug);
if (pqGets(conn->errorMessage, sizeof(conn->errorMessage), conn))
continue;
goto connect_errReturn;
}
/* Check it was an authentication request. */
/* Otherwise it should be an authentication request. */
if (beresp != 'R')
{
(void) sprintf(conn->errorMessage,
"connectDB() -- expected authentication request\n");
"connectDB() -- expected authentication request\n");
goto connect_errReturn;
}
/* Get the type of request. */
if (pqGetInt((int *) &areq, 4, conn->Pfin, conn->Pfdebug))
{
(void) sprintf(conn->errorMessage,
"connectDB() -- error getting authentication request type\n");
goto connect_errReturn;
}
if (pqGetInt((int *) &areq, 4, conn))
continue;
/* Get the password salt if there is one. */
if (areq == AUTH_REQ_CRYPT &&
pqGetnchar(conn->salt, sizeof(conn->salt),
conn->Pfin, conn->Pfdebug))
if (areq == AUTH_REQ_CRYPT)
{
(void) sprintf(conn->errorMessage,
"connectDB() -- error getting password salt\n");
goto connect_errReturn;
if (pqGetnchar(conn->salt, sizeof(conn->salt), conn))
continue;
}
/* OK, we successfully read the message; mark data consumed */
conn->inStart = conn->inCursor;
/* Respond to the request. */
/* Respond to the request if necessary. */
if (fe_sendauth(areq, conn, conn->pghost, conn->pgpass,
conn->errorMessage) != STATUS_OK)
goto connect_errReturn;
}
while (areq != AUTH_REQ_OK);
if (pqFlush(conn))
goto connect_errReturn;
/* free the password so it's not hanging out in memory forever */
/* Are we done? */
if (areq == AUTH_REQ_OK)
break;
}
/*
* Now we expect to hear from the backend.
* A ReadyForQuery message indicates that startup is successful,
* but we might also get an Error message indicating failure.
* (Notice messages indicating nonfatal warnings are also allowed
* by the protocol.)
* Easiest way to handle this is to let PQgetResult() read the messages.
* We just have to fake it out about the state of the connection.
*/
conn->status = CONNECTION_OK;
conn->asyncStatus = PGASYNC_BUSY;
res = PQgetResult(conn);
/* NULL return indicating we have gone to IDLE state is expected */
if (res) {
if (res->resultStatus != PGRES_FATAL_ERROR)
sprintf(conn->errorMessage,
"connectDB() -- unexpected message during startup\n");
PQclear(res);
goto connect_errReturn;
}
/* Given the new protocol that sends a ReadyForQuery message
* after successful backend startup, it should no longer be
* necessary to send an empty query to test for startup.
*/
#if 0
/*
* Send a blank query to make sure everything works; in
* particular, that the database exists.
*/
res = PQexec(conn, " ");
if (res == NULL || res->resultStatus != PGRES_EMPTY_QUERY)
{
/* PQexec has put error message in conn->errorMessage */
closePGconn(conn);
PQclear(res);
goto connect_errReturn;
}
PQclear(res);
#endif
/* Post-connection housekeeping.
* Send environment variables to server
*/
PQsetenv(conn);
/* Free the password so it's not hanging out in memory forever */
/* XXX Is this *really* a good idea? The security gain is marginal
* if not totally illusory, and it breaks PQreset() for databases
* that use passwords.
*/
if (conn->pgpass != NULL)
{
free(conn->pgpass);
@ -673,6 +674,11 @@ connectDB(PGconn *conn)
return CONNECTION_OK;
connect_errReturn:
if (conn->sock >= 0)
{
close(conn->sock);
conn->sock = -1;
}
return CONNECTION_BAD;
}
@ -704,6 +710,36 @@ PQsetenv(PGconn *conn)
}
} /* PQsetenv() */
/*
* makeEmptyPGconn
* - create a PGconn data structure with (as yet) no interesting data
*/
static PGconn *
makeEmptyPGconn(void)
{
PGconn *conn = (PGconn *) malloc(sizeof(PGconn));
if (conn == NULL)
return conn;
/* Zero all pointers */
MemSet((char *) conn, 0, sizeof(PGconn));
conn->status = CONNECTION_BAD;
conn->asyncStatus = PGASYNC_IDLE;
conn->notifyList = DLNewList();
conn->sock = -1;
conn->inBufSize = 8192;
conn->inBuffer = (char *) malloc(conn->inBufSize);
conn->outBufSize = 8192;
conn->outBuffer = (char *) malloc(conn->outBufSize);
if (conn->inBuffer == NULL || conn->outBuffer == NULL)
{
freePGconn(conn);
conn = NULL;
}
return conn;
}
/*
* freePGconn
* - free the PGconn data structure
@ -714,22 +750,32 @@ freePGconn(PGconn *conn)
{
if (!conn)
return;
PQclearAsyncResult(conn); /* deallocate result and curTuple */
if (conn->sock >= 0)
close(conn->sock); /* shouldn't happen, but... */
if (conn->pghost)
free(conn->pghost);
if (conn->pgport)
free(conn->pgport);
if (conn->pgtty)
free(conn->pgtty);
if (conn->pgoptions)
free(conn->pgoptions);
if (conn->pgport)
free(conn->pgport);
if (conn->dbName)
free(conn->dbName);
if (conn->pguser)
free(conn->pguser);
if (conn->pgpass)
free(conn->pgpass);
/* Note that conn->Pfdebug is not ours to close or free */
if (conn->notifyList)
DLFreeList(conn->notifyList);
if (conn->lobjfuncs)
free(conn->lobjfuncs);
if (conn->inBuffer)
free(conn->inBuffer);
if (conn->outBuffer)
free(conn->outBuffer);
free(conn);
}
@ -740,42 +786,54 @@ freePGconn(PGconn *conn)
static void
closePGconn(PGconn *conn)
{
/* GH: What to do for !USE_POSIX_SIGNALS ? */
if (conn->sock >= 0)
{
/*
* Try to send close message.
* If connection is already gone, that's cool. No reason for kernel
* to kill us when we try to write to it. So ignore SIGPIPE signals.
*/
#if defined(USE_POSIX_SIGNALS)
struct sigaction ignore_action;
struct sigaction ignore_action;
struct sigaction oldaction;
/*
* This is used as a constant, but not declared as such because the
* sigaction structure is defined differently on different systems
*/
struct sigaction oldaction;
ignore_action.sa_handler = SIG_IGN;
sigemptyset(&ignore_action.sa_mask);
ignore_action.sa_flags = 0;
sigaction(SIGPIPE, (struct sigaction *) & ignore_action, &oldaction);
/*
* If connection is already gone, that's cool. No reason for kernel
* to kill us when we try to write to it. So ignore SIGPIPE signals.
*/
ignore_action.sa_handler = SIG_IGN;
sigemptyset(&ignore_action.sa_mask);
ignore_action.sa_flags = 0;
sigaction(SIGPIPE, (struct sigaction *) & ignore_action, &oldaction);
(void) pqPuts("X", conn);
(void) pqFlush(conn);
fputs("X\0", conn->Pfout);
fflush(conn->Pfout);
sigaction(SIGPIPE, &oldaction, NULL);
sigaction(SIGPIPE, &oldaction, NULL);
#else
signal(SIGPIPE, SIG_IGN);
fputs("X\0", conn->Pfout);
fflush(conn->Pfout);
signal(SIGPIPE, SIG_DFL);
void (*oldsignal)(int);
oldsignal = signal(SIGPIPE, SIG_IGN);
(void) pqPuts("X", conn);
(void) pqFlush(conn);
signal(SIGPIPE, oldsignal);
#endif
if (conn->Pfout)
fclose(conn->Pfout);
if (conn->Pfin)
fclose(conn->Pfin);
if (conn->Pfdebug)
fclose(conn->Pfdebug);
}
/*
* Close the connection, reset all transient state, flush I/O buffers.
*/
if (conn->sock >= 0)
close(conn->sock);
conn->sock = -1;
conn->status = CONNECTION_BAD; /* Well, not really _bad_ - just
* absent */
conn->asyncStatus = PGASYNC_IDLE;
PQclearAsyncResult(conn); /* deallocate result and curTuple */
if (conn->lobjfuncs)
free(conn->lobjfuncs);
conn->lobjfuncs = NULL;
conn->inStart = conn->inCursor = conn->inEnd = 0;
conn->outCount = 0;
}
/*
@ -793,8 +851,7 @@ PQfinish(PGconn *conn)
}
else
{
if (conn->status == CONNECTION_OK)
closePGconn(conn);
closePGconn(conn);
freePGconn(conn);
}
}
@ -818,12 +875,8 @@ PQreset(PGconn *conn)
}
/*
* PacketSend()
*
this is just like PacketSend(), defined in backend/libpq/pqpacket.c
but we define it here to avoid linking in all of libpq.a
* packetSend -- send a single-packet message.
* PacketSend() -- send a single-packet message.
* this is like PacketSend(), defined in backend/libpq/pqpacket.c
*
* RETURNS: STATUS_ERROR if the write fails, STATUS_OK otherwise.
* SIDE_EFFECTS: may block.
@ -833,15 +886,16 @@ packetSend(PGconn *conn, const char *buf, size_t len)
{
/* Send the total packet size. */
if (pqPutInt(4 + len, 4, conn->Pfout, conn->Pfdebug))
if (pqPutInt(4 + len, 4, conn))
return STATUS_ERROR;
/* Send the packet itself. */
if (pqPutnchar(buf, len, conn->Pfout, conn->Pfdebug))
if (pqPutnchar(buf, len, conn))
return STATUS_ERROR;
pqFlush(conn->Pfout, conn->Pfdebug);
if (pqFlush(conn))
return STATUS_ERROR;
return STATUS_OK;
}
@ -1203,6 +1257,17 @@ PQerrorMessage(PGconn *conn)
return conn->errorMessage;
}
int
PQsocket(PGconn *conn)
{
if (!conn)
{
fprintf(stderr, "PQsocket() -- pointer to PGconn is null\n");
return -1;
}
return conn->sock;
}
void
PQtrace(PGconn *conn, FILE *debug_port)
{
@ -1218,8 +1283,8 @@ PQtrace(PGconn *conn, FILE *debug_port)
void
PQuntrace(PGconn *conn)
{
if (conn == NULL ||
conn->status == CONNECTION_BAD)
/* note: better allow untrace even when connection bad */
if (conn == NULL)
{
return;
}

2318
src/interfaces/libpq/fe-exec.c
View File

File diff suppressed because it is too large Load Diff

581
src/interfaces/libpq/fe-misc.c
View File

@ -5,177 +5,496 @@
*
* DESCRIPTION
* miscellaneous useful functions
* these routines are analogous to the ones in libpq/pqcomm.c
*
* The communication routines here are analogous to the ones in
* backend/libpq/pqcomm.c and backend/libpq/pqcomprim.c, but operate
* in the considerably different environment of the frontend libpq.
* In particular, we work with a bare nonblock-mode socket, rather than
* a stdio stream, so that we can avoid unwanted blocking of the application.
*
* XXX: MOVE DEBUG PRINTOUT TO HIGHER LEVEL. As is, block and restart
* will cause repeat printouts.
*
* We must speak the same transmitted data representations as the backend
* routines. Note that this module supports *only* network byte order
* for transmitted ints, whereas the backend modules (as of this writing)
* still handle either network or little-endian byte order.
*
* Copyright (c) 1994, Regents of the University of California
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/interfaces/libpq/fe-misc.c,v 1.10 1998/02/26 04:45:09 momjian Exp $
* $Header: /cvsroot/pgsql/src/interfaces/libpq/fe-misc.c,v 1.11 1998/05/06 23:51:14 momjian Exp $
*
*-------------------------------------------------------------------------
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <time.h>
#if !defined(NO_UNISTD_H)
#include <unistd.h>
#endif
#include <sys/types.h> /* for fd_set stuff */
#ifdef HAVE_SYS_SELECT_H
#include <sys/select.h>
#endif
#include "postgres.h"
#include "libpq-fe.h"
/* --------------------------------------------------------------------- */
/* pqGetc:
get a character from stream f
get a character from the connection
if debug is set, also echo the character fetched
All these routines return 0 on success, EOF on error.
Note that for the Get routines, EOF only means there is not enough
data in the buffer, not that there is necessarily a hard error.
*/
int
pqGetc(FILE *fin, FILE *debug)
pqGetc(char *result, PGconn *conn)
{
int c;
if (conn->inCursor >= conn->inEnd)
return EOF;
c = getc(fin);
*result = conn->inBuffer[conn->inCursor++];
if (debug && c != EOF)
fprintf(debug, "From backend> %c\n", c);
if (conn->Pfdebug)
fprintf(conn->Pfdebug, "From backend> %c\n", *result);
return c;
return 0;
}
/* --------------------------------------------------------------------- */
/* pqPutnchar:
send a string of exactly len length into stream f
returns 1 if there was an error, 0 otherwise.
*/
int
pqPutnchar(const char *s, int len, FILE *f, FILE *debug)
{
if (debug)
fprintf(debug, "To backend> %s\n", s);
return (pqPutNBytes(s, len, f) == EOF ? 1 : 0);
}
/* --------------------------------------------------------------------- */
/* pqGetnchar:
get a string of exactly len bytes in buffer s (which must be 1 byte
longer) from stream f and terminate it with a '\0'.
*/
int
pqGetnchar(char *s, int len, FILE *f, FILE *debug)
/* pqPutBytes: local routine to write N bytes to the connection,
with buffering
*/
static int
pqPutBytes(const char *s, int nbytes, PGconn *conn)
{
int status;
int avail = conn->outBufSize - conn->outCount;
status = pqGetNBytes(s, len, f);
if (debug)
fprintf(debug, "From backend (%d)> %s\n", len, s);
return (status == EOF ? 1 : 0);
}
/* --------------------------------------------------------------------- */
/* pqGets:
get a string of up to length len from stream f
*/
int
pqGets(char *s, int len, FILE *f, FILE *debug)
{
int status;
status = pqGetString(s, len, f);
if (debug)
fprintf(debug, "From backend> \"%s\"\n", s);
return (status == EOF ? 1 : 0);
}
/* --------------------------------------------------------------------- */
/* pgPutInt
send an integer of 2 or 4 bytes to the file stream, compensate
for host endianness.
returns 0 if successful, 1 otherwise
*/
int
pqPutInt(const int integer, int bytes, FILE *f, FILE *debug)
{
int retval = 0;
switch (bytes)
while (nbytes > avail)
{
case 2:
retval = pqPutShort(integer, f);
break;
case 4:
retval = pqPutLong(integer, f);
break;
default:
fprintf(stderr, "** int size %d not supported\n", bytes);
retval = 1;
memcpy(conn->outBuffer + conn->outCount, s, avail);
conn->outCount += avail;
s += avail;
nbytes -= avail;
if (pqFlush(conn))
return EOF;
avail = conn->outBufSize;
}
if (debug)
fprintf(debug, "To backend (%d#)> %d\n", bytes, integer);
return retval;
}
/* --------------------------------------------------------------------- */
/* pgGetInt
read a 2 or 4 byte integer from the stream and swab it around
to compensate for different endianness
returns 0 if successful
*/
int
pqGetInt(int *result, int bytes, FILE *f, FILE *debug)
{
int retval = 0;
switch (bytes)
{
case 2:
retval = pqGetShort(result, f);
break;
case 4:
retval = pqGetLong(result, f);
break;
default:
fprintf(stderr, "** int size %d not supported\n", bytes);
retval = 1;
}
if (debug)
fprintf(debug, "From backend (#%d)> %d\n", bytes, *result);
return retval;
}
/* --------------------------------------------------------------------- */
int
pqPuts(const char *s, FILE *f, FILE *debug)
{
if (pqPutString(s, f) == EOF)
return 1;
fflush(f);
if (debug)
fprintf(debug, "To backend> %s\n", s);
memcpy(conn->outBuffer + conn->outCount, s, nbytes);
conn->outCount += nbytes;
return 0;
}
/* --------------------------------------------------------------------- */
void
pqFlush(FILE *f, FILE *debug)
/* pqGets:
get a null-terminated string from the connection,
and store it in a buffer of size maxlen bytes.
If the incoming string is >= maxlen bytes, all of it is read,
but the excess characters are silently discarded.
*/
int
pqGets(char *s, int maxlen, PGconn *conn)
{
if (f)
fflush(f);
/* Copy conn data to locals for faster search loop */
char *inBuffer = conn->inBuffer;
int inCursor = conn->inCursor;
int inEnd = conn->inEnd;
int slen;
if (debug)
fflush(debug);
while (inCursor < inEnd && inBuffer[inCursor])
inCursor++;
if (inCursor >= inEnd)
return EOF;
slen = inCursor - conn->inCursor;
if (slen < maxlen)
strcpy(s, inBuffer + conn->inCursor);
else
{
strncpy(s, inBuffer + conn->inCursor, maxlen-1);
s[maxlen-1] = '\0';
}
conn->inCursor = ++inCursor;
if (conn->Pfdebug)
fprintf(conn->Pfdebug, "From backend> \"%s\"\n", s);
return 0;
}
/* --------------------------------------------------------------------- */
int
pqPuts(const char *s, PGconn *conn)
{
if (pqPutBytes(s, strlen(s)+1, conn))
return EOF;
if (conn->Pfdebug)
fprintf(conn->Pfdebug, "To backend> %s\n", s);
return 0;
}
/* --------------------------------------------------------------------- */
/* pqGetnchar:
get a string of exactly len bytes in buffer s (which must be 1 byte
longer) and terminate it with a '\0'.
*/
int
pqGetnchar(char *s, int len, PGconn *conn)
{
if (len < 0 || len > conn->inEnd - conn->inCursor)
return EOF;
memcpy(s, conn->inBuffer + conn->inCursor, len);
s[len] = '\0';
conn->inCursor += len;
if (conn->Pfdebug)
fprintf(conn->Pfdebug, "From backend (%d)> %s\n", len, s);
return 0;
}
/* --------------------------------------------------------------------- */
/* pqPutnchar:
send a string of exactly len bytes
The buffer should have a terminating null, but it's not sent.
*/
int
pqPutnchar(const char *s, int len, PGconn *conn)
{
if (pqPutBytes(s, len, conn))
return EOF;
if (conn->Pfdebug)
fprintf(conn->Pfdebug, "To backend> %s\n", s);
return 0;
}
/* --------------------------------------------------------------------- */
/* pgGetInt
read a 2 or 4 byte integer and convert from network byte order
to local byte order
*/
int
pqGetInt(int *result, int bytes, PGconn *conn)
{
uint16 tmp2;
uint32 tmp4;
switch (bytes)
{
case 2:
if (conn->inCursor + 2 > conn->inEnd)
return EOF;
memcpy(&tmp2, conn->inBuffer + conn->inCursor, 2);
conn->inCursor += 2;
*result = (int) ntohs(tmp2);
break;
case 4:
if (conn->inCursor + 4 > conn->inEnd)
return EOF;
memcpy(&tmp4, conn->inBuffer + conn->inCursor, 4);
conn->inCursor += 4;
*result = (int) ntohl(tmp4);
break;
default:
fprintf(stderr, "** int size %d not supported\n", bytes);
return EOF;
}
if (conn->Pfdebug)
fprintf(conn->Pfdebug, "From backend (#%d)> %d\n", bytes, *result);
return 0;
}
/* --------------------------------------------------------------------- */
/* pgPutInt
send an integer of 2 or 4 bytes, converting from host byte order
to network byte order.
*/
int
pqPutInt(int value, int bytes, PGconn *conn)
{
uint16 tmp2;
uint32 tmp4;
switch (bytes)
{
case 2:
tmp2 = htons((uint16) value);
if (pqPutBytes((const char*) &tmp2, 2, conn))
return EOF;
break;
case 4:
tmp4 = htonl((uint32) value);
if (pqPutBytes((const char*) &tmp4, 4, conn))
return EOF;
break;
default:
fprintf(stderr, "** int size %d not supported\n", bytes);
return EOF;
}
if (conn->Pfdebug)
fprintf(conn->Pfdebug, "To backend (%d#)> %d\n", bytes, value);
return 0;
}
/* --------------------------------------------------------------------- */
/* pqReadReady: is select() saying the file is ready to read?
*/
static int
pqReadReady(PGconn *conn)
{
fd_set input_mask;
struct timeval timeout;
if (conn->sock < 0)
return 0;
FD_ZERO(&input_mask);
FD_SET(conn->sock, &input_mask);
timeout.tv_sec = 0;
timeout.tv_usec = 0;
if (select(conn->sock+1, &input_mask, (fd_set *) NULL, (fd_set *) NULL,
&timeout) < 0)
{
sprintf(conn->errorMessage,
"pqReadReady() -- select() failed: errno=%d\n%s\n",
errno, strerror(errno));
return 0;
}
return FD_ISSET(conn->sock, &input_mask);
}
/* --------------------------------------------------------------------- */
/* pqReadData: read more data, if any is available
* Possible return values:
* 1: successfully loaded at least one more byte
* 0: no data is presently available, but no error detected
* -1: error detected (including EOF = connection closure);
* conn->errorMessage set
* NOTE: callers must not assume that pointers or indexes into conn->inBuffer
* remain valid across this call!
*/
int
pqReadData(PGconn *conn)
{
int nread;
if (conn->sock < 0)
{
strcpy(conn->errorMessage, "pqReadData() -- connection not open\n");
return -1;
}
/* Left-justify any data in the buffer to make room */
if (conn->inStart < conn->inEnd)
{
memmove(conn->inBuffer, conn->inBuffer + conn->inStart,
conn->inEnd - conn->inStart);
conn->inEnd -= conn->inStart;
conn->inCursor -= conn->inStart;
conn->inStart = 0;
}
else
{
conn->inStart = conn->inCursor = conn->inEnd = 0;
}
/* If the buffer is fairly full, enlarge it.
* We need to be able to enlarge the buffer in case a single message
* exceeds the initial buffer size. We enlarge before filling the
* buffer entirely so as to avoid asking the kernel for a partial packet.
* The magic constant here should be at least one TCP packet.
*/
if (conn->inBufSize - conn->inEnd < 2000)
{
int newSize = conn->inBufSize * 2;
char * newBuf = (char *) realloc(conn->inBuffer, newSize);
if (newBuf)
{
conn->inBuffer = newBuf;
conn->inBufSize = newSize;
}
}
/* OK, try to read some data */
tryAgain:
nread = recv(conn->sock, conn->inBuffer + conn->inEnd,
conn->inBufSize - conn->inEnd, 0);
if (nread < 0)
{
if (errno == EINTR)
goto tryAgain;
sprintf(conn->errorMessage,
"pqReadData() -- read() failed: errno=%d\n%s\n",
errno, strerror(errno));
return -1;
}
if (nread > 0)
{
conn->inEnd += nread;
return 1;
}
/* A return value of 0 could mean just that no data is now available,
* or it could mean EOF --- that is, the server has closed the connection.
* Since we have the socket in nonblock mode, the only way to tell the
* difference is to see if select() is saying that the file is ready.
* Grumble. Fortunately, we don't expect this path to be taken much,
* since in normal practice we should not be trying to read data unless
* the file selected for reading already.
*/
if (! pqReadReady(conn))
return 0; /* definitely no data available */
/* Still not sure that it's EOF,
* because some data could have just arrived.
*/
tryAgain2:
nread = recv(conn->sock, conn->inBuffer + conn->inEnd,
conn->inBufSize - conn->inEnd, 0);
if (nread < 0)
{
if (errno == EINTR)
goto tryAgain2;
sprintf(conn->errorMessage,
"pqReadData() -- read() failed: errno=%d\n%s\n",
errno, strerror(errno));
return -1;
}
if (nread > 0)
{
conn->inEnd += nread;
return 1;
}
/* OK, we are getting a zero read even though select() says ready.
* This means the connection has been closed. Cope.
*/
sprintf(conn->errorMessage,
"pqReadData() -- backend closed the channel unexpectedly.\n"
"\tThis probably means the backend terminated abnormally"
" before or while processing the request.\n");
conn->status = CONNECTION_BAD; /* No more connection to
* backend */
close(conn->sock);
conn->sock = -1;
return -1;
}
/* --------------------------------------------------------------------- */
/* pqFlush: send any data waiting in the output buffer
*/
int
pqFlush(PGconn *conn)
{
char * ptr = conn->outBuffer;
int len = conn->outCount;
if (conn->sock < 0)
{
strcpy(conn->errorMessage, "pqFlush() -- connection not open\n");
return EOF;
}
while (len > 0)
{
int sent = send(conn->sock, ptr, len, 0);
if (sent < 0)
{
/* Anything except EAGAIN or EWOULDBLOCK is trouble */
switch (errno)
{
#ifdef EAGAIN
case EAGAIN:
break;
#endif
#if defined(EWOULDBLOCK) && (!defined(EAGAIN) || (EWOULDBLOCK != EAGAIN))
case EWOULDBLOCK:
break;
#endif
default:
sprintf(conn->errorMessage,
"pqFlush() -- couldn't send data: errno=%d\n%s\n",
errno, strerror(errno));
return EOF;
}
}
else
{
ptr += sent;
len -= sent;
}
if (len > 0)
{
/* We didn't send it all, wait till we can send more */
if (pqWait(FALSE, TRUE, conn))
return EOF;
}
}
conn->outCount = 0;
if (conn->Pfdebug)
fflush(conn->Pfdebug);
return 0;
}
/* --------------------------------------------------------------------- */
/* pqWait: wait until we can read or write the connection socket
*/
int
pqWait(int forRead, int forWrite, PGconn *conn)
{
fd_set input_mask;
fd_set output_mask;
if (conn->sock < 0)
{
strcpy(conn->errorMessage, "pqWait() -- connection not open\n");
return EOF;
}
/* loop in case select returns EINTR */
for (;;) {
FD_ZERO(&input_mask);
FD_ZERO(&output_mask);
if (forRead)
FD_SET(conn->sock, &input_mask);
if (forWrite)
FD_SET(conn->sock, &output_mask);
if (select(conn->sock+1, &input_mask, &output_mask, (fd_set *) NULL,
(struct timeval *) NULL) < 0)
{
if (errno == EINTR)
continue;
sprintf(conn->errorMessage,
"pqWait() -- select() failed: errno=%d\n%s\n",
errno, strerror(errno));
return EOF;
}
/* On nonerror return, assume we're done */
break;
}
return 0;
}

362
src/interfaces/libpq/libpq-fe.h
View File

@ -6,7 +6,7 @@
*
* Copyright (c) 1994, Regents of the University of California
*
* $Id: libpq-fe.h,v 1.28 1998/03/20 04:02:57 momjian Exp $
* $Id: libpq-fe.h,v 1.29 1998/05/06 23:51:16 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -28,6 +28,8 @@ extern "C"
#include "libpq/pqcomm.h"
#include "lib/dllist.h"
/* Application-visible enum types */
typedef enum
{
CONNECTION_OK,
@ -41,14 +43,13 @@ extern "C"
/* anything was executed properly by the backend */
PGRES_TUPLES_OK, /* a query command that returns tuples */
/* was executed properly by the backend, PGresult */
/* contains the resulttuples */
PGRES_COPY_OUT,
PGRES_COPY_IN,
/* contains the result tuples */
PGRES_COPY_OUT, /* Copy Out data transfer in progress */
PGRES_COPY_IN, /* Copy In data transfer in progress */
PGRES_BAD_RESPONSE, /* an unexpected response was recv'd from
* the backend */
PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR
} ExecStatusType;
/* string descriptions of the ExecStatusTypes */
@ -63,29 +64,21 @@ extern "C"
#define COMMAND_LENGTH 20
#define REMARK_LENGTH 80
#define PORTAL_NAME_LENGTH 16
#define CMDSTATUS_LEN 40
/* ----------------
* PQArgBlock --
* Information (pointer to array of this structure) required
* for the PQfn() call.
* ----------------
/* PGresult and the subsidiary types PGresAttDesc, PGresAttValue
* represent the result of a query (or more precisely, of a single SQL
* command --- a query string given to PQexec can contain multiple commands).
* Note we assume that a single command can return at most one tuple group,
* hence there is no need for multiple descriptor sets.
*/
typedef struct
{
int len;
int isint;
union
{
int *ptr; /* can't use void (dec compiler barfs) */
int integer;
} u;
} PQArgBlock;
typedef struct pgresAttDesc
{
char *name; /* type name */
Oid adtid; /* type id */
short adtsize; /* type size */
short adtmod; /* type-specific modifier info */
} PGresAttDesc;
/* use char* for Attribute values,
@ -102,59 +95,8 @@ extern "C"
char *value; /* actual value */
} PGresAttValue;
typedef struct pgNotify
{
char relname[NAMEDATALEN]; /* name of relation
* containing data */
int be_pid; /* process id of backend */
} PGnotify;
struct pg_conn; /* forward reference */
typedef struct pgLobjfuncs
{
Oid fn_lo_open; /* OID of backend function lo_open */
Oid fn_lo_close;/* OID of backend function lo_close */
Oid fn_lo_creat;/* OID of backend function lo_creat */
Oid fn_lo_unlink; /* OID of backend function
* lo_unlink */
Oid fn_lo_lseek;/* OID of backend function lo_lseek */
Oid fn_lo_tell; /* OID of backend function lo_tell */
Oid fn_lo_read; /* OID of backend function LOread */
Oid fn_lo_write;/* OID of backend function LOwrite */
} PGlobjfuncs;
/* PGconn encapsulates a connection to the backend */
typedef struct pg_conn
{
char *pghost; /* the machine on which the server is
* running */
char *pgtty; /* tty on which the backend messages is
* displayed */
char *pgport; /* the communication port with the backend */
char *pgoptions; /* options to start the backend with */
char *dbName; /* database name */
ConnStatusType status;
char errorMessage[ERROR_MSG_LENGTH];
/* pipes for be/fe communication */
FILE *Pfin;
FILE *Pfout;
FILE *Pfdebug;
int sock; /* The socket */
SockAddr laddr; /* Local address */
SockAddr raddr; /* Remote address */
char salt[2];
int asyncNotifyWaiting;
Dllist *notifyList;
char *pguser; /* Postgres username of user who is
* connected */
char *pgpass;
PGlobjfuncs *lobjfuncs; /* Backend function OID's for large object
* access */
} PGconn;
#define CMDSTATUS_LEN 40
/* PGresult encapsulates the result of a query */
/* unlike the old libpq, we assume that queries only return in one group */
typedef struct pg_result
{
int ntups;
@ -168,9 +110,99 @@ extern "C"
* last insert query */
int binary; /* binary tuple values if binary == 1,
* otherwise ASCII */
PGconn *conn;
struct pg_conn *conn; /* connection we did the query on */
} PGresult;
/* PGnotify represents the occurrence of a NOTIFY message */
typedef struct pgNotify
{
char relname[NAMEDATALEN]; /* name of relation
* containing data */
int be_pid; /* process id of backend */
} PGnotify;
/* PGAsyncStatusType is private to libpq, really shouldn't be seen by users */
typedef enum
{
PGASYNC_IDLE, /* nothing's happening, dude */
PGASYNC_BUSY, /* query in progress */
PGASYNC_READY, /* result ready for PQgetResult */
PGASYNC_COPY_IN, /* Copy In data transfer in progress */
PGASYNC_COPY_OUT /* Copy Out data transfer in progress */
} PGAsyncStatusType;
/* large-object-access data ... allocated only if large-object code is used.
* Really shouldn't be visible to users */
typedef struct pgLobjfuncs
{
Oid fn_lo_open; /* OID of backend function lo_open */
Oid fn_lo_close;/* OID of backend function lo_close */
Oid fn_lo_creat;/* OID of backend function lo_creat */
Oid fn_lo_unlink; /* OID of backend function
* lo_unlink */
Oid fn_lo_lseek;/* OID of backend function lo_lseek */
Oid fn_lo_tell; /* OID of backend function lo_tell */
Oid fn_lo_read; /* OID of backend function LOread */
Oid fn_lo_write;/* OID of backend function LOwrite */
} PGlobjfuncs;
/* PGconn encapsulates a connection to the backend.
* XXX contents of this struct really shouldn't be visible to applications
*/
typedef struct pg_conn
{
/* Saved values of connection options */
char *pghost; /* the machine on which the server is
* running */
char *pgport; /* the server's communication port */
char *pgtty; /* tty on which the backend messages is
* displayed (NOT ACTUALLY USED???) */
char *pgoptions; /* options to start the backend with */
char *dbName; /* database name */
char *pguser; /* Postgres username and password, if any */
char *pgpass;
/* Optional file to write trace info to */
FILE *Pfdebug;
/* Status indicators */
ConnStatusType status;
PGAsyncStatusType asyncStatus;
Dllist *notifyList; /* Notify msgs not yet handed to application */
/* Connection data */
int sock; /* Unix FD for socket, -1 if not connected */
SockAddr laddr; /* Local address */
SockAddr raddr; /* Remote address */
/* Miscellaneous stuff */
char salt[2]; /* password salt received from backend */
PGlobjfuncs *lobjfuncs; /* private state for large-object access fns */
/* Buffer for data received from backend and not yet processed */
char *inBuffer; /* currently allocated buffer */
int inBufSize; /* allocated size of buffer */
int inStart; /* offset to first unconsumed data in buffer */
int inCursor; /* next byte to tentatively consume */
int inEnd; /* offset to first position after avail data */
/* Buffer for data not yet sent to backend */
char *outBuffer; /* currently allocated buffer */
int outBufSize; /* allocated size of buffer */
int outCount; /* number of chars waiting in buffer */
/* Status for asynchronous result construction */
PGresult *result; /* result being constructed */
PGresAttValue *curTuple; /* tuple currently being read */
/* Message space. Placed last for code-size reasons.
* errorMessage is the message last returned to the application.
* When asyncStatus=READY, asyncErrorMessage is the pending message
* that will be put in errorMessage by PQgetResult. */
char errorMessage[ERROR_MSG_LENGTH];
char asyncErrorMessage[ERROR_MSG_LENGTH];
} PGconn;
typedef char pqbool;
/*
@ -179,7 +211,9 @@ extern "C"
* defined. Pqbool, on the other hand, is unlikely to be used.
*/
struct _PQprintOpt
/* Print options for PQprint() */
typedef struct _PQprintOpt
{
pqbool header; /* print output field headings and row
* count */
@ -193,15 +227,28 @@ extern "C"
char *caption; /* HTML <caption> */
char **fieldName; /* null terminated array of repalcement
* field names */
};
} PQprintOpt;
typedef struct _PQprintOpt PQprintOpt;
/* ----------------
* PQArgBlock -- structure for PQfn() arguments
* ----------------
*/
typedef struct
{
int len;
int isint;
union
{
int *ptr; /* can't use void (dec compiler barfs) */
int integer;
} u;
} PQArgBlock;
/* ----------------
* Structure for the conninfo parameter definitions of PQconnectdb()
* ----------------
*/
struct _PQconninfoOption
typedef struct _PQconninfoOption
{
char *keyword; /* The keyword of the option */
char *environ; /* Fallback environment variable name */
@ -215,9 +262,7 @@ extern "C"
/* "D" Debug options - don't */
/* create a field by default */
int dispsize; /* Field size in characters for dialog */
};
typedef struct _PQconninfoOption PQconninfoOption;
} PQconninfoOption;
/* === in fe-connect.c === */
/* make a new client connection to the backend */
@ -235,6 +280,7 @@ extern "C"
*/
extern void PQreset(PGconn *conn);
/* Accessor functions for PGconn objects */
extern char *PQdb(PGconn *conn);
extern char *PQuser(PGconn *conn);
extern char *PQhost(PGconn *conn);
@ -243,51 +289,28 @@ extern "C"
extern char *PQtty(PGconn *conn);
extern ConnStatusType PQstatus(PGconn *conn);
extern char *PQerrorMessage(PGconn *conn);
extern int PQsocket(PGconn *conn);
/* Enable/disable tracing */
extern void PQtrace(PGconn *conn, FILE *debug_port);
extern void PQuntrace(PGconn *conn);
/* === in fe-exec.c === */
/* Simple synchronous query */
extern PGresult *PQexec(PGconn *conn, const char *query);
extern int PQgetline(PGconn *conn, char *string, int length);
extern int PQendcopy(PGconn *conn);
extern void PQputline(PGconn *conn, const char *string);
extern ExecStatusType PQresultStatus(PGresult *res);
extern int PQntuples(PGresult *res);
extern int PQnfields(PGresult *res);
extern char *PQfname(PGresult *res, int field_num);
extern int PQfnumber(PGresult *res, const char *field_name);
extern Oid PQftype(PGresult *res, int field_num);
extern short PQfsize(PGresult *res, int field_num);
extern char *PQcmdStatus(PGresult *res);
extern const char *PQoidStatus(PGresult *res);
extern const char *PQcmdTuples(PGresult *res);
extern char *PQgetvalue(PGresult *res, int tup_num, int field_num);
extern int PQgetlength(PGresult *res, int tup_num, int field_num);
extern int PQgetisnull(PGresult *res, int tup_num, int field_num);
extern void PQclear(PGresult *res);
/* PQdisplayTuples() is a better version of PQprintTuples() */
extern void PQdisplayTuples(PGresult *res,
FILE *fp, /* where to send the
* output */
int fillAlign, /* pad the fields with
* spaces */
const char *fieldSep, /* field separator */
int printHeader, /* display headers? */
int quiet);
extern void PQprintTuples(PGresult *res,
FILE *fout, /* output stream */
int printAttName, /* print attribute names
* or not */
int terseOutput, /* delimiter bars or
* not? */
int width /* width of column, if
* 0, use variable width */
);
extern void PQprint(FILE *fout, /* output stream */
PGresult *res,
PQprintOpt *ps /* option structure */
);
extern PGnotify *PQnotifies(PGconn *conn);
/* Interface for multiple-result or asynchronous queries */
extern int PQsendQuery(PGconn *conn, const char *query);
extern PGresult *PQgetResult(PGconn *conn);
/* Routines for managing an asychronous query */
extern int PQisBusy(PGconn *conn);
extern void PQconsumeInput(PGconn *conn);
extern int PQrequestCancel(PGconn *conn);
/* Routines for copy in/out */
extern int PQgetline(PGconn *conn, char *string, int length);
extern void PQputline(PGconn *conn, const char *string);
extern int PQendcopy(PGconn *conn);
/* Not really meant for application use: */
extern PGresult *PQfn(PGconn *conn,
int fnid,
int *result_buf,
@ -295,47 +318,94 @@ extern "C"
int result_is_int,
PQArgBlock *args,
int nargs);
extern void PQclearAsyncResult(PGconn *conn);
/* Accessor functions for PGresult objects */
extern ExecStatusType PQresultStatus(PGresult *res);
extern int PQntuples(PGresult *res);
extern int PQnfields(PGresult *res);
extern char *PQfname(PGresult *res, int field_num);
extern int PQfnumber(PGresult *res, const char *field_name);
extern Oid PQftype(PGresult *res, int field_num);
extern short PQfsize(PGresult *res, int field_num);
extern short PQfmod(PGresult *res, int field_num);
extern char *PQcmdStatus(PGresult *res);
extern const char *PQoidStatus(PGresult *res);
extern const char *PQcmdTuples(PGresult *res);
extern char *PQgetvalue(PGresult *res, int tup_num, int field_num);
extern int PQgetlength(PGresult *res, int tup_num, int field_num);
extern int PQgetisnull(PGresult *res, int tup_num, int field_num);
/* Delete a PGresult */
extern void PQclear(PGresult *res);
/* === in fe-print.c === */
extern void PQprint(FILE *fout, /* output stream */
PGresult *res,
PQprintOpt *ps /* option structure */
);
/* PQdisplayTuples() is a better version of PQprintTuples(),
* but both are obsoleted by PQprint().
*/
extern void PQdisplayTuples(PGresult *res,
FILE *fp, /* where to send the
* output */
int fillAlign, /* pad the fields with
* spaces */
const char *fieldSep, /* field separator */
int printHeader, /* display headers? */
int quiet);
extern void PQprintTuples(PGresult *res,
FILE *fout, /* output stream */
int printAttName, /* print attribute names
* or not */
int terseOutput, /* delimiter bars or
* not? */
int width /* width of column, if
* 0, use variable width */
);
/* === in fe-auth.c === */
extern MsgType fe_getauthsvc(char *PQerrormsg);
extern void fe_setauthsvc(const char *name, char *PQerrormsg);
extern char *fe_getauthname(char *PQerrormsg);
/* === in fe-misc.c === */
/* pqGets and pqPuts gets and sends strings to the file stream
returns 0 if successful
if debug is non-null, debugging output is sent to that stream
*/
extern int pqGets(char *s, int maxlen, FILE *stream, FILE *debug);
extern int pqGetnchar(char *s, int maxlen, FILE *stream, FILE *debug);
extern int pqPutnchar(const char *s, int maxlen, FILE *stream, FILE *debug);
extern int pqPuts(const char *s, FILE *stream, FILE *debug);
extern int pqGetc(FILE *stream, FILE *debug);
/* get a n-byte integer from the stream into result */
/* returns 0 if successful */
extern int pqGetInt(int *result, int bytes, FILE *stream, FILE *debug);
/* put a n-byte integer into the stream */
/* returns 0 if successful */
extern int pqPutInt(const int n, int bytes, FILE *stream, FILE *debug);
extern void pqFlush(FILE *stream, FILE *debug);
/* "Get" and "Put" routines return 0 if successful, EOF if not.
* Note that for Get, EOF merely means the buffer is exhausted,
* not that there is necessarily any error.
*/
extern int pqGetc(char *result, PGconn *conn);
extern int pqGets(char *s, int maxlen, PGconn *conn);
extern int pqPuts(const char *s, PGconn *conn);
extern int pqGetnchar(char *s, int len, PGconn *conn);
extern int pqPutnchar(const char *s, int len, PGconn *conn);
extern int pqGetInt(int *result, int bytes, PGconn *conn);
extern int pqPutInt(int value, int bytes, PGconn *conn);
extern int pqReadData(PGconn *conn);
extern int pqFlush(PGconn *conn);
extern int pqWait(int forRead, int forWrite, PGconn *conn);
/* === in fe-lobj.c === */
int lo_open(PGconn *conn, Oid lobjId, int mode);
int lo_close(PGconn *conn, int fd);
int lo_read(PGconn *conn, int fd, char *buf, int len);
int lo_write(PGconn *conn, int fd, char *buf, int len);
int lo_lseek(PGconn *conn, int fd, int offset, int whence);
Oid lo_creat(PGconn *conn, int mode);
int lo_tell(PGconn *conn, int fd);
int lo_unlink(PGconn *conn, Oid lobjId);
Oid lo_import(PGconn *conn, char *filename);
int lo_export(PGconn *conn, Oid lobjId, char *filename);
extern int lo_open(PGconn *conn, Oid lobjId, int mode);
extern int lo_close(PGconn *conn, int fd);
extern int lo_read(PGconn *conn, int fd, char *buf, int len);
extern int lo_write(PGconn *conn, int fd, char *buf, int len);
extern int lo_lseek(PGconn *conn, int fd, int offset, int whence);
extern Oid lo_creat(PGconn *conn, int mode);
extern int lo_tell(PGconn *conn, int fd);
extern int lo_unlink(PGconn *conn, Oid lobjId);
extern Oid lo_import(PGconn *conn, char *filename);
extern int lo_export(PGconn *conn, Oid lobjId, char *filename);
/* max length of message to send */
#define MAX_MESSAGE_LEN 8193
/* maximum number of fields in a tuple */
#define BYTELEN 8
#define MAX_FIELDS 512
/* bits in a byte */
#define BYTELEN 8
/* fall back options if they are not specified by arguments or defined
by environment variables */
#define DefaultHost "localhost"