From e6c36081c286435a8cea19109bcb2e183092555b Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Sat, 1 Sep 2007 23:06:29 +0000 Subject: [PATCH] More SGML alignment cleanups. --- doc/src/sgml/libpq.sgml | 2941 ++++++++++++++++++++------------------- 1 file changed, 1472 insertions(+), 1469 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 5e28f8010a..0e137b266b 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -74,251 +74,253 @@ PGconn *PQconnectdb(const char *conninfo); - - - - This function opens a new database connection using the parameters taken - from the string conninfo. Unlike PQsetdbLogin below, - the parameter set can be extended without changing the function signature, - so use of this function (or its nonblocking analogues PQconnectStart - and PQconnectPoll) is preferred 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. - Spaces around the equal sign are optional. - To write an empty value or a value containing - spaces, surround it with single quotes, e.g., - keyword = 'a value'. - Single quotes and backslashes within the value must be escaped with a - backslash, i.e., \' and \\. - + + This function opens a new database connection using the parameters taken + from the string conninfo. Unlike PQsetdbLogin below, + the parameter set can be extended without changing the function signature, + so use of this function (or its nonblocking analogues PQconnectStart + and PQconnectPoll) is preferred for new application programming. + - - The currently recognized parameter key words are: + + 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. + Spaces around the equal sign are optional. + To write an empty value or a value containing + spaces, surround it with single quotes, e.g., + keyword = 'a value'. + Single quotes and backslashes within the value must be escaped with a + backslash, i.e., \' and \\. + - - - host - - - Name of host to connect to.host name - If this begins with a slash, it specifies Unix-domain - communication rather than TCP/IP communication; the value is the - name of the directory in which the socket file is stored. The - default behavior when host is not specified - is to connect to a Unix-domain - socketUnix domain socket in - /tmp (or whatever socket directory was specified - when PostgreSQL was built). On machines without - Unix-domain sockets, the default is to connect to localhost. - - - + + The currently recognized parameter key words are: - - hostaddr - - - Numeric IP address of host to connect to. This should be in the - standard IPv4 address format, e.g., 172.28.40.9. If - your machine supports IPv6, you can also use those addresses. - TCP/IP communication is - always used when a nonempty string is specified for this parameter. - - - Using hostaddr instead of host allows the - application to avoid a host name look-up, which might be important in - applications with time constraints. However, Kerberos and GSSAPI authentication - requires the host name. The following therefore applies: If - host is specified without hostaddr, a host name - lookup occurs. If hostaddr is specified without - host, the value for hostaddr gives the remote - address. When Kerberos is used, a reverse name query occurs to obtain - the host name for Kerberos. If both - host and hostaddr are specified, the value for - hostaddr gives the remote address; the value for - host is ignored, unless Kerberos is used, in which case that - value is used for Kerberos authentication. (Note that authentication is - likely to fail if libpq is passed a host name - that is not the name of the machine at hostaddr.) Also, - host rather than hostaddr is used to identify - the connection in ~/.pgpass (see - ). - - - Without either a host name or host address, - libpq will connect using a - local Unix-domain socket; or on machines without Unix-domain - sockets, it will attempt to connect to localhost. - - - + + + host + + + Name of host to connect to.host name + If this begins with a slash, it specifies Unix-domain + communication rather than TCP/IP communication; the value is the + name of the directory in which the socket file is stored. The + default behavior when host is not specified + is to connect to a Unix-domain + socketUnix domain socket in + /tmp (or whatever socket directory was specified + when PostgreSQL was built). On machines without + Unix-domain sockets, the default is to connect to localhost. + + + - - port - - - Port number to connect to at the server host, or socket file - name extension for Unix-domain - connections.port - - - + + hostaddr + + + Numeric IP address of host to connect to. This should be in the + standard IPv4 address format, e.g., 172.28.40.9. If + your machine supports IPv6, you can also use those addresses. + TCP/IP communication is + always used when a nonempty string is specified for this parameter. + + + + Using hostaddr instead of host allows the + application to avoid a host name look-up, which might be important in + applications with time constraints. However, Kerberos and GSSAPI authentication + requires the host name. The following therefore applies: If + host is specified without hostaddr, a host name + lookup occurs. If hostaddr is specified without + host, the value for hostaddr gives the remote + address. When Kerberos is used, a reverse name query occurs to obtain + the host name for Kerberos. If both + host and hostaddr are specified, the value for + hostaddr gives the remote address; the value for + host is ignored, unless Kerberos is used, in which case that + value is used for Kerberos authentication. (Note that authentication is + likely to fail if libpq is passed a host name + that is not the name of the machine at hostaddr.) Also, + host rather than hostaddr is used to identify + the connection in ~/.pgpass (see + ). + + + + Without either a host name or host address, + libpq will connect using a + local Unix-domain socket; or on machines without Unix-domain + sockets, it will attempt to connect to localhost. + + + + + + port + + + Port number to connect to at the server host, or socket file + name extension for Unix-domain + connections.port + + + - - dbname - - - The database name. Defaults to be the same as the user name. - - - - - - user - - - PostgreSQL user name to connect as. - Defaults to be the same as the operating system name of the user - running the application. - - - - - - password - - - Password to be used if the server demands password authentication. - - - - - - connect_timeout - - - Maximum wait for connection, in seconds (write as a decimal integer - string). Zero or not specified means wait indefinitely. It is not - recommended to use a timeout of less than 2 seconds. - - - - - - options - + + dbname + - Command-line options to be sent to the server. + The database name. Defaults to be the same as the user name. - - + + - - tty - - - Ignored (formerly, this specified where to send server debug output). - - - - - - sslmode - + + user + - This option determines whether or with what priority an - SSL connection will be negotiated with the - server. There are four modes: disable will attempt - only an unencrypted SSL connection; - allow will negotiate, trying first a - non-SSL connection, then if that fails, trying an - SSL connection; prefer (the default) - will negotiate, trying first an SSL connection, - then if that fails, trying a regular non-SSL - connection; require will try only an - SSL connection. + PostgreSQL user name to connect as. + Defaults to be the same as the operating system name of the user + running the application. + + + + password + - If PostgreSQL is compiled without SSL support, - using option require will cause an error, while - options allow and prefer will be - accepted but libpq will not in fact attempt - an SSL - connection.SSLwith libpq + Password to be used if the server demands password authentication. - - + + - - requiressl - + + connect_timeout + - This option is deprecated in favor of the sslmode - setting. + Maximum wait for connection, in seconds (write as a decimal integer + string). Zero or not specified means wait indefinitely. It is not + recommended to use a timeout of less than 2 seconds. + + + + options + + + Command-line options to be sent to the server. + + + + + + tty + - If set to 1, an SSL connection to the server - is required (this is equivalent to sslmode - require). libpq will then refuse - to connect if the server does not accept an - SSL connection. If set to 0 (default), - libpq will negotiate the connection type with - the server (equivalent to sslmode - prefer). This option is only available if - PostgreSQL is compiled with SSL support. + Ignored (formerly, this specified where to send server debug output). - - + + - - krbsrvname - - - Kerberos service name to use when authenticating with Kerberos 5 - or GSSAPI. - This must match the service name specified in the server - configuration for Kerberos authentication to succeed. (See also - and .) - - - + + sslmode + + + This option determines whether or with what priority an + SSL connection will be negotiated with the + server. There are four modes: disable will attempt + only an unencrypted SSL connection; + allow will negotiate, trying first a + non-SSL connection, then if that fails, trying an + SSL connection; prefer (the default) + will negotiate, trying first an SSL connection, + then if that fails, trying a regular non-SSL + connection; require will try only an + SSL connection. + - - gsslib - - - GSS library to use for GSSAPI authentication. Only used on Windows. - Set to gssapi to force libpq to use the GSSAPI - library for authentication instead of the default SSPI. - - - + + If PostgreSQL is compiled without SSL support, + using option require will cause an error, while + options allow and prefer will be + accepted but libpq will not in fact attempt + an SSL + connection.SSLwith libpq + + + - - service - - - Service name to use for additional parameters. It specifies a service - name in pg_service.conf that holds additional connection parameters. - This allows applications to specify only a service name so connection parameters - can be centrally maintained. See . - - - - + + requiressl + + + This option is deprecated in favor of the sslmode + setting. + - If any parameter is unspecified, then the corresponding - environment variable (see ) - is checked. If the environment variable is not set either, - then the indicated built-in defaults are used. + + If set to 1, an SSL connection to the server + is required (this is equivalent to sslmode + require). libpq will then refuse + to connect if the server does not accept an + SSL connection. If set to 0 (default), + libpq will negotiate the connection type with + the server (equivalent to sslmode + prefer). This option is only available if + PostgreSQL is compiled with SSL support. + + + + + + krbsrvname + + + Kerberos service name to use when authenticating with Kerberos 5 + or GSSAPI. + This must match the service name specified in the server + configuration for Kerberos authentication to succeed. (See also + and .) + + + + + + gsslib + + + GSS library to use for GSSAPI authentication. Only used on Windows. + Set to gssapi to force libpq to use the GSSAPI + library for authentication instead of the default SSPI. + + + + + + service + + + Service name to use for additional parameters. It specifies a service + name in pg_service.conf that holds additional connection parameters. + This allows applications to specify only a service name so connection parameters + can be centrally maintained. See . + + + + + + If any parameter is unspecified, then the corresponding + environment variable (see ) + is checked. If the environment variable is not set either, + then the indicated built-in defaults are used. @@ -381,164 +383,164 @@ PGconn *PQsetdb(char *pghost, PQconnectStartPQconnectStart PQconnectPollPQconnectPoll - - nonblocking connection - Make a connection to the database server in a nonblocking manner. - - - PGconn *PQconnectStart(const char *conninfo); - - - - PostgresPollingStatusType PQconnectPoll(PGconn *conn); - - - - - These two functions are used to open a connection to a database server such - that your application's thread of execution is not blocked on remote I/O - whilst doing so. - The point of this approach is that the waits for I/O to complete can occur - in the application's main loop, rather than down inside - PQconnectdb, and so the application can manage this - operation in parallel with other activities. - - - - The database connection is made using the parameters taken from the string - conninfo, passed to PQconnectStart. This string is in - the same format as described above for PQconnectdb. - - - Neither PQconnectStart nor PQconnectPoll will block, so long as a number of - restrictions are met: - - - - The hostaddr and host parameters are used appropriately to ensure that - name and reverse name queries are not made. See the documentation of - these parameters under PQconnectdb above for details. - - - - - - If you call PQtrace, ensure that the stream object - into which you trace will not block. - - - - - - You ensure that the socket is in the appropriate state - before calling PQconnectPoll, as described below. - - - - - - - To begin a nonblocking connection request, call conn = PQconnectStart("connection_info_string"). - If conn is null, then libpq has been unable to allocate a new PGconn - structure. Otherwise, a valid PGconn pointer is returned (though not yet - representing a valid connection to the database). On return from - PQconnectStart, call status = PQstatus(conn). If status equals - CONNECTION_BAD, PQconnectStart has failed. - - - - If PQconnectStart succeeds, the next stage is to poll - libpq so that it can proceed with the connection sequence. - Use PQsocket(conn) to obtain the descriptor of the - socket underlying the database connection. - Loop thus: If PQconnectPoll(conn) last returned - PGRES_POLLING_READING, wait until the socket is ready to - read (as indicated by select(), poll(), or - similar system function). - Then call PQconnectPoll(conn) again. - Conversely, if PQconnectPoll(conn) last returned - PGRES_POLLING_WRITING, wait until the socket is ready - to write, then call PQconnectPoll(conn) again. - If you have yet to call - PQconnectPoll, i.e., just after the call to - PQconnectStart, behave as if it last returned - PGRES_POLLING_WRITING. Continue this loop until - PQconnectPoll(conn) returns - PGRES_POLLING_FAILED, indicating the connection procedure - has failed, or PGRES_POLLING_OK, indicating the connection - has been successfully made. - - - - At any time during connection, the status of the connection can be - checked by calling PQstatus. If this gives CONNECTION_BAD, then the - connection procedure has failed; if it gives CONNECTION_OK, then the - connection is ready. Both of these states are equally detectable - from the return value of PQconnectPoll, described above. Other states might also occur - during (and only during) an asynchronous connection procedure. These - indicate the current stage of the connection procedure and might be useful - to provide feedback to the user for example. These statuses are: - - - - CONNECTION_STARTED + + nonblocking connection + Make a connection to the database server in a nonblocking manner. + + + PGconn *PQconnectStart(const char *conninfo); + + + + PostgresPollingStatusType PQconnectPoll(PGconn *conn); + + + + + These two functions are used to open a connection to a database server such + that your application's thread of execution is not blocked on remote I/O + whilst doing so. + The point of this approach is that the waits for I/O to complete can occur + in the application's main loop, rather than down inside + PQconnectdb, and so the application can manage this + operation in parallel with other activities. + + + + The database connection is made using the parameters taken from the string + conninfo, passed to PQconnectStart. This string is in + the same format as described above for PQconnectdb. + + + Neither PQconnectStart nor PQconnectPoll will block, so long as a number of + restrictions are met: + - Waiting for connection to be made. + The hostaddr and host parameters are used appropriately to ensure that + name and reverse name queries are not made. See the documentation of + these parameters under PQconnectdb above for details. - - - - CONNECTION_MADE + - Connection OK; waiting to send. + If you call PQtrace, ensure that the stream object + into which you trace will not block. - - - - CONNECTION_AWAITING_RESPONSE + - Waiting for a response from the server. + You ensure that the socket is in the appropriate state + before calling PQconnectPoll, as described below. - - - - CONNECTION_AUTH_OK - - - Received authentication; waiting for backend start-up to finish. - - - - - - CONNECTION_SSL_STARTUP - - - Negotiating SSL encryption. - - - - - - CONNECTION_SETENV - - - Negotiating environment-driven parameter settings. - - - - - - Note that, although these constants will remain (in order to maintain - compatibility), an application should never rely upon these occurring in a - particular order, or at all, or on the status always being one of these - documented values. An application might do something like this: + + + + + To begin a nonblocking connection request, call conn = PQconnectStart("connection_info_string"). + If conn is null, then libpq has been unable to allocate a new PGconn + structure. Otherwise, a valid PGconn pointer is returned (though not yet + representing a valid connection to the database). On return from + PQconnectStart, call status = PQstatus(conn). If status equals + CONNECTION_BAD, PQconnectStart has failed. + + + + If PQconnectStart succeeds, the next stage is to poll + libpq so that it can proceed with the connection sequence. + Use PQsocket(conn) to obtain the descriptor of the + socket underlying the database connection. + Loop thus: If PQconnectPoll(conn) last returned + PGRES_POLLING_READING, wait until the socket is ready to + read (as indicated by select(), poll(), or + similar system function). + Then call PQconnectPoll(conn) again. + Conversely, if PQconnectPoll(conn) last returned + PGRES_POLLING_WRITING, wait until the socket is ready + to write, then call PQconnectPoll(conn) again. + If you have yet to call + PQconnectPoll, i.e., just after the call to + PQconnectStart, behave as if it last returned + PGRES_POLLING_WRITING. Continue this loop until + PQconnectPoll(conn) returns + PGRES_POLLING_FAILED, indicating the connection procedure + has failed, or PGRES_POLLING_OK, indicating the connection + has been successfully made. + + + + At any time during connection, the status of the connection can be + checked by calling PQstatus. If this gives CONNECTION_BAD, then the + connection procedure has failed; if it gives CONNECTION_OK, then the + connection is ready. Both of these states are equally detectable + from the return value of PQconnectPoll, described above. Other states might also occur + during (and only during) an asynchronous connection procedure. These + indicate the current stage of the connection procedure and might be useful + to provide feedback to the user for example. These statuses are: + + + + CONNECTION_STARTED + + + Waiting for connection to be made. + + + + + + CONNECTION_MADE + + + Connection OK; waiting to send. + + + + + + CONNECTION_AWAITING_RESPONSE + + + Waiting for a response from the server. + + + + + + CONNECTION_AUTH_OK + + + Received authentication; waiting for backend start-up to finish. + + + + + + CONNECTION_SSL_STARTUP + + + Negotiating SSL encryption. + + + + + + CONNECTION_SETENV + + + Negotiating environment-driven parameter settings. + + + + + + Note that, although these constants will remain (in order to maintain + compatibility), an application should never rely upon these occurring in a + particular order, or at all, or on the status always being one of these + documented values. An application might do something like this: switch(PQstatus(conn)) { @@ -556,31 +558,31 @@ switch(PQstatus(conn)) feedback = "Connecting..."; } - - - - The connect_timeout connection parameter is ignored - when using PQconnectPoll; it is the application's - responsibility to decide whether an excessive amount of time has elapsed. - Otherwise, PQconnectStart followed by a - PQconnectPoll loop is equivalent to - PQconnectdb. - - - - Note that if PQconnectStart returns a non-null pointer, you must call - PQfinish when you are finished with it, in order to dispose of - the structure and any associated memory blocks. This must be done even if - the connection attempt fails or is abandoned. - - - - - - PQconndefaultsPQconndefaults - - - Returns the default connection options. + + + + The connect_timeout connection parameter is ignored + when using PQconnectPoll; it is the application's + responsibility to decide whether an excessive amount of time has elapsed. + Otherwise, PQconnectStart followed by a + PQconnectPoll loop is equivalent to + PQconnectdb. + + + + Note that if PQconnectStart returns a non-null pointer, you must call + PQfinish when you are finished with it, in order to dispose of + the structure and any associated memory blocks. This must be done even if + the connection attempt fails or is abandoned. + + + + + + PQconndefaultsPQconndefaults + + + Returns the default connection options. PQconninfoOption *PQconndefaults(void); @@ -599,66 +601,66 @@ typedef struct int dispsize; /* Field size in characters for dialog */ } PQconninfoOption; - - - - Returns a connection options array. This can be used to determine - all possible PQconnectdb options and their - current default values. The return value points to an array of - PQconninfoOption structures, which ends - with an entry having a null keyword pointer. The - null pointer is returned if memory could not be allocated. Note that - the current default values (val fields) - will depend on environment variables and other context. Callers - must treat the connection options data as read-only. - - - - After processing the options array, free it by passing it to - PQconninfoFree. If this is not done, a small amount of memory - is leaked for each call to PQconndefaults. - - - - - - - PQfinishPQfinish - - - Closes the connection to the server. Also frees - memory used by the PGconn object. - - void PQfinish(PGconn *conn); - - - - - Note that even if the server connection attempt fails (as - indicated by PQstatus), the application should call PQfinish - to free the memory used by the PGconn object. - The PGconn pointer must not be used again after - PQfinish has been called. - - - - - - PQresetPQreset - - - Resets the communication channel to the server. - - void PQreset(PGconn *conn); - - - - - This function will close the connection - to the server and attempt to reestablish a new - connection to the same server, using all the same - parameters previously used. This might be useful for - error recovery if a working connection is lost. + + + + Returns a connection options array. This can be used to determine + all possible PQconnectdb options and their + current default values. The return value points to an array of + PQconninfoOption structures, which ends + with an entry having a null keyword pointer. The + null pointer is returned if memory could not be allocated. Note that + the current default values (val fields) + will depend on environment variables and other context. Callers + must treat the connection options data as read-only. + + + + After processing the options array, free it by passing it to + PQconninfoFree. If this is not done, a small amount of memory + is leaked for each call to PQconndefaults. + + + + + + + PQfinishPQfinish + + + Closes the connection to the server. Also frees + memory used by the PGconn object. + + void PQfinish(PGconn *conn); + + + + + Note that even if the server connection attempt fails (as + indicated by PQstatus), the application should call PQfinish + to free the memory used by the PGconn object. + The PGconn pointer must not be used again after + PQfinish has been called. + + + + + + PQresetPQreset + + + Resets the communication channel to the server. + + void PQreset(PGconn *conn); + + + + + This function will close the connection + to the server and attempt to reestablish a new + connection to the same server, using all the same + parameters previously used. This might be useful for + error recovery if a working connection is lost. @@ -716,90 +718,90 @@ typedef struct libpq application programmers should be careful to maintain the PGconn abstraction. Use the accessor functions described below to get at the contents of PGconn. - Reference to internal PGconn fields using + Reference to internal PGconn fields using libpq-int.h is not recommended because they are subject to change in the future. - + - - The following functions return parameter values established at connection. - These values are fixed for the life of the PGconn object. + + The following functions return parameter values established at connection. + These values are fixed for the life of the PGconn object. - - - - PQdb - - PQdb - - + + + + PQdb + + PQdb + + - - - Returns the database name of the connection. - - char *PQdb(const PGconn *conn); - - - - + + + Returns the database name of the connection. + + char *PQdb(const PGconn *conn); + + + + - - - PQuser - - PQuser - - + + + PQuser + + PQuser + + - - - Returns the user name of the connection. - - char *PQuser(const PGconn *conn); - - - - + + + Returns the user name of the connection. + + char *PQuser(const PGconn *conn); + + + + - - - PQpass - - PQpass - - + + + PQpass + + PQpass + + - - - Returns the password of the connection. - - char *PQpass(const PGconn *conn); - - - - + + + Returns the password of the connection. + + char *PQpass(const PGconn *conn); + + + + - - - PQhost - - PQhost - - + + + PQhost + + PQhost + + - - - Returns the server host name of the connection. - - char *PQhost(const PGconn *conn); - - - - + + + Returns the server host name of the connection. + + char *PQhost(const PGconn *conn); + + + + - + PQport @@ -875,7 +877,7 @@ typedef struct - Returns the status of the connection. + Returns the status of the connection. ConnStatusType PQstatus(const PGconn *conn); @@ -1170,7 +1172,7 @@ typedef struct SSLin libpq Returns the SSL structure used in the connection, or null - if SSL is not in use. + if SSL is not in use. SSL *PQgetssl(const PGconn *conn); @@ -1185,7 +1187,7 @@ typedef struct You must define USE_SSL in order to get the - correct prototype for this function. Doing this will also + correct prototype for this function. Doing this will also automatically include ssl.h from OpenSSL. @@ -1460,66 +1462,66 @@ PGresult *PQprepare(PGconn *conn, connections; it will fail when using protocol 2.0. - - The function creates a prepared statement named - stmtName from the query string, which - must contain a single SQL command. stmtName can be - "" to create an unnamed statement, in which case any - pre-existing unnamed statement is automatically replaced; otherwise - it is an error if the statement name is already defined in the - current session. If any parameters are used, they are referred - to in the query as $1, $2, etc. - nParams is the number of parameters for which types - are pre-specified in the array paramTypes[]. (The - array pointer can be NULL when - nParams is zero.) paramTypes[] - specifies, by OID, the data types to be assigned to the parameter - symbols. If paramTypes is NULL, - or any particular element in the array is zero, the server assigns - a data type to the parameter symbol in the same way it would do - for an untyped literal string. Also, the query can use parameter - symbols with numbers higher than nParams; data types - will be inferred for these symbols as well. (See - PQdescribePrepared for a means to find out - what data types were inferred.) - - - - As with PQexec, the result is normally a - PGresult object whose contents indicate - server-side success or failure. A null result indicates - out-of-memory or inability to send the command at all. Use - PQerrorMessage to get more information about - such errors. - - - - + + The function creates a prepared statement named + stmtName from the query string, which + must contain a single SQL command. stmtName can be + "" to create an unnamed statement, in which case any + pre-existing unnamed statement is automatically replaced; otherwise + it is an error if the statement name is already defined in the + current session. If any parameters are used, they are referred + to in the query as $1, $2, etc. + nParams is the number of parameters for which types + are pre-specified in the array paramTypes[]. (The + array pointer can be NULL when + nParams is zero.) paramTypes[] + specifies, by OID, the data types to be assigned to the parameter + symbols. If paramTypes is NULL, + or any particular element in the array is zero, the server assigns + a data type to the parameter symbol in the same way it would do + for an untyped literal string. Also, the query can use parameter + symbols with numbers higher than nParams; data types + will be inferred for these symbols as well. (See + PQdescribePrepared for a means to find out + what data types were inferred.) + - Prepared statements for use with PQexecPrepared can also - be created by executing SQL statements. (But PQprepare - is more flexible since it does not require parameter types to be - pre-specified.) Also, although there is no libpq - function for deleting a prepared statement, the SQL statement - can be used for that purpose. - + + As with PQexec, the result is normally a + PGresult object whose contents indicate + server-side success or failure. A null result indicates + out-of-memory or inability to send the command at all. Use + PQerrorMessage to get more information about + such errors. + + + + - - - - - PQexecPrepared - - PQexecPrepared - - + Prepared statements for use with PQexecPrepared can also + be created by executing SQL statements. (But PQprepare + is more flexible since it does not require parameter types to be + pre-specified.) Also, although there is no libpq + function for deleting a prepared statement, the SQL statement + can be used for that purpose. + - - - Sends a request to execute a prepared statement with given - parameters, and waits for the result. + + + + + PQexecPrepared + + PQexecPrepared + + + + + + Sends a request to execute a prepared statement with given + parameters, and waits for the result. PGresult *PQexecPrepared(PGconn *conn, const char *stmtName, @@ -1529,384 +1531,384 @@ PGresult *PQexecPrepared(PGconn *conn, const int *paramFormats, int resultFormat); - + - - PQexecPrepared is like PQexecParams, - but the command to be executed is specified by naming a - previously-prepared statement, instead of giving a query string. - This feature allows commands that will be used repeatedly to be - parsed and planned just once, rather than each time they are - executed. The statement must have been prepared previously in - the current session. PQexecPrepared is supported - only in protocol 3.0 and later connections; it will fail when - using protocol 2.0. - + + PQexecPrepared is like PQexecParams, + but the command to be executed is specified by naming a + previously-prepared statement, instead of giving a query string. + This feature allows commands that will be used repeatedly to be + parsed and planned just once, rather than each time they are + executed. The statement must have been prepared previously in + the current session. PQexecPrepared is supported + only in protocol 3.0 and later connections; it will fail when + using protocol 2.0. + - - The parameters are identical to PQexecParams, except that the - name of a prepared statement is given instead of a query string, and the - paramTypes[] parameter is not present (it is not needed since - the prepared statement's parameter types were determined when it was created). - - - + + The parameters are identical to PQexecParams, except that the + name of a prepared statement is given instead of a query string, and the + paramTypes[] parameter is not present (it is not needed since + the prepared statement's parameter types were determined when it was created). + + + - - - PQdescribePrepared - - PQdescribePrepared - - + + + PQdescribePrepared + + PQdescribePrepared + + - - - Submits a request to obtain information about the specified - prepared statement, and waits for completion. + + + Submits a request to obtain information about the specified + prepared statement, and waits for completion. PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - + - - PQdescribePrepared allows an application to obtain - information about a previously prepared statement. - PQdescribePrepared is supported only in protocol 3.0 - and later connections; it will fail when using protocol 2.0. - + + PQdescribePrepared allows an application to obtain + information about a previously prepared statement. + PQdescribePrepared is supported only in protocol 3.0 + and later connections; it will fail when using protocol 2.0. + - - stmtName can be "" or NULL to reference - the unnamed statement, otherwise it must be the name of an existing - prepared statement. On success, a PGresult with - status PGRES_COMMAND_OK is returned. The - functions PQnparams and - PQparamtype can be applied to this - PGresult to obtain information about the parameters - of the prepared statement, and the functions - PQnfields, PQfname, - PQftype, etc provide information about the - result columns (if any) of the statement. - - - + + stmtName can be "" or NULL to reference + the unnamed statement, otherwise it must be the name of an existing + prepared statement. On success, a PGresult with + status PGRES_COMMAND_OK is returned. The + functions PQnparams and + PQparamtype can be applied to this + PGresult to obtain information about the parameters + of the prepared statement, and the functions + PQnfields, PQfname, + PQftype, etc provide information about the + result columns (if any) of the statement. + + + - - - PQdescribePortal - - PQdescribePortal - - + + + PQdescribePortal + + PQdescribePortal + + - - - Submits a request to obtain information about the specified - portal, and waits for completion. + + + Submits a request to obtain information about the specified + portal, and waits for completion. PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + - - PQdescribePortal allows an application to obtain - information about a previously created portal. - (libpq does not provide any direct access to - portals, but you can use this function to inspect the properties - of a cursor created with a DECLARE CURSOR SQL command.) - PQdescribePortal is supported only in protocol 3.0 - and later connections; it will fail when using protocol 2.0. - + + PQdescribePortal allows an application to obtain + information about a previously created portal. + (libpq does not provide any direct access to + portals, but you can use this function to inspect the properties + of a cursor created with a DECLARE CURSOR SQL command.) + PQdescribePortal is supported only in protocol 3.0 + and later connections; it will fail when using protocol 2.0. + - - portalName can be "" or NULL to reference - the unnamed portal, otherwise it must be the name of an existing - portal. On success, a PGresult with status - PGRES_COMMAND_OK is returned. The functions - PQnfields, PQfname, - PQftype, etc can be applied to the - PGresult to obtain information about the result - columns (if any) of the portal. - - - - - + + portalName can be "" or NULL to reference + the unnamed portal, otherwise it must be the name of an existing + portal. On success, a PGresult with status + PGRES_COMMAND_OK is returned. The functions + PQnfields, PQfname, + PQftype, etc can be applied to the + PGresult to obtain information about the result + columns (if any) of the portal. + + + + + - - The PGresultPGresult - structure encapsulates the result returned by the server. - 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. + + The PGresultPGresult + structure encapsulates the result returned by the server. + 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. - - - - PQresultStatus - - PQresultStatus - - + + + + PQresultStatus + + PQresultStatus + + - - - Returns the result status of the command. - - ExecStatusType PQresultStatus(const PGresult *res); - - + + + Returns the result status of the command. + + ExecStatusType PQresultStatus(const PGresult *res); + + - - PQresultStatus can return one of the following values: + + PQresultStatus can return one of the following values: - - - PGRES_EMPTY_QUERY - - - The string sent to the server was empty. - - - - - - PGRES_COMMAND_OK - - - Successful completion of a command returning no data. - - - - - - PGRES_TUPLES_OK - - - Successful completion of a command returning data (such as - a SELECT or SHOW). - - - - - - PGRES_COPY_OUT - - - Copy Out (from server) data transfer started. - - - - - - PGRES_COPY_IN - - - Copy In (to server) data transfer started. - - - - - - PGRES_BAD_RESPONSE - - - The server's response was not understood. - - - - - - PGRES_NONFATAL_ERROR - - - A nonfatal error (a notice or warning) occurred. - - - - - - PGRES_FATAL_ERROR - - - A fatal error occurred. - - - - - - If the result status is PGRES_TUPLES_OK, then - the functions described below can be used to retrieve the rows - returned by the query. Note that a SELECT - command that happens to retrieve zero rows still shows - PGRES_TUPLES_OK. - PGRES_COMMAND_OK is for commands that can never - return rows (INSERT, UPDATE, - etc.). A response of PGRES_EMPTY_QUERY might - indicate a bug in the client software. - - - - A result of status PGRES_NONFATAL_ERROR will - never be returned directly by PQexec or other - query execution functions; results of this kind are instead passed - to the notice processor (see ). - - - + + + PGRES_EMPTY_QUERY + + + The string sent to the server was empty. + + + - - - PQresStatus - - PQresStatus - - + + PGRES_COMMAND_OK + + + Successful completion of a command returning no data. + + + - - - Converts the enumerated type returned by - PQresultStatus into a string constant describing the - status code. The caller should not free the result. + + PGRES_TUPLES_OK + + + Successful completion of a command returning data (such as + a SELECT or SHOW). + + + - - char *PQresStatus(ExecStatusType status); - - - - + + PGRES_COPY_OUT + + + Copy Out (from server) data transfer started. + + + - - - PQresultErrorMessage - - PQresultErrorMessage - - + + PGRES_COPY_IN + + + Copy In (to server) data transfer started. + + + - - - Returns the error message associated with the command, or an empty string - if there was no error. - - char *PQresultErrorMessage(const PGresult *res); - - If there was an error, the returned string will include a trailing - newline. The caller should not free the result directly. It will - be freed when the associated PGresult handle is - passed to PQclear. - + + PGRES_BAD_RESPONSE + + + The server's response was not understood. + + + - - 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. - - - + + PGRES_NONFATAL_ERROR + + + A nonfatal error (a notice or warning) occurred. + + + - - PQresultErrorFieldPQresultErrorField - - - Returns an individual field of an error report. - - char *PQresultErrorField(const PGresult *res, int fieldcode); - - fieldcode is an error field identifier; see the symbols - listed below. NULL is returned if the - PGresult is not an error or warning result, - or does not include the specified field. Field values will normally - not include a trailing newline. The caller should not free the - result directly. It will be freed when the - associated PGresult handle is passed to - PQclear. - - - - The following field codes are available: - - - PG_DIAG_SEVERITY - - - The severity; the field contents are ERROR, - FATAL, or PANIC (in an error message), - or WARNING, NOTICE, DEBUG, - INFO, or LOG (in a notice message), or - a localized translation of one of these. Always present. - - - - - - - error codes - libpq - - PG_DIAG_SQLSTATE - - - The SQLSTATE code for the error. The SQLSTATE code identifies - the type of error that has occurred; it can be used by - front-end applications to perform specific operations (such - as error handling) in response to a particular database error. - For a list of the possible SQLSTATE codes, see . This field is not localizable, - and is always present. - - - - - - PG_DIAG_MESSAGE_PRIMARY - - - The primary human-readable error message (typically one line). - Always present. - - - - - - PG_DIAG_MESSAGE_DETAIL - - - Detail: an optional secondary error message carrying more - detail about the problem. Might run to multiple lines. - - - - - - PG_DIAG_MESSAGE_HINT - - - Hint: an optional suggestion what to do about the problem. - This is intended to differ from detail in that it offers advice - (potentially inappropriate) rather than hard facts. Might - run to multiple lines. - - - - - - PG_DIAG_STATEMENT_POSITION - + + PGRES_FATAL_ERROR + + + A fatal error occurred. + + + + + + If the result status is PGRES_TUPLES_OK, then + the functions described below can be used to retrieve the rows + returned by the query. Note that a SELECT + command that happens to retrieve zero rows still shows + PGRES_TUPLES_OK. + PGRES_COMMAND_OK is for commands that can never + return rows (INSERT, UPDATE, + etc.). A response of PGRES_EMPTY_QUERY might + indicate a bug in the client software. + + + + A result of status PGRES_NONFATAL_ERROR will + never be returned directly by PQexec or other + query execution functions; results of this kind are instead passed + to the notice processor (see ). + + + + + + + PQresStatus + + PQresStatus + + + + + + Converts the enumerated type returned by + PQresultStatus into a string constant describing the + status code. The caller should not free the result. + + + char *PQresStatus(ExecStatusType status); + + + + + + + + PQresultErrorMessage + + PQresultErrorMessage + + + + + + Returns the error message associated with the command, or an empty string + if there was no error. + + char *PQresultErrorMessage(const PGresult *res); + + If there was an error, the returned string will include a trailing + newline. The caller should not free the result directly. It will + be freed when the associated PGresult handle is + passed to PQclear. + + + + 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. + + + + + + PQresultErrorFieldPQresultErrorField + + + Returns an individual field of an error report. + + char *PQresultErrorField(const PGresult *res, int fieldcode); + + fieldcode is an error field identifier; see the symbols + listed below. NULL is returned if the + PGresult is not an error or warning result, + or does not include the specified field. Field values will normally + not include a trailing newline. The caller should not free the + result directly. It will be freed when the + associated PGresult handle is passed to + PQclear. + + + + The following field codes are available: + + + PG_DIAG_SEVERITY + + + The severity; the field contents are ERROR, + FATAL, or PANIC (in an error message), + or WARNING, NOTICE, DEBUG, + INFO, or LOG (in a notice message), or + a localized translation of one of these. Always present. + + + + + + + error codes + libpq + + PG_DIAG_SQLSTATE + + + The SQLSTATE code for the error. The SQLSTATE code identifies + the type of error that has occurred; it can be used by + front-end applications to perform specific operations (such + as error handling) in response to a particular database error. + For a list of the possible SQLSTATE codes, see . This field is not localizable, + and is always present. + + + + + + PG_DIAG_MESSAGE_PRIMARY + + + The primary human-readable error message (typically one line). + Always present. + + + + + + PG_DIAG_MESSAGE_DETAIL + + + Detail: an optional secondary error message carrying more + detail about the problem. Might run to multiple lines. + + + + + + PG_DIAG_MESSAGE_HINT + + + Hint: an optional suggestion what to do about the problem. + This is intended to differ from detail in that it offers advice + (potentially inappropriate) rather than hard facts. Might + run to multiple lines. + + + + + + PG_DIAG_STATEMENT_POSITION + A string containing a decimal integer indicating an error cursor position as an index into the original statement string. The @@ -1915,7 +1917,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PG_DIAG_INTERNAL_POSITION @@ -1929,7 +1931,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PG_DIAG_INTERNAL_QUERY @@ -1939,7 +1941,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PG_DIAG_CONTEXT @@ -1951,7 +1953,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PG_DIAG_SOURCE_FILE @@ -1961,7 +1963,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PG_DIAG_SOURCE_LINE @@ -1971,7 +1973,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PG_DIAG_SOURCE_FUNCTION @@ -1982,21 +1984,21 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + The client is responsible for formatting displayed information to meet its needs; in particular it should break long lines as needed. Newline characters appearing in the error message fields should be treated as paragraph breaks, not line breaks. - + Errors generated internally by libpq will have severity and primary message, but typically no other fields. Errors returned by a pre-3.0-protocol server will include severity and primary message, and sometimes a detail message, but no other fields. - + Note that error fields are only available from PGresult objects, not @@ -2005,7 +2007,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PQclearPQclear @@ -2019,7 +2021,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); void PQclear(PGresult *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 @@ -2029,7 +2031,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PQmakeEmptyPGresult @@ -2045,7 +2047,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); - + This is libpq's internal function to allocate and initialize an empty PGresult object. This @@ -2064,10 +2066,10 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + Retrieving Query Result Information - + These functions are used to extract information from a PGresult object that represents a successful @@ -2078,7 +2080,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); would provide, but it has zero rows. For objects with other status values, these functions will act as though the result has zero rows and zero columns. - + @@ -2099,7 +2101,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PQnfields @@ -2119,7 +2121,7 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - + PQfname @@ -2140,13 +2142,13 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); int column_number); - + NULL is returned if the column number is out of range. - + PQfnumber @@ -2163,11 +2165,11 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); const char *column_name); - + -1 is returned if the given name does not match any column. - + The given name is treated like an identifier in an SQL command, that is, it is downcased unless double-quoted. For example, given @@ -2187,7 +2189,7 @@ PQfnumber(res, "\"BAR\"") 1 - + PQftable @@ -2205,7 +2207,7 @@ PQfnumber(res, "\"BAR\"") 1 int column_number); - + InvalidOid is returned if the column number is out of range, or if the specified column is not a simple reference to a table column, @@ -2222,7 +2224,7 @@ PQfnumber(res, "\"BAR\"") 1 - + PQftablecol @@ -2241,7 +2243,7 @@ PQfnumber(res, "\"BAR\"") 1 int column_number); - + Zero is returned if the column number is out of range, or if the specified column is not a simple reference to a table column, or @@ -2267,7 +2269,7 @@ PQfnumber(res, "\"BAR\"") 1 int column_number); - + Format code zero indicates textual data representation, while format code one indicates binary representation. (Other codes are reserved @@ -2275,7 +2277,7 @@ PQfnumber(res, "\"BAR\"") 1 - + PQftype @@ -2294,7 +2296,7 @@ PQfnumber(res, "\"BAR\"") 1 int column_number); - + You can query the system table pg_type to obtain the names and properties of the various data types. The @@ -2304,7 +2306,7 @@ PQfnumber(res, "\"BAR\"") 1 - + PQfmod @@ -2322,7 +2324,7 @@ PQfnumber(res, "\"BAR\"") 1 int column_number); - + The interpretation of modifier values is type-specific; they typically indicate precision or size limits. The value -1 is @@ -2332,7 +2334,7 @@ PQfnumber(res, "\"BAR\"") 1 - + PQfsize @@ -2350,7 +2352,7 @@ PQfnumber(res, "\"BAR\"") 1 int column_number); - + PQfsize returns the space allocated for this column in a database row, in other words the size of the server's @@ -2360,7 +2362,7 @@ PQfnumber(res, "\"BAR\"") 1 - + PQbinaryTuples @@ -2370,198 +2372,199 @@ PQfnumber(res, "\"BAR\"") 1 - - Returns 1 if the PGresult contains binary data - and 0 if it contains text data. - - int PQbinaryTuples(const PGresult *res); - - - - - This function is deprecated (except for its use in connection with - COPY), because it is possible for a single - PGresult to contain text data in some columns and - binary data in others. PQfformat is preferred. - PQbinaryTuples returns 1 only if all columns of the - result are binary (format 1). - - - - - - - PQgetvalue + + Returns 1 if the PGresult contains binary data + and 0 if it contains text data. + + int PQbinaryTuples(const PGresult *res); + + + + + This function is deprecated (except for its use in connection with + COPY), because it is possible for a single + PGresult to contain text data in some columns and + binary data in others. PQfformat is preferred. + PQbinaryTuples returns 1 only if all columns of the + result are binary (format 1). + + + + + + + PQgetvalue + + PQgetvalue + + + + + + Returns a single field value of one row of a + PGresult. Row and column numbers start + at 0. The caller should not free the result directly. It will + be freed when the associated PGresult handle is + passed to PQclear. + + char *PQgetvalue(const PGresult *res, + int row_number, + int column_number); + + + + + For data in text format, the value returned by + PQgetvalue is a null-terminated character + string representation of the field value. For data in binary + format, the value is in the binary representation determined by + the data type's typsend and typreceive + functions. (The value is actually followed by a zero byte in + this case too, but that is not ordinarily useful, since the + value is likely to contain embedded nulls.) + + + + An empty string is returned if the field value is null. See + PQgetisnull to distinguish null values from + empty-string values. + + + + The pointer returned by PQgetvalue points + to storage that is part of the PGresult + structure. One should not modify the data it points to, and one + must explicitly copy the data into other storage if it is to be + used past the lifetime of the PGresult + structure itself. + + + + + + + PQgetisnull + + PQgetisnull + + + null value + in libpq + + + + + + Tests a field for a null value. Row and column numbers start + at 0. + + int PQgetisnull(const PGresult *res, + int row_number, + int column_number); + + + + + This function returns 1 if the field is null and 0 if it + contains a non-null value. (Note that + PQgetvalue will return an empty string, + not a null pointer, for a null field.) + + + + + + + PQgetlength - PQgetvalue - - - - - - Returns a single field value of one row of a - PGresult. Row and column numbers start - at 0. The caller should not free the result directly. It will - be freed when the associated PGresult handle is - passed to PQclear. - - char *PQgetvalue(const PGresult *res, - int row_number, - int column_number); - - + PQgetlength + + + + + Returns the actual length of a field value in bytes. Row and + column numbers start at 0. + + int PQgetlength(const PGresult *res, + int row_number, + int column_number); + + - - For data in text format, the value returned by - PQgetvalue is a null-terminated character - string representation of the field value. For data in binary - format, the value is in the binary representation determined by - the data type's typsend and typreceive - functions. (The value is actually followed by a zero byte in - this case too, but that is not ordinarily useful, since the - value is likely to contain embedded nulls.) - + + This is the actual data length for the particular data value, + that is, the size of the object pointed to by + PQgetvalue. For text data format this is + the same as strlen(). For binary format this is + essential information. Note that one should not + rely on PQfsize to obtain the actual data + length. + + + - - An empty string is returned if the field value is null. See - PQgetisnull to distinguish null values from - empty-string values. - - - - The pointer returned by PQgetvalue points - to storage that is part of the PGresult - structure. One should not modify the data it points to, and one - must explicitly copy the data into other storage if it is to be - used past the lifetime of the PGresult - structure itself. - - - - - - - PQgetisnull - - PQgetisnull - - - null value - in libpq - - - - - - Tests a field for a null value. Row and column numbers start - at 0. - - int PQgetisnull(const PGresult *res, - int row_number, - int column_number); - - + + + PQnparams + + PQnparams + + - - This function returns 1 if the field is null and 0 if it - contains a non-null value. (Note that - PQgetvalue will return an empty string, - not a null pointer, for a null field.) - - - + + + Returns the number of parameters of a prepared statement. + + int PQnparams(const PGresult *res); + + - - - PQgetlength - - PQgetlength - - - - - Returns the actual length of a field value in bytes. Row and - column numbers start at 0. - - int PQgetlength(const PGresult *res, - int row_number, - int column_number); - - + + This function is only useful when inspecting the result of + PQdescribePrepared. For other types of queries it + will return zero. + + + - - This is the actual data length for the particular data value, - that is, the size of the object pointed to by - PQgetvalue. For text data format this is - the same as strlen(). For binary format this is - essential information. Note that one should not - rely on PQfsize to obtain the actual data - length. - - - - - - - PQnparams - - PQnparams - - - - - - Returns the number of parameters of a prepared statement. - - int PQnparams(const PGresult *res); - - - - - This function is only useful when inspecting the result of - PQdescribePrepared. For other types of queries it - will return zero. - - - - - - - PQparamtype - - PQparamtype - - - - - Returns the data type of the indicated statement parameter. - Parameter numbers start at 0. - - Oid PQparamtype(const PGresult *res, int param_number); - - - - - This function is only useful when inspecting the result of - PQdescribePrepared. For other types of queries it - will return zero. - - - - - - - PQprint - - PQprint - - - - - - Prints out all the rows and, optionally, the column names to - the specified output stream. - + + + PQparamtype + + PQparamtype + + + + + + Returns the data type of the indicated statement parameter. + Parameter numbers start at 0. + + Oid PQparamtype(const PGresult *res, int param_number); + + + + + This function is only useful when inspecting the result of + PQdescribePrepared. For other types of queries it + will return zero. + + + + + + + PQprint + + PQprint + + + + + + Prints out all the rows and, optionally, the column names to + the specified output stream. + void PQprint(FILE *fout, /* output stream */ const PGresult *res, const PQprintOpt *po); @@ -2579,7 +2582,7 @@ typedef struct { } PQprintOpt; - + This function was formerly used by psql to print query results, but this is no longer the case. Note @@ -2589,16 +2592,16 @@ typedef struct { - + Retrieving Result Information for Other Commands - + These functions are used to extract information from PGresult objects that are not SELECT results. - + @@ -2626,7 +2629,7 @@ typedef struct { - + PQcmdTuples @@ -2642,7 +2645,7 @@ typedef struct { char *PQcmdTuples(PGresult *res); - + This function returns a string containing the number of rows affected by the SQL statement that generated the @@ -2660,7 +2663,7 @@ typedef struct { - + PQoidValue @@ -2685,7 +2688,7 @@ typedef struct { - + PQoidStatus @@ -2708,7 +2711,7 @@ typedef struct { char *PQoidStatus(const PGresult *res); - + This function is deprecated in favor of PQoidValue. It is not thread-safe. @@ -2716,12 +2719,12 @@ typedef struct { - + - + Escaping Strings for Inclusion in SQL Commands - + PQescapeStringConn @@ -2732,7 +2735,7 @@ typedef struct { escaping strings in libpq - + PQescapeStringConn escapes a string for use within an SQL command. This is useful when inserting data values as literal constants @@ -2740,7 +2743,7 @@ typedef struct { be escaped to prevent them from being interpreted specially by the SQL parser. PQescapeStringConn performs this operation. - + It is especially important to do proper escaping when handling strings that @@ -2749,19 +2752,19 @@ typedef struct { SQL commands are fed to your database. - + Note that it is not necessary nor correct to do escaping when a data value is passed as a separate parameter in PQexecParams or its sibling routines. - + size_t PQescapeStringConn (PGconn *conn, char *to, const char *from, size_t length, int *error); - + PQescapeStringConn writes an escaped version of the from string to the to buffer, escaping @@ -2797,13 +2800,13 @@ typedef struct { PQescapeStringConn returns the number of bytes written to to, not including the terminating zero byte. - + size_t PQescapeString (char *to, const char *from, size_t length); - + PQescapeString is an older, deprecated version of PQescapeStringConn; the difference is that it does @@ -2823,16 +2826,16 @@ typedef struct { PQescapeStringConn. - - + + Escaping Binary Strings for Inclusion in SQL Commands - + bytea in libpq - + @@ -2854,7 +2857,7 @@ typedef struct { size_t *to_length); - + Certain byte values must be escaped (but all byte values can be escaped) when used as part @@ -2867,7 +2870,7 @@ typedef struct { information. PQescapeByteaConn performs this operation, escaping only the minimally required bytes. - + The from parameter points to the first byte of the string that is to be escaped, and the @@ -2878,7 +2881,7 @@ typedef struct { escaped string length. This result string length includes the terminating zero byte of the result. - + PQescapeByteaConn returns an escaped version of the from parameter binary string in memory @@ -2891,7 +2894,7 @@ typedef struct { surround PostgreSQL string literals are not part of the result string. - + On error, a NULL pointer is returned, and a suitable error message is stored in the conn object. Currently, the only @@ -2899,7 +2902,7 @@ typedef struct { - + PQescapeBytea @@ -2918,7 +2921,7 @@ typedef struct { size_t *to_length); - + The only difference from PQescapeByteaConn is that PQescapeBytea does not take a PGconn @@ -2928,7 +2931,7 @@ typedef struct { it might give the wrong results. Also, it has no way to return an error message on failure. - + PQescapeBytea can be used safely in single-threaded client programs that work with only one PostgreSQL @@ -2939,7 +2942,7 @@ typedef struct { - + PQunescapeBytea @@ -2954,12 +2957,12 @@ typedef struct { — the reverse of PQescapeBytea. This is needed when retrieving bytea data in text format, but not when retrieving it in binary format. - + unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - + The from parameter points to a string such as might be returned by PQgetvalue when applied @@ -2970,7 +2973,7 @@ typedef struct { the buffer in to_length. The result must be freed using PQfreemem when it is no longer needed. - + This conversion is not exactly the inverse of PQescapeBytea, because the string is not expected @@ -2980,7 +2983,7 @@ typedef struct { - + PQfreemem @@ -2996,7 +2999,7 @@ typedef struct { void PQfreemem(void *ptr); - + Frees memory allocated by libpq, particularly PQescapeByteaConn, @@ -3014,23 +3017,23 @@ typedef struct { - + - + Asynchronous Command Processing - + nonblocking connection - + The PQexec function is adequate for submitting commands in normal, synchronous applications. It has a couple of deficiencies, however, that can be of importance to some users: - + @@ -3049,7 +3052,7 @@ typedef struct { from a signal handler, but not otherwise.) - + PQexec can return only one @@ -3061,7 +3064,7 @@ typedef struct { - + Applications that do not like these limitations can instead use the underlying functions that PQexec is built from: @@ -3080,7 +3083,7 @@ typedef struct { PQdescribePrepared, and PQdescribePortal respectively. - + @@ -3099,7 +3102,7 @@ typedef struct { int PQsendQuery(PGconn *conn, const char *command); - + After successfully calling PQsendQuery, call PQgetResult one or more times to obtain the results. PQsendQuery cannot be called again @@ -3108,7 +3111,7 @@ typedef struct { - + PQsendQueryParams @@ -3131,7 +3134,7 @@ typedef struct { const int *paramFormats, int resultFormat); - + This is equivalent to PQsendQuery except that query parameters can be specified separately from the query string. The function's parameters are handled identically to @@ -3141,7 +3144,7 @@ typedef struct { - + PQsendPrepare @@ -3161,7 +3164,7 @@ typedef struct { int nParams, const Oid *paramTypes); - + This is an asynchronous version of PQprepare: it returns 1 if it was able to dispatch the request, and 0 if not. After a successful call, call PQgetResult to @@ -3173,7 +3176,7 @@ typedef struct { - + PQsendQueryPrepared @@ -3195,7 +3198,7 @@ typedef struct { const int *paramFormats, int resultFormat); - + This is similar to PQsendQueryParams, but the command to be executed is specified by naming a previously-prepared statement, instead of giving a query string. @@ -3206,7 +3209,7 @@ typedef struct { - + PQsendDescribePrepared @@ -3222,7 +3225,7 @@ typedef struct { int PQsendDescribePrepared(PGconn *conn, const char *stmtName); - + This is an asynchronous version of PQdescribePrepared: it returns 1 if it was able to dispatch the request, and 0 if not. After a successful call, call PQgetResult to @@ -3233,7 +3236,7 @@ typedef struct { - + PQsendDescribePortal @@ -3249,7 +3252,7 @@ typedef struct { int PQsendDescribePortal(PGconn *conn, const char *portalName); - + This is an asynchronous version of PQdescribePortal: it returns 1 if it was able to dispatch the request, and 0 if not. After a successful call, call PQgetResult to @@ -3260,7 +3263,7 @@ typedef struct { - + PQgetResult @@ -3282,7 +3285,7 @@ typedef struct { PGresult *PQgetResult(PGconn *conn); - + PQgetResult must be called repeatedly until it returns a null pointer, indicating that the command is done. @@ -3301,7 +3304,7 @@ typedef struct { - + Using PQsendQuery and PQgetResult solves one of @@ -3314,7 +3317,7 @@ typedef struct { will still cause the client to block until the server completes the next SQL command. This can be avoided by proper use of two more functions: - + @@ -3331,7 +3334,7 @@ typedef struct { int PQconsumeInput(PGconn *conn); - + PQconsumeInput normally returns 1 indicating no error, but returns 0 if there was some kind of @@ -3355,7 +3358,7 @@ typedef struct { - + PQisBusy @@ -3374,7 +3377,7 @@ typedef struct { int PQisBusy(PGconn *conn); - + PQisBusy will not itself attempt to read data from the server; therefore PQconsumeInput @@ -3384,7 +3387,7 @@ typedef struct { - + A typical application using these functions will have a main loop that uses select() or poll() to wait for @@ -3400,7 +3403,7 @@ typedef struct { to detect NOTIFY messages (see ). - + A client that uses PQsendQuery/PQgetResult @@ -3412,7 +3415,7 @@ typedef struct { simply cause the command to terminate sooner than it would have otherwise. - + By using the functions described above, it is possible to avoid blocking while waiting for input from the database server. However, @@ -3423,7 +3426,7 @@ typedef struct { however.) To prevent this possibility and achieve completely nonblocking database operation, the following additional functions can be used. - + @@ -3440,7 +3443,7 @@ typedef struct { int PQsetnonblocking(PGconn *conn, int arg); - + Sets the state of the connection to nonblocking if arg is 1, or blocking if @@ -3461,7 +3464,7 @@ typedef struct { - + PQisnonblocking @@ -3477,14 +3480,14 @@ typedef struct { int PQisnonblocking(const PGconn *conn); - + Returns 1 if the connection is set to nonblocking mode and 0 if blocking. - + PQflush @@ -3508,7 +3511,7 @@ typedef struct { - + After sending any command or data on a nonblocking connection, call PQflush. If it returns 1, wait for the socket @@ -3516,22 +3519,22 @@ typedef struct { PQflush returns 0, wait for the socket to be read-ready and then read the response as described above. - + - + Cancelling Queries in Progress - + canceling SQL command - + A client application can request cancellation of a command that is still being processed by the server, using the functions described in this section. - + @@ -3549,7 +3552,7 @@ typedef struct { PGcancel *PQgetCancel(PGconn *conn); - + PQgetCancel creates a PGcancelPGcancel object @@ -3578,14 +3581,14 @@ typedef struct { void PQfreeCancel(PGcancel *cancel); - + PQfreeCancel frees a data object previously created by PQgetCancel. - + PQcancel @@ -3601,7 +3604,7 @@ typedef struct { int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); - + The return value is 1 if the cancel request was successfully dispatched and 0 if not. If not, errbuf is filled @@ -3609,7 +3612,7 @@ typedef struct { must be a char array of size errbufsize (the recommended size is 256 bytes). - + Successful dispatch is no guarantee that the request will have any effect, however. If the cancellation is effective, the current @@ -3618,7 +3621,7 @@ typedef struct { processing the command), then there will be no visible result at all. - + PQcancel can safely be invoked from a signal handler, if the errbuf is a local variable in the @@ -3630,7 +3633,7 @@ typedef struct { - + @@ -3648,7 +3651,7 @@ typedef struct { int PQrequestCancel(PGconn *conn); - + PQrequestCancel is a deprecated variant of PQcancel. It operates directly on the @@ -3664,21 +3667,21 @@ typedef struct { - + - + The Fast-Path Interface - + fast path - + PostgreSQL provides a fast-path interface to send simple function calls to the server. - + This interface is somewhat obsolete, as one can achieve similar @@ -3688,7 +3691,7 @@ typedef struct { fast-path function call. - + The function PQfnPQfn requests execution of a server function via the fast-path interface: @@ -3700,7 +3703,7 @@ typedef struct { int result_is_int, const PQArgBlock *args, int nargs); - + typedef struct { int len; int isint; @@ -3711,7 +3714,7 @@ typedef struct { } PQArgBlock; - + The fnid argument is the OID of the function to be executed. args and nargs define the @@ -3735,7 +3738,7 @@ typedef struct { When result_is_int is 0, the binary-format byte string sent by the server is returned unmodified. - + PQfn always returns a valid PGresult pointer. The result status should be @@ -3743,22 +3746,22 @@ typedef struct { freeing the PGresult with PQclear when it is no longer needed. - + Note that it is not possible to handle null arguments, null results, nor set-valued results when using this interface. - + - + Asynchronous Notification - + NOTIFY in libpq - + PostgreSQL offers asynchronous notification via the LISTEN and NOTIFY @@ -3774,7 +3777,7 @@ typedef struct { associated table, but it is not necessary for there to be any associated table. - + libpq applications submit LISTEN and UNLISTEN commands as @@ -3782,7 +3785,7 @@ typedef struct { messages can subsequently be detected by calling PQnotifies.PQnotifies - + The function PQnotifies returns the next notification from a list of unhandled @@ -3792,7 +3795,7 @@ typedef struct { removed from the list of notifications. PGnotify *PQnotifies(PGconn *conn); - + typedef struct pgNotify { char *relname; /* notification condition name */ int be_pid; /* process ID of notifying server process */ @@ -3808,12 +3811,12 @@ typedef struct { extra field is unused and will always point to an empty string.) - + gives a sample program that illustrates the use of asynchronous notification. - + PQnotifies does not actually read data from the server; it just returns messages previously absorbed by another @@ -3824,7 +3827,7 @@ typedef struct { 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 commands to execute is to call @@ -3841,17 +3844,17 @@ typedef struct { PQgetResult or PQexec, to see if any notifications came in during the processing of the command. - + - + Functions Associated with the <command>COPY</command> Command - + COPY with libpq - + The COPY command in PostgreSQL has options to read from or write @@ -3859,7 +3862,7 @@ typedef struct { The functions described in this section allow applications to take advantage of this capability by supplying or consuming copied data. - + The overall process is that the application first issues the SQL COPY command via PQexec or one @@ -3878,7 +3881,7 @@ typedef struct { commands using the same connection while the COPY operation is in progress.) - + If a COPY command is issued via PQexec in a string that could contain additional @@ -3888,20 +3891,20 @@ typedef struct { NULL is it certain that the PQexec command string is done and it is safe to issue more commands. - + The functions of this section should be executed only after obtaining a result status of PGRES_COPY_OUT or PGRES_COPY_IN from PQexec or PQgetResult. - + A PGresult object bearing one of these status values carries some additional data about the COPY operation that is starting. This additional data is available using functions that are also used in connection with query results: - + @@ -3918,7 +3921,7 @@ typedef struct { - + PQbinaryTuples @@ -3937,7 +3940,7 @@ typedef struct { - + PQfformat @@ -3961,23 +3964,23 @@ typedef struct { - + These additional data values are only available when using protocol 3.0. When using protocol 2.0, all these functions will return 0. - + Functions for Sending <command>COPY</command> Data - + These functions are used to send data during COPY FROM STDIN. They will fail if called when the connection is not in COPY_IN state. - + @@ -3996,7 +3999,7 @@ typedef struct { int nbytes); - + Transmits the COPY data in the specified buffer, of length nbytes, to the server. @@ -4007,7 +4010,7 @@ typedef struct { the return value is -1. If the value is zero, wait for write-ready and try again.) - + The application can divide the COPY data stream into buffer loads of any convenient size. Buffer-load boundaries @@ -4018,7 +4021,7 @@ typedef struct { - + PQputCopyEnd @@ -4035,7 +4038,7 @@ typedef struct { const char *errormsg); - + Ends the COPY_IN operation successfully if errormsg is NULL. If @@ -4048,7 +4051,7 @@ typedef struct { to force failure does not work when using pre-3.0-protocol connections.) - + The result is 1 if the termination data was sent, zero if it was not sent because the attempt would block (this case is only possible @@ -4057,7 +4060,7 @@ typedef struct { details if the return value is -1. If the value is zero, wait for write-ready and try again.) - + After successfully calling PQputCopyEnd, call PQgetResult to obtain the final result status of the @@ -4067,18 +4070,18 @@ typedef struct { - + - + Functions for Receiving <command>COPY</command> Data - + These functions are used to receive data during COPY TO STDOUT. They will fail if called when the connection is not in COPY_OUT state. - + @@ -4097,7 +4100,7 @@ typedef struct { int async); - + Attempts to obtain another row of data from the server during a COPY. Data is always returned one data row at @@ -4110,7 +4113,7 @@ typedef struct { buffer must be freed using PQfreemem when no longer needed. - + When a row is successfully returned, the return value is the number of data bytes in the row (this will always be greater than zero). @@ -4122,7 +4125,7 @@ typedef struct { COPY is done. A result of -2 indicates that an error occurred (consult PQerrorMessage for the reason). - + When async is true (not zero), PQgetCopyData will not block waiting for input; it @@ -4133,7 +4136,7 @@ typedef struct { false (zero), PQgetCopyData will block until data is available or the operation completes. - + After PQgetCopyData returns -1, call PQgetResult to obtain the final result status of the @@ -4143,19 +4146,19 @@ typedef struct { - + - + Obsolete Functions for <command>COPY</command> - + These functions represent older methods of handling COPY. Although they still work, they are deprecated due to poor error handling, inconvenient methods of detecting end-of-data, and lack of support for binary or nonblocking transfers. - + @@ -4175,7 +4178,7 @@ typedef struct { int length); - + This function copies up to length-1 characters into the buffer and converts the terminating newline into a zero byte. @@ -4195,7 +4198,7 @@ typedef struct { - + PQgetlineAsync @@ -4214,7 +4217,7 @@ typedef struct { int bufsize); - + This function is similar to PQgetline, but it can be used by applications @@ -4254,7 +4257,7 @@ typedef struct { - + PQputline @@ -4272,7 +4275,7 @@ typedef struct { const char *string); - + The COPY data stream sent by a series of calls to PQputline has the same format as that @@ -4281,7 +4284,7 @@ typedef struct { PQputline call; it is okay to send a partial line or multiple lines per call. - + Before PostgreSQL protocol 3.0, it was necessary @@ -4295,7 +4298,7 @@ typedef struct { - + PQputnbytes @@ -4314,7 +4317,7 @@ typedef struct { 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 @@ -4322,7 +4325,7 @@ typedef struct { - + PQendcopy @@ -4348,7 +4351,7 @@ typedef struct { nonzero otherwise. (Use PQerrorMessage to retrieve details if the return value is nonzero.) - + When using PQgetResult, the application should respond to a PGRES_COPY_OUT result by executing @@ -4363,7 +4366,7 @@ typedef struct { ensure that a COPY command embedded in a series of SQL commands will be executed correctly. - + Older applications are likely to submit a COPY via PQexec and assume that the transaction @@ -4374,19 +4377,19 @@ typedef struct { - + - + - + Control Functions - + These functions control miscellaneous details of libpq's behavior. - + @@ -4396,91 +4399,91 @@ typedef struct { - - - Determines the verbosity of messages returned by - PQerrorMessage and PQresultErrorMessage. - + + + Determines the verbosity of messages returned by + PQerrorMessage and PQresultErrorMessage. + typedef enum { PQERRORS_TERSE, PQERRORS_DEFAULT, PQERRORS_VERBOSE } PGVerbosity; - + PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - + - PQsetErrorVerbosity sets the verbosity mode, returning - the connection's previous setting. In TERSE mode, - returned messages include severity, primary text, and position only; - this will normally fit on a single line. The default mode produces - messages that include the above plus any detail, hint, or context - fields (these might span multiple lines). The VERBOSE - mode includes all available fields. Changing the verbosity does not - affect the messages available from already-existing - PGresult objects, only subsequently-created ones. - - - - - - - PQtrace - - PQtrace - - - - - - Enables tracing of the client/server communication to a debugging file stream. - - void PQtrace(PGconn *conn, FILE *stream); - - - - - - On Windows, if the libpq library and an application are - compiled with different flags, this function call will crash the - application because the internal representation of the FILE - pointers differ. Specifically, multithreaded/single-threaded, - release/debug, and static/dynamic flags should be the same for the - library and all applications using that library. + PQsetErrorVerbosity sets the verbosity mode, returning + the connection's previous setting. In TERSE mode, + returned messages include severity, primary text, and position only; + this will normally fit on a single line. The default mode produces + messages that include the above plus any detail, hint, or context + fields (these might span multiple lines). The VERBOSE + mode includes all available fields. Changing the verbosity does not + affect the messages available from already-existing + PGresult objects, only subsequently-created ones. - - - - - - - - PQuntrace - - PQuntrace - - - - - - Disables tracing started by PQtrace. - - void PQuntrace(PGconn *conn); - - - - - - + + + + + + PQtrace + + PQtrace + + + + + + Enables tracing of the client/server communication to a debugging file stream. + + void PQtrace(PGconn *conn, FILE *stream); + + + + + + On Windows, if the libpq library and an application are + compiled with different flags, this function call will crash the + application because the internal representation of the FILE + pointers differ. Specifically, multithreaded/single-threaded, + release/debug, and static/dynamic flags should be the same for the + library and all applications using that library. + + + + + + + + + PQuntrace + + PQuntrace + + + + + + Disables tracing started by PQtrace. + + void PQuntrace(PGconn *conn); + + + + + + - + Miscellaneous Functions - + As always, there are some functions that just don't fit anywhere. - + @@ -4512,17 +4515,17 @@ typedef struct { - + - + Notice Processing - + notice processing in libpq - + Notice and warning messages generated by the server are not returned by the query execution functions, since they do not imply failure of @@ -4532,7 +4535,7 @@ typedef struct { stderr, but the application can override this behavior by supplying its own handling function. - + For historical reasons, there are two levels of notice handling, called the notice receiver and notice processor. The default behavior is for @@ -4541,7 +4544,7 @@ typedef struct { its own notice receiver will typically ignore the notice processor layer and just do all the work in the notice receiver. - + The function PQsetNoticeReceiver notice @@ -4551,29 +4554,29 @@ typedef struct { notice processorPQsetNoticeProcessor sets or examines the current notice processor. - + typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res); - + PQnoticeReceiver PQsetNoticeReceiver(PGconn *conn, PQnoticeReceiver proc, void *arg); - + typedef void (*PQnoticeProcessor) (void *arg, const char *message); - + PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn, PQnoticeProcessor proc, void *arg); - + Each of these functions returns the previous notice receiver or processor function pointer, and sets the new value. If you supply a null function pointer, no action is taken, but the current pointer is returned. - + When a notice or warning message is received from the server, or generated internally by libpq, the notice @@ -4586,13 +4589,13 @@ typedef struct { passed. (This pointer can be used to access application-specific state if needed.) - + The default notice receiver simply extracts the message (using PQresultErrorMessage) and passes it to the notice processor. - + The notice processor is responsible for handling a notice or warning message given in text form. It is passed the string text of the message @@ -4600,7 +4603,7 @@ typedef struct { one passed to PQsetNoticeProcessor. (This pointer can be used to access application-specific state if needed.) - + The default notice processor is simply: @@ -4611,7 +4614,7 @@ defaultNoticeProcessor(void *arg, const char *message) } - + Once you have set a notice receiver or processor, you should expect that that function could be called as long as either the @@ -4621,16 +4624,16 @@ defaultNoticeProcessor(void *arg, const char *message) into the PGresult for possible use by functions like PQgetvalue. - + - + Environment Variables - + environment variable - + The following environment variables can be used to select default connection parameter values, which will be used by @@ -4638,7 +4641,7 @@ defaultNoticeProcessor(void *arg, const char *message) PQsetdb if no value is directly specified by the calling code. These are useful to avoid hard-coding database connection information into simple client applications, for example. - + @@ -4685,7 +4688,7 @@ defaultNoticeProcessor(void *arg, const char *message) - + PGDATABASE PGDATABASE sets the @@ -4704,7 +4707,7 @@ defaultNoticeProcessor(void *arg, const char *message) - + PGPASSWORD @@ -4727,7 +4730,7 @@ defaultNoticeProcessor(void *arg, const char *message) (see ). - + @@ -4739,7 +4742,7 @@ defaultNoticeProcessor(void *arg, const char *message) of setting all the parameters. - + @@ -4755,7 +4758,7 @@ defaultNoticeProcessor(void *arg, const char *message) selected by the server. - + @@ -4765,7 +4768,7 @@ defaultNoticeProcessor(void *arg, const char *message) PostgreSQL server. - + @@ -4787,7 +4790,7 @@ defaultNoticeProcessor(void *arg, const char *message) connection. - + @@ -4802,7 +4805,7 @@ defaultNoticeProcessor(void *arg, const char *message) if PostgreSQL is compiled with SSL support. - + @@ -4816,7 +4819,7 @@ defaultNoticeProcessor(void *arg, const char *message) file. - + @@ -4826,7 +4829,7 @@ defaultNoticeProcessor(void *arg, const char *message) when authenticating with Kerberos 5 or GSSAPI. - + @@ -4836,7 +4839,7 @@ defaultNoticeProcessor(void *arg, const char *message) authentication. - + @@ -4852,7 +4855,7 @@ defaultNoticeProcessor(void *arg, const char *message) - + The following environment variables can be used to specify default behavior for each PostgreSQL session. (See @@ -4860,7 +4863,7 @@ defaultNoticeProcessor(void *arg, const char *message) and commands for ways to set default behavior on a per-user or per-database basis.) - + @@ -4872,7 +4875,7 @@ defaultNoticeProcessor(void *arg, const char *message) ....) - + @@ -4882,7 +4885,7 @@ defaultNoticeProcessor(void *arg, const char *message) SET timezone TO ....) - + @@ -4893,7 +4896,7 @@ defaultNoticeProcessor(void *arg, const char *message) ....) - + @@ -4904,16 +4907,16 @@ defaultNoticeProcessor(void *arg, const char *message) - + Refer to the SQL command for information on correct values for these environment variables. - + The following environment variables determine internal behavior of libpq; they override compiled-in defaults. - + @@ -4924,7 +4927,7 @@ defaultNoticeProcessor(void *arg, const char *message) pg_service.conf file. - + @@ -4936,20 +4939,20 @@ defaultNoticeProcessor(void *arg, const char *message) - + - - + + The Password File - + password file .pgpass - + The file .pgpass in a user's home directory or the file referenced by PGPASSFILE can contain passwords to @@ -4959,7 +4962,7 @@ defaultNoticeProcessor(void *arg, const char *message) %APPDATA% refers to the Application Data subdirectory in the user's profile). - + This file should contain lines of the following format: @@ -4976,7 +4979,7 @@ defaultNoticeProcessor(void *arg, const char *message) or the default socket directory) connections coming from the local machine. - + On Unix systems, the permissions on .pgpass must disallow any access to world or group; achieve this by the command @@ -4986,18 +4989,18 @@ defaultNoticeProcessor(void *arg, const char *message) no special permissions check is made. - - + + The Connection Service File - + connection service file pg_service.conf - + The connection service file allows libpq connection parameters to be associated with a single service name. That service name can then be @@ -5016,15 +5019,15 @@ defaultNoticeProcessor(void *arg, const char *message) PGSYSCONFDIR environment variable. - - + + LDAP Lookup of Connection Parameters - + LDAP connection parameter lookup - + If libpq has been compiled with LDAP support (option for configure) @@ -5033,7 +5036,7 @@ defaultNoticeProcessor(void *arg, const char *message) The advantage is that if the connection parameters for a database change, the connection information doesn't have to be updated on all client machines. - + LDAP connection parameter lookup uses the connection service file pg_service.conf (see localhost and port defaults to 389. - + Processing of pg_service.conf is terminated after a successful LDAP lookup, but is continued if the LDAP server cannot @@ -5061,7 +5064,7 @@ defaultNoticeProcessor(void *arg, const char *message) rather get an error message in this case, add a syntactically incorrect line after the LDAP URL. - + A sample LDAP entry that has been created with the LDIF file @@ -5083,22 +5086,22 @@ defaultNoticeProcessor(void *arg, const char *message) - - + + SSL Support - + SSL - + PostgreSQL has native support for using SSL connections to encrypt client/server communications for increased security. See for details about the server-side SSL functionality. - + libpq reads the system-wide OpenSSL configuration file. By default, this @@ -5108,7 +5111,7 @@ defaultNoticeProcessor(void *arg, const char *message) OPENSSL_CONF to the name of the desired configuration file. - + If the server demands a client certificate, libpq will send the certificate stored in @@ -5158,16 +5161,16 @@ defaultNoticeProcessor(void *arg, const char *message) - - + + Behavior in Threaded Programs - + threads with libpq - + libpq is reentrant and thread-safe if the configure command-line option @@ -5176,12 +5179,12 @@ defaultNoticeProcessor(void *arg, const char *message) addition, you might need to use additional compiler command-line options when you compile your application code. Refer to your system's documentation for information about how to build - thread-enabled applications, or look in + thread-enabled applications, or look in src/Makefile.global for PTHREAD_CFLAGS and PTHREAD_LIBS. This function allows the querying of libpq's thread-safe status: - + @@ -5199,7 +5202,7 @@ defaultNoticeProcessor(void *arg, const char *message) int PQisthreadsafe(); - + Returns 1 if the libpq is thread-safe and 0 if it is not. @@ -5207,7 +5210,7 @@ defaultNoticeProcessor(void *arg, const char *message) - + One thread restriction is that no two threads attempt to manipulate the same PGconn object at the same time. In particular, @@ -5215,12 +5218,12 @@ defaultNoticeProcessor(void *arg, const char *message) the same connection object. (If you need to run concurrent commands, use multiple connections.) - + PGresult objects are read-only after creation, and so can be passed around freely between threads. - + The deprecated functions PQrequestCancel and PQoidStatus are not thread-safe and should not be @@ -5229,7 +5232,7 @@ defaultNoticeProcessor(void *arg, const char *message) PQoidStatus can be replaced by PQoidValue. - + If you are using Kerberos inside your application (in addition to inside libpq), you will need to do locking around @@ -5238,7 +5241,7 @@ defaultNoticeProcessor(void *arg, const char *message) libpq source code for a way to do cooperative locking between libpq and your application. - + If you experience problems with threaded applications, run the program in src/tools/thread to see if your platform has @@ -5247,21 +5250,21 @@ defaultNoticeProcessor(void *arg, const char *message) library might not match the library used to build the binaries. - - + + Building <application>libpq</application> Programs - + compiling libpq applications - + To build (i.e., compile and link) a program using libpq you need to do all of the following things: - + @@ -5281,7 +5284,7 @@ foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) - + Point your compiler to the directory where the PostgreSQL header @@ -5300,7 +5303,7 @@ cc -c -I/usr/local/pgsql/include testprog.c CPPFLAGS += -I/usr/local/pgsql/include - + If there is any chance that your program might be compiled by other users then you should not hardcode the directory location @@ -5313,7 +5316,7 @@ CPPFLAGS += -I/usr/local/pgsql/include /usr/local/include - + Failure to specify the correct option to the compiler will result in an error message such as @@ -5322,7 +5325,7 @@ testlibpq.c:8:22: libpq-fe.h: No such file or directory - + When linking the final program, specify the option @@ -5338,7 +5341,7 @@ testlibpq.c:8:22: libpq-fe.h: No such file or directory cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq - + You can find out the library directory using pg_config as well: @@ -5347,7 +5350,7 @@ cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq /usr/local/pgsql/lib - + Error messages that point to problems in this area could look like the following. @@ -5367,13 +5370,13 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' - + - - + + Example Programs - + These examples and others can be found in the directory src/test/examples in the source code