diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 6fe77dbcde..a78fdb6f38 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -2,15 +2,22 @@ <FileName>libpq</FileName> - libpq is the application programming interface to Postgres. - libpq is a set of library routines which allows - client programs to pass queries to the Postgres backend - server and to receive the results of these queries. - This version of the documentation describes the C - interface library. Three short programs are included - at the end of this section to show how to write programs that use libpq. - There are several examples of libpq applications in the - following directories: + +libpq is the C application programmer's interface to +Postgres. libpq is a set +of library routines that allow client programs to pass queries to the +Postgres backend server and to receive the +results of these queries. libpq is also the +underlying engine for several other Postgres +application interfaces, including libpq++ (C++), +libpgtcl (Tcl), perl5, and +ecpg. So some aspects of libpq's behavior will be +important to you if you use one of those packages. + +Three short programs are included at the end of this section to show how +to write programs that use libpq. There are several +complete examples of libpq applications in the +following directories: ../src/test/regress @@ -19,127 +26,26 @@ - Frontend programs which use libpq must include the - header file libpq-fe.h and must link with the libpq - library. +Frontend programs which use libpq must include the +header file libpq-fe.h and must link with the +libpq library. - -Control and Initialization - - - The following environment variables can be used to set - up default environment values to avoid hard-coding - database names into an application program: - - - - -PGHOST sets the default server name. -If it is set to a non-zero-length string, it causes TCP/IP -communication to be used, rather than the default local Unix domain sockets. - - - - -PGOPTIONS sets additional runtime options for the Postgres backend. - - - - -PGPORT sets the default port or local Unix domain socket -file extension for communicating with the Postgres -backend. - - - - -PGTTY sets the file or tty on which debugging messages from the backend server are displayed. - - - - -PGDATABASE sets the default Postgres database name. - - - - -PGREALM sets the Kerberos realm to use with Postgres, - if it is different from the local realm. If -PGREALM is set, Postgres applications will attempt - authentication with servers for this realm and use - separate ticket files to avoid conflicts with local - ticket files. This environment variable is only - used if Kerberos authentication is enabled. - - - - - - -The following environment variables can be used to specify user-level default -behavior for every Postgres session: - - - - -PGDATESTYLE -sets the default style of date/time representation. - - - - -PGTZ -sets the default time zone. - - - - - - -The following environment variables can be used to specify default internal -behavior for every Postgres session: - - - - -PGGEQO -sets the default mode for the genetic optimizer. - - - - -PGRPLANS -sets the default mode to allow or disable right-sided plans in the optimizer. - - - - -PGCOSTHEAP -sets the default cost for heap searches for the optimizer. - - - - -PGCOSTINDEX -sets the default cost for indexed searches for the optimizer. - - - - - - -Refer to the SET SQL command -for information on the arguments for these environment variables. - - - Database Connection Functions The following routines deal with making a connection to - a backend from a C program. + a Postgres backend server. The application + program can have several backend connections open at one time. + (One reason to do that is to access more than one database.) + Each connection is represented by a PGconn object which is obtained + from PQconnectdb() or PQsetdbLogin(). NOTE that these functions + will always return a non-null object pointer, unless perhaps + there is too little memory even to allocate the PGconn object. + The PQstatus function should be called + to check whether a connection was successfully made + before queries are sent via the connection object. @@ -152,21 +58,14 @@ PGconn *PQsetdbLogin(const char *pghost, const char *pgtty, const char *dbName, const char *login, - const char *pwd); + const char *pwd) If any argument is NULL, then the corresponding - environment variable is checked. If the environment variable is also not set, then hardwired - defaults are used. - PQsetdbLogin always returns a valid PGconn pointer. - The PQstatus (see below) command should be called - to ensure that a connection was properly made - before queries are sent via the connection. libpq - programmers should be careful to maintain the - PGconn abstraction. Use the accessor functions - below to get at the contents of PGconn. Avoid - directly referencing the fields of the PGconn - structure as they are subject to change in the - future. + environment variable (see "Environment Variables" section) + is checked. If the environment variable + is also not set, then hardwired defaults are used. + The return value is a pointer to an abstract struct + representing the connection to the backend. @@ -179,10 +78,83 @@ PGconn *PQsetdb(char *pghost, char *pgport, char *pgoptions, char *pgtty, - char *dbName); + char *dbName) This is a macro that calls PQsetdbLogin() with null pointers - for the login and pwd parameters. + for the login and pwd parameters. It is provided primarily + for backward compatibility with old programs. + + + + + +PQconnectdb + Makes a new connection to a backend. + +PGconn *PQconnectdb(const char *conninfo) + + This routine opens a new database connection using parameters + taken from a string. Unlike PQsetdbLogin(), the parameter set + can be extended without changing the function signature, so use + of this routine is encouraged for new application + programming. The passed string can be empty to use all default + parameters, or it can contain one or more parameter settings + separated by whitespace. Each parameter setting is in the form + keyword = value. (To write a null value or a value containing + spaces, surround it with single quotes, eg, keyword = 'a value'. + Single quotes within the value must be written as \'. Spaces + around the equal sign are optional.) The currently recognized + parameter keywords are: + + + +host -- host to connect to. +If a non-zero-length string is specified, TCP/IP communication is used. +Without a host name, libpq will connect using a local Unix domain socket. + + + + +port -- port number to connect to at the server host, +or socket filename extension for Unix-domain connections. + + + + +dbname -- database name. + + + + +user -- user name for authentication. + + + + +password -- +password used if the backend demands password authentication. + + + + +authtype -- authorization type. (No longer used, +since the backend now chooses how to authenticate users. libpq still +accepts and ignores this keyword for backward compatibility.) + + + + +options -- trace/debug options to send to backend. + + + + +tty -- file or tty for optional debug output. + + + +Like PQsetdbLogin, PQconnectdb uses environment variables or built-in +default values for unspecified options. @@ -196,7 +168,7 @@ PQconninfoOption *PQconndefaults(void) struct PQconninfoOption { char *keyword; /* The keyword of the option */ - char *environ; /* Fallback environment variable name */ + char *envvar; /* Fallback environment variable name */ char *compiled; /* Fallback compiled in default value */ char *val; /* Options value */ char *label; /* Label for field in connect dialog */ @@ -211,10 +183,59 @@ struct PQconninfoOption Returns the address of the connection options structure. This may - be used to determine all possible options and their current values. + be used to determine all possible PQconnectdb options and their + current default values. The return value points to an array of + PQconninfoOption structs, which ends with an entry having a NULL + keyword pointer. Note that the default values ("val" fields) + will depend on environment variables and other context. + Callers must treat the connection options data as read-only. + + +PQfinish + Close the connection to the backend. Also frees + memory used by the PGconn object. + +void PQfinish(PGconn *conn) + +Note that even if the backend connection attempt fails (as +indicated by PQstatus), the application should call PQfinish +to free the memory used by the PGconn object. +The PGconn pointer should not be used after PQfinish has been called. + + + + + +PQreset + Reset the communication port with the backend. + +void PQreset(PGconn *conn) + + This function will close the connection + to the backend and attempt to reestablish a new + connection to the same postmaster, using all the same + parameters previously used. This may be useful for + error recovery if a working connection is lost. + + + + + + + +libpq application programmers should be careful to +maintain the PGconn abstraction. Use the accessor functions below to get +at the contents of PGconn. Avoid directly referencing the fields of the +PGconn structure because they are subject to change in the future. +(Beginning in Postgres release 6.4, the +definition of struct PGconn is not even provided in libpq-fe.h. If you +have old code that accesses PGconn fields directly, you can keep using it +by including libpq-int.h too, but you are encouraged to fix the code +soon.) + PQdb @@ -222,33 +243,46 @@ struct PQconninfoOption char *PQdb(PGconn *conn) +PQdb and the next several functions return the values established +at connection. These values are fixed for the life of the PGconn +object. + + + + + +PQuser + Returns the user name of the connection. + +char *PQuser(PGconn *conn) + + + + + + +PQpass + Returns the password of the connection. + +char *PQpass(PGconn *conn) + PQhost - Returns the host name of the connection. + Returns the server host name of the connection. char *PQhost(PGconn *conn) - - -PQoptions - Returns the pgoptions used in the connection. - -char *PQoptions(PGconn *conn) - - - - PQport - Returns the pgport of the connection. + Returns the port of the connection. char *PQport(PGconn *conn) @@ -258,13 +292,23 @@ char *PQport(PGconn *conn) PQtty - Returns the pgtty of the connection. + Returns the debug tty of the connection. char *PQtty(PGconn *conn) + + +PQoptions + Returns the backend options used in the connection. + +char *PQoptions(PGconn *conn) + + + + PQstatus @@ -274,43 +318,42 @@ char *PQtty(PGconn *conn) ConnStatusType *PQstatus(PGconn *conn) +A failed connection attempt is signaled by status CONNECTION_BAD. +Ordinarily, an OK status will remain so until PQfinish, but a +communications failure might result in the status changing to +CONNECTION_BAD prematurely. In that case the application could +try to recover by calling PQreset. PQerrorMessage - Returns the error message associated with the connection + Returns the error message most recently generated by + an operation on the connection. char *PQerrorMessage(PGconn* conn); +Nearly all libpq functions will set PQerrorMessage if they fail. +Note that by libpq convention, a non-empty PQerrorMessage will +include a trailing newline. -PQfinish - Close the connection to the backend. Also frees - memory used by the PGconn structure. The PGconn - pointer should not be used after PQfinish has been - called. +PQbackendPID + Returns the process ID of the backend server handling this + connection. -void PQfinish(PGconn *conn) +int PQbackendPID(PGconn *conn); +The backend PID is useful for debugging purposes and for comparison +to NOTIFY messages (which include the PID of the notifying backend). +Note that the PID belongs to a process executing on the database +server host, not the local host! - - -PQreset - 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 postmaster. - -void PQreset(PGconn *conn) - - - @@ -319,29 +362,45 @@ void PQreset(PGconn *conn) Query Execution Functions +Once a connection to a database server has been successfully +established, the functions described here are used to perform +SQL queries and commands. PQexec - Submit a query to Postgres. Returns a PGresult - 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. + Submit a query to Postgres + and wait for the result. PGresult *PQexec(PGconn *conn, const char *query); - The PGresult structure encapsulates the query - result returned by the backend. libpq programmers - should be careful to maintain the PGresult - abstraction. Use the accessor functions described - below to retrieve the results of the query. Avoid - directly referencing the fields of the PGresult - structure as they are subject to change in the - future. + Returns a PGresult pointer or possibly a NULL pointer. + A non-NULL pointer will generally be returned except in + out-of-memory conditions or serious errors such as inability + to send the query to the backend. + If a NULL is returned, it + should be treated like a PGRES_FATAL_ERROR result. Use + PQerrorMessage to get more information about the error. + + + +The PGresult structure encapsulates the query result +returned by the backend. +libpq application programmers should be careful to +maintain the PGresult abstraction. Use the accessor functions below to get +at the contents of PGresult. Avoid directly referencing the fields of the +PGresult structure because they are subject to change in the future. +(Beginning in Postgres release 6.4, the +definition of struct PGresult is not even provided in libpq-fe.h. If you +have old code that accesses PGresult fields directly, you can keep using it +by including libpq-int.h too, but you are encouraged to fix the code +soon.) + + PQresultStatus @@ -350,21 +409,42 @@ PGresult *PQexec(PGconn *conn, PGRES_EMPTY_QUERY, 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, +PGRES_COPY_OUT, /* Copy Out (from server) data transfer started */ +PGRES_COPY_IN, /* Copy In (to server) data transfer started */ PGRES_BAD_RESPONSE, /* an unexpected response was received */ PGRES_NONFATAL_ERROR, PGRES_FATAL_ERROR If the result status is PGRES_TUPLES_OK, then the - following routines can be used to retrieve the - tuples returned by the query. + routines described below can be used to retrieve the + tuples returned by the query. Note that a SELECT that + happens to retrieve zero tuples still shows PGRES_TUPLES_OK; + PGRES_COMMAND_OK is for commands that can never return tuples. -PQntuples returns the number of tuples (instances) +PQresultErrorMessage +returns the error message associated with the query, or an empty string +if there was no error. + +const char *PQresultErrorMessage(PGresult *res); + +Immediately following a PQexec or PQgetResult call, PQerrorMessage +(on the connection) will return the same string as PQresultErrorMessage +(on the result). However, a PGresult will retain its error message +until destroyed, whereas the connection's error message will change when +subsequent operations are done. Use PQresultErrorMessage when you want to +know the status associated with a particular PGresult; use PQerrorMessage +when you want to know the status from the latest operation on the connection. + + + + + +PQntuples + Returns the number of tuples (instances) in the query result. int PQntuples(PGresult *res); @@ -376,13 +456,26 @@ int PQntuples(PGresult *res); PQnfields Returns the number of fields - (attributes) in the query result. + (attributes) in each tuple of the query result. int PQnfields(PGresult *res); + + +PQbinaryTuples + Returns 1 if the PGresult contains binary tuple data, + 0 if it contains ASCII data. + +int PQbinaryTuples(PGresult *res); + +Currently, binary tuple data can only be returned by a query that +extracts data from a BINARY cursor. + + + PQfname @@ -405,6 +498,7 @@ int PQfnumber(PGresult *res, char* field_name); + -1 is returned if the given name does not match any field. @@ -424,13 +518,13 @@ Oid PQftype(PGresult *res, PQfsize - Returns the size in bytes of the field + Returns the size in bytes of the field associated with the given field index. If the size returned is -1, the field is a variable length field. Field indices start at 0. -short PQfsize(PGresult *res, - int field_index); +int PQfsize(PGresult *res, + int field_index); @@ -451,24 +545,27 @@ int PQfmod(PGresult *res, PQgetvalue - Returns the field (attribute) value. - For most queries, the value returned by PQgetvalue - is a null-terminated ASCII string representation - of the attribute value. If the query was a result - of a BINARY cursor, then the value returned by - PQgetvalue is the binary representation of the - type in the internal format of the backend server. - It is the programmer's responsibility to cast and - convert the data to the correct C type. The value - returned by PQgetvalue points to storage that is - part of the PGresult structure. One must explicitly - copy the value into other storage if it is to - be used past the lifetime of the PGresult structure itself. + Returns a single field (attribute) value of one tuple + of a PGresult. + Tuple and field indices start at 0. char* PQgetvalue(PGresult *res, int tup_num, int field_num); + For most queries, the value returned by PQgetvalue + is a null-terminated ASCII string representation + of the attribute value. If the query extracted data from + a BINARY cursor, then the value returned by + PQgetvalue is the binary representation of the + type in the internal format of the backend server. + It is the programmer's responsibility to cast and + convert the data to the correct C type. The pointer + returned by PQgetvalue points to storage that is + part of the PGresult structure. One should not modify it, + and one must explicitly + copy the value into other storage if it is to + be used past the lifetime of the PGresult structure itself. @@ -476,37 +573,45 @@ char* PQgetvalue(PGresult *res, PQgetisnull Tests a field for a NULL entry. + Tuple and field indices start at 0. int PQgetisnull(PGresult *res, int tup_num, int field_num); This function returns 1 if the field contains a NULL, 0 if - it contains a known value. + it contains a non-null value. (Note that PQgetvalue + will return an empty string, not a null pointer, for a NULL + field.) PQgetlength - Returns the length of a field - (attribute) in bytes. If the field is a struct - varlena, the length returned here does not include - the size field of the varlena, i.e., it is 4 bytes - less. + Returns the length of a field + (attribute) in bytes. + Tuple and field indices start at 0. int PQgetlength(PGresult *res, int tup_num, int field_num); +This is the actual data length for the particular data value, +whereas PQfsize shows the allocated space for all entries in +this column. +If the field is a struct + varlena, the length returned here does not include + the size field of the varlena, i.e., it is 4 bytes + less. PQcmdStatus - Returns the command status associated with the - last query command. + Returns the command status string from the SQL command that + generated the PGresult. char *PQcmdStatus(PGresult *res); @@ -516,12 +621,13 @@ char *PQcmdStatus(PGresult *res); PQcmdTuples - Returns the number of rows affected by the last command. + Returns the number of rows affected by the SQL command. const char *PQcmdTuples(PGresult *res); - If the last command was INSERT, UPDATE or DELETE, this returns - a string containing the number of rows affected. If the last + If the SQL command that generated the + PGresult was INSERT, UPDATE or DELETE, this returns a + string containing the number of rows affected. If the command was anything else, it returns the empty string. @@ -530,7 +636,7 @@ const char *PQcmdTuples(PGresult *res); PQoidStatus Returns a string with the object id of the tuple - inserted if the last query is an INSERT command. + inserted, if the SQL command was an INSERT. Otherwise, returns an empty string. char* PQoidStatus(PGresult *res); @@ -562,8 +668,9 @@ struct _PQprintOpt char **fieldName; /* null terminated array of replacement field names */ }; - This funtion is intended to replace PQprintTuples(), which is - now obsolete. + This function is intended to replace PQprintTuples(), which is + now obsolete. The psql program uses + PQprint() to display query results. @@ -588,13 +695,12 @@ void PQprintTuples(PGresult* res, Prints out all the tuples and, optionally, the attribute names to the specified output stream. -void PQdisplayTuples( - PGresult* res, +void PQdisplayTuples(PGresult* res, FILE* fout, /* output stream */ int fillAlign, /* space fill to align columns */ const char *fieldSep, /* field separator */ - int printHeader, /* display headers? */ - int quiet); /* suppress print of row count at end */ + int printHeader, /* display headers? */ + int quiet); /* suppress print of row count at end */ PQdisplayTuples() was intended to supersede PQprintTuples(), and is in turn superseded by PQprint(). @@ -604,14 +710,36 @@ void PQdisplayTuples( PQclear Frees the storage associated with the PGresult. - Every query result should be properly freed when - it is no longer used. Failure to do this will - result in memory leaks in the frontend application. + Every query result should be freed via PQclear when + it is no longer needed. void PQclear(PQresult *res); + You can keep a PGresult object around for as long as you + need it; it does not go away when you issue a new query, + nor even if you close the connection. To get rid of it, + you must call PQclear. Failure to do this will + result in memory leaks in the frontend application. + + + +PQmakeEmptyPGresult + Constructs an empty PGresult object with the given status. + +PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); + +This is libpq's internal routine to allocate and initialize an empty +PGresult object. It is exported because some applications find it +useful to generate result objects (particularly objects with error +status) themselves. If conn is not NULL and status indicates an error, +the connection's current errorMessage is copied into the PGresult. +Note that PQclear should eventually be called on the object, just +as with a PGresult returned by libpq itself. + + + @@ -715,11 +843,14 @@ functions: PQconsumeInput If input is available from the backend, consume it. -void PQconsumeInput(PGconn *conn); +int PQconsumeInput(PGconn *conn); - 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 normally returns 1 indicating "no error", but returns +0 if there was some kind of trouble (in which case PQerrorMessage +is set). Note that the result does not say whether any input data +was actually collected. After calling PQconsumeInput, +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 @@ -841,8 +972,11 @@ PGresult* PQfn(PGconn* conn, PQArgBlock *args, int nargs); - The fnid argument is the object identifier of the function to be executed. result_buf is the buffer in which - to load the return value. The caller must have allocated sufficient space to store the return value. The + The fnid argument is the object identifier of the function to be + executed. + result_buf is the buffer in which + to place the return value. The caller must have allocated + sufficient space to store the return value. The result length will be returned in the storage pointed to by result_len. If the result is to be an integer value, than result_is_int should be set to 1; otherwise @@ -874,7 +1008,8 @@ typedef struct { Postgres 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 +notification condition with the LISTEN command (and can stop listening +with the UNLISTEN 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 @@ -883,9 +1018,9 @@ Commonly the condition name is the same as the associated relation, but it is not necessary for there to be any associated relation. -libpq applications submit LISTEN commands as ordinary -SQL queries. Subsequently, arrival of NOTIFY messages can be detected by -calling PQnotifies(). +libpq applications submit LISTEN and UNLISTEN +commands as ordinary SQL queries. Subsequently, arrival of NOTIFY +messages can be detected by calling PQnotifies(). @@ -894,22 +1029,23 @@ calling PQnotifies(). PQnotifies 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. + there are no pending notifications. Once a notification is + returned from PQnotifies, it is considered handled and will be + removed from the list of notifications. PGnotify* PQnotifies(PGconn *conn); 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. + +The second sample program gives an example of the use +of asynchronous notification. + PQnotifies() does not actually read backend data; it just returns messages previously absorbed by another libpq function. In prior @@ -932,10 +1068,10 @@ processing of the query. Functions Associated with the COPY Command - The copy command in Postgres has options to read from + The COPY command in Postgres has options to read from or write to the network connection used by libpq. - Therefore, functions are necessary to access this network connection directly so applications may take full - advantage of this capability. + Therefore, functions are necessary to access this network + connection directly so applications may take advantage of this capability. @@ -950,7 +1086,13 @@ processing of the query. PQgetline Reads a newline-terminated line of characters (transmitted by the backend server) into a buffer - string of size length. Like fgets(3), this routine copies up to length-1 characters into string. + string of size length. + +int PQgetline(PGconn *conn, + char *string, + int length) + + Like fgets(3), this routine copies up to length-1 characters into string. It is like gets(3), however, in that it converts the terminating newline into a null character. PQgetline returns EOF at EOF, 0 if the entire line @@ -958,35 +1100,85 @@ processing of the query. terminating newline has not yet been read. Notice that the application must check to see if a 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 - the return value of PQgetline very carefully. - The code in + which indicates that the backend server has finished sending + the results of the copy command. +If the application might +receive lines that are more than length-1 characters long, +care is needed to be sure one recognizes the "\." line correctly +(and does not, for example, mistake the end of a long data line +for a terminator line). +The code in ../src/bin/psql/psql.c - contains routines that correctly handle the copy - protocol. - -int PQgetline(PGconn *conn, - char *string, - int length) - +contains routines that correctly handle the copy protocol. + + + +PQgetlineAsync + Reads a newline-terminated line of characters + (transmitted by the backend server) into a buffer + without blocking. + +int PQgetlineAsync(PGconn *conn, + char *buffer, + int bufsize) + +This routine is similar to PQgetline, but it can be used by applications +that must read COPY data asynchronously, that is without blocking. +Having issued the COPY command and gotten a PGRES_COPY_OUT response, the +application should call PQconsumeInput and PQgetlineAsync until the +end-of-data signal is detected. Unlike PQgetline, this routine takes +responsibility for detecting end-of-data. +On each call, PQgetlineAsync will return data if a complete newline- +terminated data line is available in libpq's input buffer, or if the +incoming data line is too long to fit in the buffer offered by the caller. +Otherwise, no data is returned until the rest of the line arrives. +The routine returns -1 if the end-of-copy-data marker has been recognized, +or 0 if no data is available, or a positive number giving the number of +bytes of data returned. If -1 is returned, the caller must next call +PQendcopy, and then return to normal processing. +The data returned will not extend beyond a newline character. If possible +a whole line will be returned at one time. But if the buffer offered by +the caller is too small to hold a line sent by the backend, then a partial +data line will be returned. This can be detected by testing whether the +last returned byte is '\n' or not. +The returned string is not null-terminated. (If you want to add a +terminating null, be sure to pass a bufsize one smaller than the room +actually available.) + + + PQputline - Sends a null-terminated string to the backend - server. - The application must explicitly send the two - characters "\." on a final line to indicate to the backend that it - has finished sending its data. +Sends a null-terminated string to the backend server. +Returns 0 if OK, EOF if unable to send the string. -void PQputline(PGconn *conn, - char *string); +int PQputline(PGconn *conn, + char *string); +Note the application must explicitly send the two +characters "\." on a final line to indicate to the backend that it +has finished sending its data. + + + + + +PQputnbytes +Sends a non-null-terminated string to the backend server. +Returns 0 if OK, EOF if unable to send the string. + +int PQputnbytes(PGconn *conn, + const char *buffer, + int nbytes); + +This is exactly like PQputline, except that the data buffer need +not be null-terminated since the number of bytes to send is +specified directly. @@ -1120,10 +1312,8 @@ any creation of a new PGconn object. User Authentication Functions - If the user has generated the appropriate authentication credentials - (e.g., obtaining Kerberos tickets), - the frontend/backend authentication process is handled - by PQexec without any further intervention. +The frontend/backend authentication process is handled +by PQconnectdb without any further intervention. The authentication method is now determined entirely by the DBA (see pga_hba.conf(5)). The following routines no longer have any effect and should not be used. @@ -1166,6 +1356,131 @@ void fe_setauthsvc(char *name, + +Environment Variables + + +The following environment variables can be used to select default +connection parameter values, which will be used by PQconnectdb or +PQsetdbLogin if no value is directly specified by the calling code. +These are useful to avoid hard-coding database names into simple +application programs. + + + + +PGHOST sets the default server name. +If a non-zero-length string is specified, TCP/IP communication is used. +Without a host name, libpq will connect using a local Unix domain socket. + + + + +PGPORT sets the default port or local Unix domain socket +file extension for communicating with the Postgres +backend. + + + + +PGDATABASE sets the default Postgres database name. + + + + +PGUSER +sets the username used to connect to the database and for authentication. + + + + +PGPASSWORD +sets the password used if the backend demands password authentication. + + + + +PGREALM sets the Kerberos realm to use with Postgres, + if it is different from the local realm. If +PGREALM is set, Postgres applications will attempt + authentication with servers for this realm and use + separate ticket files to avoid conflicts with local + ticket files. This environment variable is only + used if Kerberos authentication is selected by the backend. + + + + +PGOPTIONS sets additional runtime options for the Postgres backend. + + + + +PGTTY sets the file or tty on which debugging messages from the backend server are displayed. + + + + + + +The following environment variables can be used to specify user-level default +behavior for every Postgres session: + + + + +PGDATESTYLE +sets the default style of date/time representation. + + + + +PGTZ +sets the default time zone. + + + + + + +The following environment variables can be used to specify default internal +behavior for every Postgres session: + + + + +PGGEQO +sets the default mode for the genetic optimizer. + + + + +PGRPLANS +sets the default mode to allow or disable right-sided plans in the optimizer. + + + + +PGCOSTHEAP +sets the default cost for heap searches for the optimizer. + + + + +PGCOSTINDEX +sets the default cost for indexed searches for the optimizer. + + + + + + +Refer to the SET SQL command +for information on correct values for these environment variables. + + + + Caveats