diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index 6641eee440c..b6a4fa2600e 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -5915,7 +5915,7 @@ ECPG = ecpg ECPGtransactionStatus(const char *connection_name) returns the current transaction status of the given connection identified by connection_name. - See and libpq's PQtransactionStatus() for details about the returned status codes. + See and libpq's for details about the returned status codes. @@ -8418,7 +8418,7 @@ if (*(int2 *)sqldata->sqlvar[i].sqlind != 0) sqlformat - Reserved in Informix, value of PQfformat() for the field. + Reserved in Informix, value of for the field. @@ -8447,7 +8447,7 @@ if (*(int2 *)sqldata->sqlvar[i].sqlind != 0) sqlxid - Extended type of the field, result of PQftype(). + Extended type of the field, result of . diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 494e0fc824c..ef2e97afd12 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -56,12 +56,12 @@ one time. (One reason to do that is to access more than one database.) Each connection is represented by a PGconnPGconn object, which - is obtained from the function PQconnectdb, - PQconnectdbParams, or - PQsetdbLogin. Note that these functions will always + is obtained from the function , + , or + . 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 + The function should be called to check the return value for a successful connection before queries are sent via the connection object. @@ -125,9 +125,9 @@ PGconn *PQconnectdbParams(const char * const *keywords, from two NULL-terminated arrays. The first, keywords, is defined as an array of strings, each one being a key word. The second, values, gives the value - for each key word. Unlike PQsetdbLogin below, the parameter + for each key word. Unlike below, the parameter set can be extended without changing the function signature, so use of - this function (or its nonblocking analogs PQconnectStartParams + this function (or its nonblocking analogs and PQconnectPoll) is preferred for new application programming. @@ -216,7 +216,7 @@ PGconn *PQsetdbLogin(const char *pghost, - This is the predecessor of PQconnectdb with a fixed + This is the predecessor of with a fixed set of parameters. It has the same functionality except that the missing parameters will always take on default values. Write NULL or an empty string for any one of the fixed parameters that is to be defaulted. @@ -226,8 +226,8 @@ PGconn *PQsetdbLogin(const char *pghost, If the dbName contains an = sign or has a valid connection URI prefix, it is taken as a conninfo string in exactly the same way as - if it had been passed to PQconnectdb, and the remaining - parameters are then applied as specified for PQconnectdbParams. + if it had been passed to , and the remaining + parameters are then applied as specified for . @@ -247,7 +247,7 @@ PGconn *PQsetdb(char *pghost, - This is a macro that calls PQsetdbLogin with null pointers + This is a macro that calls with null pointers for the login and pwd parameters. It is provided for backward compatibility with very old programs. @@ -279,25 +279,25 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); 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 - PQconnectdbParams or PQconnectdb, and so the + or , and so the application can manage this operation in parallel with other activities. - With PQconnectStartParams, the database connection is made + With , the database connection is made using the parameters taken from the keywords and values arrays, and controlled by expand_dbname, - as described above for PQconnectdbParams. + as described above for . With PQconnectStart, the database connection is made using the parameters taken from the string conninfo as - described above for PQconnectdb. + described above for . - Neither PQconnectStartParams nor PQconnectStart + Neither nor PQconnectStart nor PQconnectPoll will block, so long as a number of restrictions are met: @@ -311,7 +311,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); - If you call PQtrace, ensure that the stream object + If you call , ensure that the stream object into which you trace will not block. @@ -328,7 +328,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); To begin a nonblocking connection request, call PQconnectStart - or PQconnectStartParams. If the result is null, + or . If the result is null, then libpq has been unable to allocate a new PGconn structure. Otherwise, a valid PGconn pointer is returned (though not @@ -340,7 +340,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); If PQconnectStart - or PQconnectStartParams succeeds, the next stage + or 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 @@ -366,7 +366,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); At any time during connection, the status of the connection can be - checked by calling PQstatus. If this call returns CONNECTION_BAD, then the + checked by calling . If this call returns CONNECTION_BAD, then the connection procedure has failed; if the call returns 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 @@ -477,13 +477,13 @@ switch(PQstatus(conn)) responsibility to decide whether an excessive amount of time has elapsed. Otherwise, PQconnectStart followed by a PQconnectPoll loop is equivalent to - PQconnectdb. + . Note that when PQconnectStart - or PQconnectStartParams returns a non-null - pointer, you must call PQfinish when you are + or returns a non-null + pointer, you must call 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. @@ -518,7 +518,7 @@ typedef struct Returns a connection options array. This can be used to determine - all possible PQconnectdb options and their + all possible 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 @@ -531,8 +531,8 @@ typedef struct 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. + . If this is not done, a small amount of memory + is leaked for each call to . @@ -550,12 +550,12 @@ PQconninfoOption *PQconninfo(PGconn *conn); Returns a connection options array. This can be used to determine - all possible PQconnectdb options and the + all possible options and the values that were used to connect to the server. The return value points to an array of PQconninfoOption structures, which ends with an entry having a null keyword - pointer. All notes above for PQconndefaults also - apply to the result of PQconninfo. + pointer. All notes above for also + apply to the result of . @@ -577,7 +577,7 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); Parses a connection string and returns the resulting options as an array; or returns NULL if there is a problem with the connection string. This function can be used to extract - the PQconnectdb options in the provided + the options in the provided connection string. The return value points to an array of PQconninfoOption structures, which ends with an entry having a null keyword pointer. @@ -600,10 +600,10 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); After processing the options array, free it by passing it to - PQconninfoFree. If this is not done, some memory - is leaked for each call to PQconninfoParse. + . If this is not done, some memory + is leaked for each call to . Conversely, if an error occurs and errmsg is not NULL, - be sure to free the error string using PQfreemem. + be sure to free the error string using . @@ -622,10 +622,10 @@ void PQfinish(PGconn *conn); Note that even if the server connection attempt fails (as - indicated by PQstatus), the application should call PQfinish + indicated by ), the application should call to free the memory used by the PGconn object. The PGconn pointer must not be used again after - PQfinish has been called. + has been called. @@ -668,15 +668,15 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); These functions 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 can be useful for error recovery if a - working connection is lost. They differ from PQreset (above) in that they + working connection is lost. They differ from (above) in that they act in a nonblocking manner. These functions suffer from the same - restrictions as PQconnectStartParams, PQconnectStart + restrictions as , PQconnectStart and PQconnectPoll. To initiate a connection reset, call - PQresetStart. If it returns 0, the reset has + . If it returns 0, the reset has failed. If it returns 1, poll the reset using PQresetPoll in exactly the same way as you would create the connection using PQconnectPoll. @@ -688,9 +688,9 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); PQpingParamsPQpingParams - PQpingParams reports the status of the + reports the status of the server. It accepts connection parameters identical to those of - PQconnectdbParams, described above. It is not + , described above. It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt. @@ -757,9 +757,9 @@ PGPing PQpingParams(const char * const *keywords, PQpingPQping - PQping reports the status of the + reports the status of the server. It accepts connection parameters identical to those of - PQconnectdb, described above. It is not + , described above. It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt. @@ -770,7 +770,7 @@ PGPing PQping(const char *conninfo); - The return values are the same as for PQpingParams. + The return values are the same as for . @@ -1689,8 +1689,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname The following functions return parameter values established at connection. These values are fixed for the life of the connection. If a multi-host - connection string is used, the values of PQhost, - PQport, and PQpass can change if a new connection + connection string is used, the values of , + , and can change if a new connection is established using the same PGconn object. Other values are fixed for the lifetime of the PGconn object. @@ -1733,14 +1733,14 @@ char *PQpass(const PGconn *conn); - PQpass will return either the password specified + will return either the password specified in the connection parameters, or if there was none and the password was obtained from the password file, it will return that. In the latter case, if multiple hosts were specified in the connection parameters, it is - not possible to rely on the result of PQpass until + not possible to rely on the result of until the connection is established. The status of the connection can be - checked using the function PQstatus. + checked using the function . @@ -1762,15 +1762,15 @@ char *PQhost(const PGconn *conn); If the connection parameters specified both host and - hostaddr, then PQhost will + hostaddr, then will return the host information. If only hostaddr was specified, then that is returned. If multiple hosts were specified in the connection parameters, - PQhost returns the host actually connected to. + returns the host actually connected to. - PQhost returns NULL if the + returns NULL if the conn argument is NULL. Otherwise, if there is an error producing the host information (perhaps if the connection has not been fully established or there was an @@ -1779,9 +1779,9 @@ char *PQhost(const PGconn *conn); If multiple hosts were specified in the connection parameters, it is - not possible to rely on the result of PQhost until + not possible to rely on the result of until the connection is established. The status of the connection can be - checked using the function PQstatus. + checked using the function . @@ -1802,7 +1802,7 @@ char *PQhostaddr(const PGconn *conn); - PQhostaddr returns NULL if the + returns NULL if the conn argument is NULL. Otherwise, if there is an error producing the host information (perhaps if the connection has not been fully established or @@ -1825,11 +1825,11 @@ char *PQport(const PGconn *conn); If multiple ports were specified in the connection parameters, - PQport returns the port actually connected to. + returns the port actually connected to. - PQport returns NULL if the + returns NULL if the conn argument is NULL. Otherwise, if there is an error producing the port information (perhaps if the connection has not been fully established or there was an @@ -1838,9 +1838,9 @@ char *PQport(const PGconn *conn); If multiple ports were specified in the connection parameters, it is - not possible to rely on the result of PQport until + not possible to rely on the result of until the connection is established. The status of the connection can be - checked using the function PQstatus. + checked using the function . @@ -1901,15 +1901,15 @@ ConnStatusType PQstatus(const PGconn *conn); has the status CONNECTION_OK. A failed connection attempt is signaled by status CONNECTION_BAD. Ordinarily, an OK status will - remain so until PQfinish, but a communications + remain so until , 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. + . - See the entry for PQconnectStartParams, PQconnectStart + See the entry for , PQconnectStart and PQconnectPoll with regards to other status codes that might be returned. @@ -1951,7 +1951,7 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); Certain parameter values are reported by the server automatically at connection startup or whenever their values change. - PQparameterStatus can be used to interrogate these settings. + can be used to interrogate these settings. It returns the current value of a parameter if known, or NULL if the parameter is not known. @@ -1986,13 +1986,13 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName); Pre-3.0-protocol servers do not report parameter settings, but libpq includes logic to obtain values for server_version and client_encoding anyway. - Applications are encouraged to use PQparameterStatus + Applications are encouraged to use rather than ad hoc code to determine these values. (Beware however that on a pre-3.0 connection, changing client_encoding via SET after connection - startup will not be reflected by PQparameterStatus.) + startup will not be reflected by .) For server_version, see also - PQserverVersion, which returns the information in a + , which returns the information in a numeric form that is much easier to compare against. @@ -2059,14 +2059,14 @@ int PQserverVersion(const PGconn *conn); Prior to major version 10, PostgreSQL used three-part version numbers in which the first two parts together represented the major version. For those - versions, PQserverVersion uses two digits for each + versions, uses two digits for each part; for example version 9.1.5 will be returned as 90105, and version 9.2.0 will be returned as 90200. Therefore, for purposes of determining feature compatibility, - applications should divide the result of PQserverVersion + applications should divide the result of by 100 not 10000 to determine a logical major version number. In all release series, only the last two digits differ between minor releases (bug-fix releases). @@ -2090,13 +2090,13 @@ char *PQerrorMessage(const PGconn *conn); Nearly all libpq functions will set a message for - PQerrorMessage if they fail. Note that by + if they fail. Note that by libpq convention, a nonempty - PQerrorMessage result can consist of multiple lines, + result can consist of multiple lines, and will include a trailing newline. The caller should not free the result directly. It will be freed when the associated PGconn handle is passed to - PQfinish. The result string should not be + . The result string should not be expected to remain the same across operations on the PGconn structure. @@ -2352,8 +2352,8 @@ void *PQgetssl(const PGconn *conn); not be used in new applications, because the returned struct is specific to OpenSSL and will not be available if another SSL implementation is used. To check if a connection uses SSL, call - PQsslInUse instead, and for more details about the - connection, use PQsslAttribute. + instead, and for more details about the + connection, use . @@ -2393,11 +2393,11 @@ PGresult *PQexec(PGconn *conn, const char *command); 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 command to the server. The PQresultStatus function + the command to the server. The function should be called to check the return value for any errors (including the value of a null pointer, in which case it will return PGRES_FATAL_ERROR). Use - PQerrorMessage to get more information about such + to get more information about such errors. @@ -2406,7 +2406,7 @@ PGresult *PQexec(PGconn *conn, const char *command); The command string can include multiple SQL commands (separated by semicolons). Multiple queries sent in a single - PQexec call are processed in a single transaction, unless + call are processed in a single transaction, unless there are explicit BEGIN/COMMIT commands included in the query string to divide it into multiple transactions. (See @@ -2442,10 +2442,10 @@ PGresult *PQexecParams(PGconn *conn, - PQexecParams is like PQexec, but offers additional + is like , but offers additional functionality: parameter values can be specified separately from the command string proper, and query results can be requested in either text or binary - format. PQexecParams is supported only in protocol 3.0 and later + format. is supported only in protocol 3.0 and later connections; it will fail when using protocol 2.0. @@ -2566,14 +2566,14 @@ PGresult *PQexecParams(PGconn *conn, - The primary advantage of PQexecParams over - PQexec is that parameter values can be separated from the + The primary advantage of over + is that parameter values can be separated from the command string, thus avoiding the need for tedious and error-prone quoting and escaping. - Unlike PQexec, PQexecParams allows at most + Unlike , allows at most one SQL command in the given string. (There can be semicolons in it, but not more than one nonempty command.) This is a limitation of the underlying protocol, but has some usefulness as an extra defense against @@ -2619,11 +2619,11 @@ PGresult *PQprepare(PGconn *conn, - PQprepare creates a prepared statement for later - execution with PQexecPrepared. This feature allows + creates a prepared statement for later + execution with . This feature allows commands to be executed repeatedly without being parsed and planned each time; see for details. - PQprepare is supported only in protocol 3.0 and later + is supported only in protocol 3.0 and later connections; it will fail when using protocol 2.0. @@ -2647,23 +2647,23 @@ PGresult *PQprepare(PGconn *conn, 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 + for a means to find out what data types were inferred.) - As with PQexec, the result is normally a + As with , 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 + to get more information about such errors. - Prepared statements for use with PQexecPrepared can also + Prepared statements for use with can also be created by executing SQL statements. Also, although there is no libpq function for deleting a prepared statement, the SQL - PQexecPrepared is like PQexecParams, + is like , 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 + the current session. 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 + The parameters are identical to , 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). @@ -2725,9 +2725,9 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); - PQdescribePrepared allows an application to obtain + allows an application to obtain information about a previously prepared statement. - PQdescribePrepared is supported only in protocol 3.0 + is supported only in protocol 3.0 and later connections; it will fail when using protocol 2.0. @@ -2736,12 +2736,12 @@ PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); 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 + functions and + 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 + , , + , etc provide information about the result columns (if any) of the statement. @@ -2760,12 +2760,12 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); - PQdescribePortal allows an application to obtain + 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 + is supported only in protocol 3.0 and later connections; it will fail when using protocol 2.0. @@ -2774,8 +2774,8 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); 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 + , , + , etc can be applied to the PGresult to obtain information about the result columns (if any) of the portal. @@ -2807,7 +2807,7 @@ ExecStatusType PQresultStatus(const PGresult *res); - PQresultStatus can return one of the following values: + can return one of the following values: @@ -2922,7 +2922,7 @@ ExecStatusType PQresultStatus(const PGresult *res); A result of status PGRES_NONFATAL_ERROR will - never be returned directly by PQexec or other + never be returned directly by or other query execution functions; results of this kind are instead passed to the notice processor (see ). @@ -2936,7 +2936,7 @@ ExecStatusType PQresultStatus(const PGresult *res); Converts the enumerated type returned by - PQresultStatus into a string constant describing the + into a string constant describing the status code. The caller should not free the result. @@ -2959,21 +2959,21 @@ 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. + passed to . - Immediately following a PQexec or - PQgetResult call, - PQerrorMessage (on the connection) will return - the same string as PQresultErrorMessage (on + Immediately following a or + call, + (on the connection) will return + the same string as (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 + Use when you want to know the status associated with a particular PGresult; use - PQerrorMessage when you want to know the + when you want to know the status from the latest operation on the connection. @@ -2993,9 +2993,9 @@ char *PQresultVerboseErrorMessage(const PGresult *res, In some situations a client might wish to obtain a more detailed version of a previously-reported error. - PQresultVerboseErrorMessage addresses this need + addresses this need by computing the message that would have been produced - by PQresultErrorMessage if the specified + by if the specified verbosity settings had been in effect for the connection when the given PGresult was generated. If the PGresult is not an error result, @@ -3031,7 +3031,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); 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. + . @@ -3291,7 +3291,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); Frees the storage associated with a PGresult. Every command result should be - freed via PQclear when it is no longer + freed via when it is no longer needed. @@ -3303,7 +3303,7 @@ 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 command, nor even if you close the connection. To get rid of it, - you must call PQclear. Failure to do this + you must call . Failure to do this will result in memory leaks in your application. @@ -3370,7 +3370,7 @@ int PQnfields(const PGresult *res); 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 *PQfname(const PGresult *res, int column_number); @@ -3553,7 +3553,7 @@ int PQfsize(const PGresult *res, - PQfsize returns the space allocated for this column + returns the space allocated for this column in a database row, in other words the size of the server's internal representation of the data type. (Accordingly, it is not really very useful to clients.) A negative value indicates @@ -3578,8 +3578,8 @@ 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 + binary data in others. is preferred. + returns 1 only if all columns of the result are binary (format 1). @@ -3594,7 +3594,7 @@ int PQbinaryTuples(const PGresult *res); 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. + passed to . char *PQgetvalue(const PGresult *res, int row_number, @@ -3604,7 +3604,7 @@ char *PQgetvalue(const PGresult *res, For data in text format, the value returned by - PQgetvalue is a null-terminated character + 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 @@ -3615,12 +3615,12 @@ char *PQgetvalue(const PGresult *res, An empty string is returned if the field value is null. See - PQgetisnull to distinguish null values from + to distinguish null values from empty-string values. - The pointer returned by PQgetvalue points + The pointer returned by 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 @@ -3649,7 +3649,7 @@ int PQgetisnull(const PGresult *res, 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, + will return an empty string, not a null pointer, for a null field.) @@ -3672,10 +3672,10 @@ int PQgetlength(const PGresult *res, 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 + . 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 + rely on to obtain the actual data length. @@ -3694,7 +3694,7 @@ int PQnparams(const PGresult *res); This function is only useful when inspecting the result of - PQdescribePrepared. For other types of queries it + . For other types of queries it will return zero. @@ -3714,7 +3714,7 @@ 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 + . For other types of queries it will return zero. @@ -3783,7 +3783,7 @@ char *PQcmdStatus(PGresult *res); additional data such as the number of rows processed. The caller should not free the result directly. It will be freed when the associated PGresult handle is passed to - PQclear. + . @@ -3809,10 +3809,10 @@ char *PQcmdTuples(PGresult *res); or an EXECUTE of a prepared query that contains an INSERT, UPDATE, or DELETE statement. If the command that generated the PGresult was anything - else, PQcmdTuples returns an empty string. The caller + else, returns an empty string. The caller should not free the return value directly. It will be freed when the associated PGresult handle is passed to - PQclear. + . @@ -3843,9 +3843,9 @@ Oid PQoidValue(const PGresult *res); This function is deprecated in favor of - PQoidValue and is not thread-safe. + and is not thread-safe. It returns a string with the OID of the inserted row, while - PQoidValue returns the OID value. + returns the OID value. char *PQoidStatus(const PGresult *res); @@ -3877,23 +3877,23 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - PQescapeLiteral escapes a string for + escapes a string for use within an SQL command. This is useful when inserting data values as literal constants in SQL commands. Certain characters (such as quotes and backslashes) must be escaped to prevent them from being interpreted specially by the SQL parser. - PQescapeLiteral performs this operation. + performs this operation. - PQescapeLiteral returns an escaped version of the + returns an escaped version of the str parameter in memory allocated with malloc(). This memory should be freed using PQfreemem() when the result is no longer needed. A terminating zero byte is not required, and should not be counted in length. (If a terminating zero byte is found before length bytes are processed, - PQescapeLiteral stops at the zero; the behavior is + stops at the zero; the behavior is thus rather like strncpy.) The return string has all special characters replaced so that they can be properly processed by the PostgreSQL @@ -3903,7 +3903,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); - On error, PQescapeLiteral returns NULL and a suitable + On error, returns NULL and a suitable message is stored in the conn object. @@ -3919,7 +3919,7 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); Note that it is neither necessary nor correct to do escaping when a data - value is passed as a separate parameter in PQexecParams or + value is passed as a separate parameter in or its sibling routines. @@ -3936,7 +3936,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - PQescapeIdentifier escapes a string for + escapes a string for use as an SQL identifier, such as a table, column, or function name. This is useful when a user-supplied identifier might contain special characters that would otherwise not be interpreted as part @@ -3945,14 +3945,14 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - PQescapeIdentifier returns a version of the + returns a version of the str parameter escaped as an SQL identifier in memory allocated with malloc(). This memory must be freed using PQfreemem() when the result is no longer needed. A terminating zero byte is not required, and should not be counted in length. (If a terminating zero byte is found before length bytes are processed, - PQescapeIdentifier stops at the zero; the behavior is + stops at the zero; the behavior is thus rather like strncpy.) The return string has all special characters replaced so that it will be properly processed as an SQL identifier. A terminating zero byte @@ -3961,7 +3961,7 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); - On error, PQescapeIdentifier returns NULL and a suitable + On error, returns NULL and a suitable message is stored in the conn object. @@ -3988,10 +3988,10 @@ size_t PQescapeStringConn(PGconn *conn, - PQescapeStringConn escapes string literals, much like - PQescapeLiteral. Unlike PQescapeLiteral, + escapes string literals, much like + . Unlike , the caller is responsible for providing an appropriately sized buffer. - Furthermore, PQescapeStringConn does not generate the + Furthermore, does not generate the single quotes that must surround PostgreSQL string literals; they should be provided in the SQL command that the result is inserted into. The parameter from points to @@ -4000,7 +4000,7 @@ size_t PQescapeStringConn(PGconn *conn, string. A terminating zero byte is not required, and should not be counted in length. (If a terminating zero byte is found before length bytes are processed, - PQescapeStringConn stops at the zero; the behavior is + stops at the zero; the behavior is thus rather like strncpy.) to shall point to a buffer that is able to hold at least one more byte than twice the value of length, otherwise the behavior is undefined. @@ -4019,7 +4019,7 @@ size_t PQescapeStringConn(PGconn *conn, - PQescapeStringConn returns the number of bytes written + returns the number of bytes written to to, not including the terminating zero byte. @@ -4030,16 +4030,16 @@ size_t PQescapeStringConn(PGconn *conn, - PQescapeString is an older, deprecated version of - PQescapeStringConn. + is an older, deprecated version of + . size_t PQescapeString (char *to, const char *from, size_t length); - The only difference from PQescapeStringConn is that - PQescapeString does not take PGconn + The only difference from is that + does not take PGconn or error parameters. Because of this, it cannot adjust its behavior depending on the connection properties (such as character encoding) and therefore @@ -4048,12 +4048,12 @@ size_t PQescapeString (char *to, const char *from, size_t length); - PQescapeString can be used safely in + can be used safely in client programs that work with only one PostgreSQL connection at a time (in this case it can find out what it needs to know behind the scenes). In other contexts it is a security hazard and should be avoided in favor of - PQescapeStringConn. + . @@ -4064,7 +4064,7 @@ size_t PQescapeString (char *to, const char *from, size_t length); Escapes binary data for use within an SQL command with the type - bytea. As with PQescapeStringConn, + bytea. As with , this is only used when inserting data directly into an SQL command string. unsigned char *PQescapeByteaConn(PGconn *conn, @@ -4077,7 +4077,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, Certain byte values must be escaped when used as part of a bytea literal in an SQL statement. - PQescapeByteaConn escapes bytes using + escapes bytes using either hex encoding or backslash escaping. See for more information. @@ -4094,7 +4094,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - PQescapeByteaConn returns an escaped version of the + returns an escaped version of the from parameter binary string in memory allocated with malloc(). This memory should be freed using PQfreemem() when the result is no longer needed. The @@ -4119,8 +4119,8 @@ unsigned char *PQescapeByteaConn(PGconn *conn, - PQescapeBytea is an older, deprecated version of - PQescapeByteaConn. + is an older, deprecated version of + . unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, @@ -4129,15 +4129,15 @@ unsigned char *PQescapeBytea(const unsigned char *from, - The only difference from PQescapeByteaConn is that - PQescapeBytea does not take a PGconn - parameter. Because of this, PQescapeBytea can + The only difference from is that + does not take a PGconn + parameter. Because of this, can only be used safely in client programs that use a single PostgreSQL connection at a time (in this case it can find out what it needs to know behind the scenes). It might give the wrong results if used in programs that use multiple database connections (use - PQescapeByteaConn in such cases). + in such cases). @@ -4148,7 +4148,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, Converts a string representation of binary data into binary data - — the reverse of PQescapeBytea. This + — the reverse of . This is needed when retrieving bytea data in text format, but not when retrieving it in binary format. @@ -4159,19 +4159,19 @@ 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 - to a bytea column. PQunescapeBytea + such as might be returned by when applied + to a bytea column. converts this string representation into its binary representation. It returns a pointer to a buffer allocated with malloc(), or NULL on error, and puts the size of the buffer in to_length. The result must be - freed using PQfreemem when it is no longer needed. + freed using when it is no longer needed. This conversion is not exactly the inverse of - PQescapeBytea, because the string is not expected - to be escaped when received from PQgetvalue. + , because the string is not expected + to be escaped when received from . In particular this means there is no need for string quoting considerations, and so no need for a PGconn parameter. @@ -4191,14 +4191,14 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - The PQexec function is adequate for submitting + The function is adequate for submitting commands in normal, synchronous applications. It has a few deficiencies, however, that can be of importance to some users: - PQexec waits for the command to be completed. + waits for the command to be completed. The application might have other work to do (such as maintaining a user interface), in which case it won't want to block waiting for the response. @@ -4216,17 +4216,17 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); - PQexec can return only one + can return only one PGresult structure. If the submitted command string contains multiple SQL commands, all but the last PGresult are discarded by - PQexec. + . - PQexec always collects the command's entire result, + always collects the command's entire result, buffering it in a single PGresult. While this simplifies error-handling logic for the application, it can be impractical for results containing many rows. @@ -4237,21 +4237,21 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); Applications that do not like these limitations can instead use the - underlying functions that PQexec is built from: - PQsendQuery and PQgetResult. + underlying functions that is built from: + and . There are also - PQsendQueryParams, - PQsendPrepare, - PQsendQueryPrepared, - PQsendDescribePrepared, and - PQsendDescribePortal, - which can be used with PQgetResult to duplicate + , + , + , + , and + , + which can be used with to duplicate the functionality of - PQexecParams, - PQprepare, - PQexecPrepared, - PQdescribePrepared, and - PQdescribePortal + , + , + , + , and + respectively. @@ -4262,16 +4262,16 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); Submits a command to the server without waiting for the result(s). 1 is returned if the command was successfully dispatched and 0 if - not (in which case, use PQerrorMessage to get more + not (in which case, use to get more information about the failure). 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 - (on the same connection) until PQgetResult + After successfully calling , call + one or more times to obtain the + results. cannot be called again + (on the same connection) until has returned a null pointer, indicating that the command is done. @@ -4295,11 +4295,11 @@ int PQsendQueryParams(PGconn *conn, int resultFormat); - This is equivalent to PQsendQuery except that + This is equivalent to except that query parameters can be specified separately from the query string. The function's parameters are handled identically to - PQexecParams. Like - PQexecParams, it will not work on 2.0-protocol + . Like + , it will not work on 2.0-protocol connections, and it allows only one command in the query string. @@ -4320,13 +4320,13 @@ int PQsendPrepare(PGconn *conn, const Oid *paramTypes); - This is an asynchronous version of PQprepare: it + This is an asynchronous version of : it returns 1 if it was able to dispatch the request, and 0 if not. - After a successful call, call PQgetResult to + After a successful call, call to determine whether the server successfully created the prepared statement. The function's parameters are handled identically to - PQprepare. Like - PQprepare, it will not work on 2.0-protocol + . Like + , it will not work on 2.0-protocol connections. @@ -4349,12 +4349,12 @@ int PQsendQueryPrepared(PGconn *conn, int resultFormat); - This is similar to PQsendQueryParams, but + This is similar to , but the command to be executed is specified by naming a previously-prepared statement, instead of giving a query string. The function's parameters are handled identically to - PQexecPrepared. Like - PQexecPrepared, it will not work on + . Like + , it will not work on 2.0-protocol connections. @@ -4371,12 +4371,12 @@ int PQsendQueryPrepared(PGconn *conn, int PQsendDescribePrepared(PGconn *conn, const char *stmtName); - This is an asynchronous version of PQdescribePrepared: + This is an asynchronous version of : it returns 1 if it was able to dispatch the request, and 0 if not. - After a successful call, call PQgetResult to + After a successful call, call to obtain the results. The function's parameters are handled - identically to PQdescribePrepared. Like - PQdescribePrepared, it will not work on + identically to . Like + , it will not work on 2.0-protocol connections. @@ -4393,12 +4393,12 @@ int PQsendDescribePrepared(PGconn *conn, const char *stmtName); int PQsendDescribePortal(PGconn *conn, const char *portalName); - This is an asynchronous version of PQdescribePortal: + This is an asynchronous version of : it returns 1 if it was able to dispatch the request, and 0 if not. - After a successful call, call PQgetResult to + After a successful call, call to obtain the results. The function's parameters are handled - identically to PQdescribePortal. Like - PQdescribePortal, it will not work on + identically to . Like + , it will not work on 2.0-protocol connections. @@ -4410,12 +4410,12 @@ int PQsendDescribePortal(PGconn *conn, const char *portalName); Waits for the next result from a prior - PQsendQuery, - PQsendQueryParams, - PQsendPrepare, - PQsendQueryPrepared, - PQsendDescribePrepared, or - PQsendDescribePortal + , + , + , + , + , or + call, and returns it. A null pointer is returned when the command is complete and there will be no more results. @@ -4425,24 +4425,24 @@ PGresult *PQgetResult(PGconn *conn); - PQgetResult must be called repeatedly until + must be called repeatedly until it returns a null pointer, indicating that the command is done. (If called when no command is active, - PQgetResult will just return a null pointer + will just return a null pointer at once.) Each non-null result from - PQgetResult should be processed using the + should be processed using the same PGresult accessor functions previously described. Don't forget to free each result object with - PQclear when done with it. Note that - PQgetResult will block only if a command is + when done with it. Note that + will block only if a command is active and the necessary response data has not yet been read by - PQconsumeInput. + . - Even when PQresultStatus indicates a fatal - error, PQgetResult should be called until it + Even when indicates a fatal + error, should be called until it returns a null pointer, to allow libpq to process the error information completely. @@ -4453,9 +4453,9 @@ PGresult *PQgetResult(PGconn *conn); - Using PQsendQuery and - PQgetResult solves one of - PQexec's problems: If a command string contains + Using and + solves one of + 's problems: If a command string contains multiple SQL commands, the results of those commands can be obtained individually. (This allows a simple form of overlapped processing, by the way: the client can be handling the results of one @@ -4465,13 +4465,13 @@ PGresult *PQgetResult(PGconn *conn); Another frequently-desired feature that can be obtained with - PQsendQuery and PQgetResult + and is retrieving large query results a row at a time. This is discussed in . - By itself, calling PQgetResult + By itself, calling 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: @@ -4490,23 +4490,23 @@ int PQconsumeInput(PGconn *conn); - PQconsumeInput normally returns 1 indicating + normally returns 1 indicating no error, but returns 0 if there was some kind of - trouble (in which case PQerrorMessage can be + trouble (in which case can be consulted). Note that the result does not say whether any input data was actually collected. After calling - PQconsumeInput, the application can check - PQisBusy and/or + , the application can check + and/or PQnotifies to see if their state has changed. - PQconsumeInput can be called even if the + can be called even if the application is not prepared to deal with a result or notification just yet. The function will read available data and save it in a buffer, thereby causing a select() read-ready indication to go away. The application can thus use - PQconsumeInput to clear the + to clear the select() condition immediately, and then examine the results at leisure. @@ -4519,8 +4519,8 @@ int PQconsumeInput(PGconn *conn); Returns 1 if a command is busy, that is, - PQgetResult would block waiting for input. - A 0 return indicates that PQgetResult can be + would block waiting for input. + A 0 return indicates that can be called with assurance of not blocking. int PQisBusy(PGconn *conn); @@ -4528,8 +4528,8 @@ int PQisBusy(PGconn *conn); - PQisBusy will not itself attempt to read data - from the server; therefore PQconsumeInput + will not itself attempt to read data + from the server; therefore must be invoked first, or the busy state will never end. @@ -4543,11 +4543,11 @@ int PQisBusy(PGconn *conn); all the conditions that it must respond to. One of the conditions will be input available from the server, which in terms of select() means readable data on the file - descriptor identified by PQsocket. When the main + descriptor identified by . When the main loop detects input ready, it should call - PQconsumeInput to read the input. It can then - call PQisBusy, followed by - PQgetResult if PQisBusy + to read the input. It can then + call , followed by + if returns false (0). It can also call PQnotifies to detect NOTIFY messages (see ). @@ -4555,12 +4555,12 @@ int PQisBusy(PGconn *conn); A client that uses - PQsendQuery/PQgetResult + / can also attempt to cancel a command that is still being processed by the server; see . But regardless of - the return value of PQcancel, the application + the return value of , the application must continue with the normal result-reading sequence using - PQgetResult. A successful cancellation will + . A successful cancellation will simply cause the command to terminate sooner than it would have otherwise. @@ -4596,14 +4596,14 @@ int PQsetnonblocking(PGconn *conn, int arg); In the nonblocking state, calls to - PQsendQuery, PQputline, - PQputnbytes, PQputCopyData, - and PQendcopy will not block but instead return + , , + , , + and will not block but instead return an error if they need to be called again. - Note that PQexec does not honor nonblocking + Note that does not honor nonblocking mode; if it is called, it will act in blocking fashion anyway. @@ -4648,16 +4648,16 @@ int PQflush(PGconn *conn); After sending any command or data on a nonblocking connection, call - PQflush. If it returns 1, wait for the socket + . If it returns 1, wait for the socket to become read- or write-ready. If it becomes write-ready, call - PQflush again. If it becomes read-ready, call - PQconsumeInput, then call - PQflush again. Repeat until - PQflush returns 0. (It is necessary to check for - read-ready and drain the input with PQconsumeInput, + again. If it becomes read-ready, call + , then call + again. Repeat until + returns 0. (It is necessary to check for + read-ready and drain the input with , because the server can block trying to send us data, e.g. NOTICE messages, and won't read our data until we read its.) Once - PQflush returns 0, wait for the socket to be + returns 0, wait for the socket to be read-ready and then read the response as described above. @@ -4676,17 +4676,17 @@ int PQflush(PGconn *conn); entire result and returns it to the application as a single PGresult. This can be unworkable for commands that return a large number of rows. For such cases, applications can use - PQsendQuery and PQgetResult in + and in single-row mode. In this mode, the result row(s) are returned to the application one at a time, as they are received from the server. - To enter single-row mode, call PQsetSingleRowMode - immediately after a successful call of PQsendQuery + To enter single-row mode, call + immediately after a successful call of (or a sibling function). This mode selection is effective only for the - currently executing query. Then call PQgetResult + currently executing query. Then call repeatedly, until it returns null, as documented in . If the query returns any rows, they are returned as individual PGresult objects, which look like @@ -4696,11 +4696,11 @@ int PQflush(PGconn *conn); the query returns zero rows, a zero-row object with status PGRES_TUPLES_OK is returned; this is the signal that no more rows will arrive. (But note that it is still necessary to continue - calling PQgetResult until it returns null.) All of + calling until it returns null.) All of these PGresult objects will contain the same row description data (column names, types, etc) that an ordinary PGresult object for the query would have. - Each object should be freed with PQclear as usual. + Each object should be freed with as usual. @@ -4719,10 +4719,10 @@ int PQsetSingleRowMode(PGconn *conn); This function can only be called immediately after - PQsendQuery or one of its sibling functions, + or one of its sibling functions, before any other operation on the connection such as - PQconsumeInput or - PQgetResult. If called at the correct time, + or + . If called at the correct time, the function activates single-row mode for the current query and returns 1. Otherwise the mode stays unchanged and the function returns 0. In any case, the mode reverts to normal after @@ -4777,14 +4777,14 @@ PGcancel *PQgetCancel(PGconn *conn); - PQgetCancel creates a + creates a PGcancelPGcancel object given a PGconn connection object. It will return NULL if the given conn is NULL or an invalid connection. The PGcancel object is an opaque structure that is not meant to be accessed directly by the - application; it can only be passed to PQcancel - or PQfreeCancel. + application; it can only be passed to + or . @@ -4794,15 +4794,15 @@ PGcancel *PQgetCancel(PGconn *conn); - Frees a data structure created by PQgetCancel. + Frees a data structure created by . void PQfreeCancel(PGcancel *cancel); - PQfreeCancel frees a data object previously created - by PQgetCancel. + frees a data object previously created + by . @@ -4836,10 +4836,10 @@ int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); - PQcancel can safely be invoked from a signal + can safely be invoked from a signal handler, if the errbuf is a local variable in the signal handler. The PGcancel object is read-only - as far as PQcancel is concerned, so it can + as far as is concerned, so it can also be invoked from a thread that is separate from the one manipulating the PGconn object. @@ -4853,8 +4853,8 @@ int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); - PQrequestCancel is a deprecated variant of - PQcancel. + is a deprecated variant of + . int PQrequestCancel(PGconn *conn); @@ -4865,7 +4865,7 @@ int PQrequestCancel(PGconn *conn); command. It operates directly on the PGconn object, and in case of failure stores the error message in the PGconn object (whence it can - be retrieved by PQerrorMessage). Although + be retrieved by ). Although the functionality is the same, this approach creates hazards for multiple-thread programs and signal handlers, since it is possible that overwriting the PGconn's error message will @@ -4901,7 +4901,7 @@ int PQrequestCancel(PGconn *conn); - The function PQfnPQfn + The function PQfnPQfn requests execution of a server function via the fast-path interface: PGresult *PQfn(PGconn *conn, @@ -4961,7 +4961,7 @@ typedef struct PGresult pointer. The result status should be checked before the result is used. The caller is responsible for freeing the PGresult with - PQclear when it is no longer needed. + when it is no longer needed. @@ -4997,7 +4997,7 @@ typedef struct and NOTIFY commands as ordinary SQL commands. The arrival of NOTIFY messages can subsequently be detected by calling - PQnotifies.PQnotifies + PQnotifies.PQnotifies @@ -5020,7 +5020,7 @@ typedef struct pgNotify After processing a PGnotify object returned by PQnotifies, be sure to free it with - PQfreemem. It is sufficient to free the + . It is sufficient to free the PGnotify pointer; the relname and extra fields do not represent separate allocations. (The names of these fields @@ -5040,24 +5040,24 @@ typedef struct pgNotify libpq, the only way to ensure timely receipt of NOTIFY messages was to constantly submit commands, even empty ones, and then check PQnotifies after each - PQexec. While this still works, it is deprecated + . 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 - PQconsumeInput, then check + , then check PQnotifies. You can use select() to wait for data to arrive from the server, thereby using no CPU power unless there is - something to do. (See PQsocket to obtain the file + something to do. (See to obtain the file descriptor number to use with select().) Note that this will work OK whether you submit commands with - PQsendQuery/PQgetResult or - simply use PQexec. You should, however, remember + / or + simply use . You should, however, remember to check PQnotifies after each - PQgetResult or PQexec, to + or , to see if any notifications came in during the processing of the command. @@ -5081,7 +5081,7 @@ typedef struct pgNotify The overall process is that the application first issues the SQL - COPY command via PQexec or one + COPY command via or one of the equivalent functions. The response to this (if there is no error in the command) will be a PGresult object bearing a status code of PGRES_COPY_OUT or @@ -5093,26 +5093,26 @@ typedef struct pgNotify PGRES_COMMAND_OK for success or PGRES_FATAL_ERROR if some problem was encountered. At this point further SQL commands can be issued via - PQexec. (It is not possible to execute other SQL + . (It is not possible to execute other SQL 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 + in a string that could contain additional commands, the application must continue fetching results via - PQgetResult after completing the COPY - sequence. Only when PQgetResult returns - NULL is it certain that the PQexec + after completing the COPY + sequence. Only when returns + NULL is it certain that the 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. + PGRES_COPY_IN from or + . @@ -5202,7 +5202,7 @@ int PQputCopyData(PGconn *conn, The result is 1 if the data was queued, zero if it was not queued because of full buffers (this will only happen in nonblocking mode), or -1 if an error occurred. - (Use PQerrorMessage to retrieve details if + (Use to retrieve details if the return value is -1. If the value is zero, wait for write-ready and try again.) @@ -5247,18 +5247,18 @@ int PQputCopyEnd(PGconn *conn, nonblocking mode, this may only indicate that the termination message was successfully queued. (In nonblocking mode, to be certain that the data has been sent, you should next wait for - write-ready and call PQflush, repeating until it + write-ready and call , repeating until it returns zero.) Zero indicates that the function could not queue the termination message because of full buffers; this will only happen in nonblocking mode. (In this case, wait for - write-ready and try the PQputCopyEnd call + write-ready and try the call again.) If a hard error occurs, -1 is returned; you can use - PQerrorMessage to retrieve details. + to retrieve details. - After successfully calling PQputCopyEnd, call - PQgetResult to obtain the final result status of the + After successfully calling , call + to obtain the final result status of the COPY command. One can wait for this result to be available in the usual way. Then return to normal operation. @@ -5300,7 +5300,7 @@ int PQgetCopyData(PGconn *conn, be non-NULL. *buffer is set to point to the allocated memory, or to NULL in cases where no buffer is returned. A non-NULL result - buffer should be freed using PQfreemem when no longer + buffer should be freed using when no longer needed. @@ -5313,23 +5313,23 @@ int PQgetCopyData(PGconn *conn, progress, but no row is yet available (this is only possible when async is true). A result of -1 indicates that the COPY is done. A result of -2 indicates that an - error occurred (consult PQerrorMessage for the reason). + error occurred (consult for the reason). When async is true (not zero), - PQgetCopyData will not block waiting for input; it + will not block waiting for input; it will return zero if the COPY is still in progress but no complete row is available. (In this case wait for read-ready - and then call PQconsumeInput before calling - PQgetCopyData again.) When async is - false (zero), PQgetCopyData will block until data is + and then call before calling + again.) When async is + false (zero), will block until data is available or the operation completes. - After PQgetCopyData returns -1, call - PQgetResult to obtain the final result status of the + After returns -1, call + to obtain the final result status of the COPY command. One can wait for this result to be available in the usual way. Then return to normal operation. @@ -5367,7 +5367,7 @@ int PQgetline(PGconn *conn, This function copies up to length-1 characters into the buffer and converts the terminating newline into a zero byte. - PQgetline returns EOF at the + returns EOF at the end of input, 0 if the entire line has been read, and 1 if the buffer is full but the terminating newline has not yet been read. @@ -5399,28 +5399,28 @@ int PQgetlineAsync(PGconn *conn, - This function is similar to PQgetline, but it can be used + This function is similar to , 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 + application should call and + until the end-of-data signal is detected. - Unlike PQgetline, this function takes + Unlike , this function takes responsibility for detecting end-of-data. - On each call, PQgetlineAsync will return data if a + On each call, will return data if a complete data row is available in libpq's input buffer. Otherwise, no data is returned until the rest of the row arrives. The function 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. + , and then return to normal processing. @@ -5453,10 +5453,10 @@ int PQputline(PGconn *conn, The COPY data stream sent by a series of calls - to PQputline has the same format as that - returned by PQgetlineAsync, except that + to has the same format as that + returned by , except that applications are not obliged to send exactly one data row per - PQputline call; it is okay to send a partial + call; it is okay to send a partial line or multiple lines per call. @@ -5467,7 +5467,7 @@ int PQputline(PGconn *conn, \. as a final line to indicate to the server that it had finished sending COPY data. While this still works, it is deprecated and the special meaning of \. can be expected to be removed in a - future release. It is sufficient to call PQendcopy after + future release. It is sufficient to call after having sent the actual data. @@ -5489,7 +5489,7 @@ int PQputnbytes(PGconn *conn, - This is exactly like PQputline, except that the data + This is exactly like , except that the data buffer need not be null-terminated since the number of bytes to send is specified directly. Use this procedure when sending binary data. @@ -5507,35 +5507,35 @@ int PQendcopy(PGconn *conn); This function waits until the server has finished the copying. It should either be issued when the last string has been sent - to the server using PQputline or when the + to the server using or when the last string has been received from the server using PGgetline. It must be issued or the server will get out of sync with the client. Upon return from this function, the server is ready to receive the next SQL command. The return value is 0 on successful completion, - nonzero otherwise. (Use PQerrorMessage to + nonzero otherwise. (Use to retrieve details if the return value is nonzero.) - When using PQgetResult, the application should + When using , the application should respond to a PGRES_COPY_OUT result by executing - PQgetline repeatedly, followed by - PQendcopy after the terminator line is seen. - It should then return to the PQgetResult loop - until PQgetResult returns a null pointer. + repeatedly, followed by + after the terminator line is seen. + It should then return to the loop + until returns a null pointer. Similarly a PGRES_COPY_IN result is processed - by a series of PQputline calls followed by - PQendcopy, then return to the - PQgetResult loop. This arrangement will + by a series of calls followed by + , then return to the + loop. This arrangement will 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 - is done after PQendcopy. This will work + via and assume that the transaction + is done after . This will work correctly only if the COPY is the only SQL command in the command string. @@ -5592,7 +5592,7 @@ int PQsetClientEncoding(PGconn *conn, const char *encoding is the encoding you want to use. If the function successfully sets the encoding, it returns 0, otherwise -1. The current encoding for this connection can be - determined by using PQclientEncoding. + determined by using . @@ -5603,7 +5603,7 @@ int PQsetClientEncoding(PGconn *conn, const char * Determines the verbosity of messages returned by - PQerrorMessage and PQresultErrorMessage. + and . typedef enum { @@ -5616,7 +5616,7 @@ typedef enum PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); - PQsetErrorVerbosity sets the verbosity mode, + 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 @@ -5633,7 +5633,7 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); Changing the verbosity setting does not affect the messages available from already-existing PGresult objects, only subsequently-created ones. - (But see PQresultVerboseErrorMessage if you + (But see if you want to print a previous error with a different verbosity.) @@ -5645,8 +5645,8 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); Determines the handling of CONTEXT fields in messages - returned by PQerrorMessage - and PQresultErrorMessage. + returned by + and . typedef enum { @@ -5658,7 +5658,7 @@ typedef enum PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); - PQsetErrorContextVisibility sets the context display mode, + sets the context display mode, returning the connection's previous setting. This mode controls whether the CONTEXT field is included in messages. The NEVER mode @@ -5676,7 +5676,7 @@ PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit affect the messages available from already-existing PGresult objects, only subsequently-created ones. - (But see PQresultVerboseErrorMessage if you + (But see if you want to print a previous error with a different display mode.) @@ -5712,7 +5712,7 @@ void PQtrace(PGconn *conn, FILE *stream); - Disables tracing started by PQtrace. + Disables tracing started by . void PQuntrace(PGconn *conn); @@ -5744,9 +5744,9 @@ void PQfreemem(void *ptr); Frees memory allocated by libpq, particularly - PQescapeByteaConn, - PQescapeBytea, - PQunescapeBytea, + , + , + , and PQnotifies. It is particularly important that this function, rather than free(), be used on Microsoft Windows. This is because @@ -5765,14 +5765,14 @@ void PQfreemem(void *ptr); Frees the data structures allocated by - PQconndefaults or PQconninfoParse. + or . void PQconninfoFree(PQconninfoOption *connOptions); - A simple PQfreemem will not do for this, since + A simple will not do for this, since the array contains references to subsidiary strings. @@ -5812,14 +5812,14 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, is busy executing another query. If you wish to use the default algorithm for the server but want to avoid blocking, query password_encryption yourself before calling - PQencryptPasswordConn, and pass that value as the + , and pass that value as the algorithm. The return value is a string allocated by malloc. The caller can assume the string doesn't contain any special characters - that would require escaping. Use PQfreemem to free the + that would require escaping. Use to free the result when done with it. On error, returns NULL, and a suitable message is stored in the connection object. @@ -5836,9 +5836,9 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, char *PQencryptPassword(const char *passwd, const char *user); - PQencryptPassword is an older, deprecated version of - PQencryptPasswordConn. The difference is that - PQencryptPassword does not + is an older, deprecated version of + . The difference is that + does not require a connection object, and md5 is always used as the encryption algorithm. @@ -5869,8 +5869,8 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); registered in the connection are copied into the PGresult. (They do not get PGEVT_RESULTCREATE calls, but see - PQfireResultCreateEvents.) - Note that PQclear should eventually be called + .) + Note that should eventually be called on the object, just as with a PGresult returned by libpq itself. @@ -5905,7 +5905,7 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); The main reason that this function is separate from - PQmakeEmptyPGresult is that it is often appropriate + is that it is often appropriate to create a PGresult and fill it with data before invoking the event procedures. @@ -5919,7 +5919,7 @@ int PQfireResultCreateEvents(PGconn *conn, PGresult *res); Makes a copy of a PGresult object. The copy is not linked to the source result in any way and - PQclear must be called when the copy is no longer + must be called when the copy is no longer needed. If the function fails, NULL is returned. @@ -5983,7 +5983,7 @@ int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); The function will automatically grow the result's internal tuples array as needed. However, the tup_num argument must be - less than or equal to PQntuples, meaning this + less than or equal to , meaning this function can only grow the tuples array one tuple at a time. But any field of any existing tuple can be modified in any order. If a value at field_num already exists, it will be overwritten. @@ -6034,7 +6034,7 @@ size_t PQresultMemorySize(const PGresult *res); This value is the sum of all malloc requests associated with the PGresult object, that is, - all the space that will be freed by PQclear. + all the space that will be freed by . This information can be useful for managing memory consumption. @@ -6057,7 +6057,7 @@ int PQlibVersion(void); run time, whether specific functionality is available in the currently loaded version of libpq. The function can be used, for example, to determine which connection options are available in - PQconnectdb. + . @@ -6071,14 +6071,14 @@ int PQlibVersion(void); Prior to major version 10, PostgreSQL used three-part version numbers in which the first two parts together represented the major version. For those - versions, PQlibVersion uses two digits for each + versions, uses two digits for each part; for example version 9.1.5 will be returned as 90105, and version 9.2.0 will be returned as 90200. Therefore, for purposes of determining feature compatibility, - applications should divide the result of PQlibVersion + applications should divide the result of by 100 not 10000 to determine a logical major version number. In all release series, only the last two digits differ between minor releases (bug-fix releases). @@ -6127,11 +6127,11 @@ int PQlibVersion(void); - The function PQsetNoticeReceiver + The function PQsetNoticeReceiver notice receiver PQsetNoticeReceiver sets or examines the current notice receiver for a connection object. - Similarly, PQsetNoticeProcessor + Similarly, PQsetNoticeProcessor notice processor PQsetNoticeProcessor sets or examines the current notice processor. @@ -6164,9 +6164,9 @@ PQsetNoticeProcessor(PGconn *conn, receiver function is called. It is passed the message in the form of a PGRES_NONFATAL_ERROR PGresult. (This allows the receiver to extract - individual fields using PQresultErrorField, or obtain a - complete preformatted message using PQresultErrorMessage - or PQresultVerboseErrorMessage.) The same + individual fields using , or obtain a + complete preformatted message using + or .) The same void pointer passed to PQsetNoticeReceiver is also passed. (This pointer can be used to access application-specific state if needed.) @@ -6174,7 +6174,7 @@ PQsetNoticeProcessor(PGconn *conn, The default notice receiver simply extracts the message (using - PQresultErrorMessage) and passes it to the notice + ) and passes it to the notice processor. @@ -6204,7 +6204,7 @@ defaultNoticeProcessor(void *arg, const char *message) from it exist. At creation of a PGresult, the PGconn's current notice handling pointers are copied into the PGresult for possible use by functions like - PQgetvalue. + . @@ -6234,9 +6234,9 @@ defaultNoticeProcessor(void *arg, const char *message) In addition there is an instance data pointer, which starts out NULL in every PGconn and PGresult. This pointer can be manipulated using the - PQinstanceData, - PQsetInstanceData, - PQresultInstanceData and + , + , + and PQsetResultInstanceData functions. Note that unlike the passthrough pointer, instance data of a PGconn is not automatically inherited by PGresults created from @@ -6261,7 +6261,7 @@ defaultNoticeProcessor(void *arg, const char *message) PGEVT_REGISTER - The register event occurs when PQregisterEventProc + The register event occurs when is called. It is the ideal time to initialize any instanceData an event procedure may need. Only one register event will be fired per event handler per connection. If the @@ -6279,7 +6279,7 @@ typedef struct PGEventRegister *. This structure contains a PGconn that should be in the CONNECTION_OK status; guaranteed if one calls - PQregisterEventProc right after obtaining a good + right after obtaining a good PGconn. When returning a failure code, all cleanup must be performed as no PGEVT_CONNDESTROY event will be sent. @@ -6292,7 +6292,7 @@ typedef struct The connection reset event is fired on completion of - PQreset or PQresetPoll. In + or PQresetPoll. In both cases, the event is only fired if the reset was successful. If the event procedure fails, the entire connection reset will fail; the PGconn is put into @@ -6325,7 +6325,7 @@ typedef struct The connection destroy event is fired in response to - PQfinish. It is the event procedure's + . It is the event procedure's responsibility to properly clean up its event data as libpq has no ability to manage this memory. Failure to clean up will lead to memory leaks. @@ -6340,9 +6340,9 @@ typedef struct When a PGEVT_CONNDESTROY event is received, the evtInfo pointer should be cast to a PGEventConnDestroy *. This event is fired - prior to PQfinish performing any other cleanup. + prior to performing any other cleanup. The return value of the event procedure is ignored since there is no - way of indicating a failure from PQfinish. Also, + way of indicating a failure from . Also, an event procedure failure should not abort the process of cleaning up unwanted memory. @@ -6355,7 +6355,7 @@ typedef struct The result creation event is fired in response to any query execution function that generates a result, including - PQgetResult. This event will only be fired after + . This event will only be fired after the result has been created successfully. @@ -6374,7 +6374,7 @@ typedef struct instanceData that needs to be associated with the result. If the event procedure fails, the result will be cleared and the failure will be propagated. The event procedure must not try to - PQclear the result object for itself. When returning a + the result object for itself. When returning a failure code, all cleanup must be performed as no PGEVT_RESULTDESTROY event will be sent. @@ -6386,7 +6386,7 @@ typedef struct The result copy event is fired in response to - PQcopyResult. This event will only be fired after + . This event will only be fired after the copy is complete. Only event procedures that have successfully handled the PGEVT_RESULTCREATE or PGEVT_RESULTCOPY event for the source result @@ -6421,7 +6421,7 @@ typedef struct The result destroy event is fired in response to a - PQclear. It is the event procedure's + . It is the event procedure's responsibility to properly clean up its event data as libpq has no ability to manage this memory. Failure to clean up will lead to memory leaks. @@ -6436,9 +6436,9 @@ typedef struct When a PGEVT_RESULTDESTROY event is received, the evtInfo pointer should be cast to a PGEventResultDestroy *. This event is fired - prior to PQclear performing any other cleanup. + prior to performing any other cleanup. The return value of the event procedure is ignored since there is no - way of indicating a failure from PQclear. Also, + way of indicating a failure from . Also, an event procedure failure should not abort the process of cleaning up unwanted memory. @@ -6469,7 +6469,7 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) evtInfo pointer must be cast to the appropriate structure type to obtain further information about the event. The passThrough parameter is the pointer - provided to PQregisterEventProc when the event + provided to when the event procedure was registered. The function should return a non-zero value if it succeeds and zero if it fails. @@ -6586,8 +6586,8 @@ int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); Beware that any storage represented by data - will not be accounted for by PQresultMemorySize, - unless it is allocated using PQresultAlloc. + will not be accounted for by , + unless it is allocated using . (Doing so is recommendable because it eliminates the need to free such storage explicitly when the result is destroyed.) @@ -6777,8 +6777,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) The following environment variables can be used to select default connection parameter values, which will be used by - PQconnectdb, PQsetdbLogin and - PQsetdb if no value is directly specified by the calling + , and + 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. @@ -7697,7 +7697,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) If your application initializes libssl and/or libcrypto libraries and libpq is built with SSL support, you should call - PQinitOpenSSL to tell libpq + to tell libpq that the libssl and/or libcrypto libraries have been initialized by your application, so that libpq will not also initialize those libraries. @@ -7724,7 +7724,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); will initialize the OpenSSL library before first opening a database connection. When do_crypto is non-zero, the libcrypto library will be initialized. By - default (if PQinitOpenSSL is not called), both libraries + default (if is not called), both libraries are initialized. When SSL support is not compiled in, this function is present but does nothing. @@ -7756,9 +7756,9 @@ void PQinitSSL(int do_ssl); - PQinitSSL has been present since - PostgreSQL 8.0, while PQinitOpenSSL - was added in PostgreSQL 8.4, so PQinitSSL + has been present since + PostgreSQL 8.0, while + was added in PostgreSQL 8.4, so might be preferable for applications that need to work with older versions of libpq. @@ -7829,12 +7829,12 @@ int PQisthreadsafe(); - The deprecated functions PQrequestCancel and - PQoidStatus are not thread-safe and should not be - used in multithread programs. PQrequestCancel - can be replaced by PQcancel. - PQoidStatus can be replaced by - PQoidValue. + The deprecated functions and + are not thread-safe and should not be + used in multithread programs. + can be replaced by . + can be replaced by + . diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index 9f3b7852420..34dcfabe737 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -121,7 +121,7 @@ If an error occurs while executing any one of these functions, the function will return an otherwise-impossible value, typically 0 or -1. A message describing the error is stored in the connection object and - can be retrieved with PQerrorMessage. + can be retrieved with .