diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index bfd66945f9c..ec1324c810c 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -903,7 +903,7 @@ only protocol 2.0. (Protocol 1.0 is obsolete and not supported by Returns the error message most recently generated by an operation on the connection. -char *PQerrorMessage(const PGconn* conn); +char *PQerrorMessage(const PGconn *conn); @@ -912,7 +912,9 @@ char *PQerrorMessage(const PGconn* conn); PQerrorMessage if they fail. Note that by libpq convention, a nonempty PQerrorMessage result will - include a trailing newline. + 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. @@ -1262,7 +1264,8 @@ processor (see ). Converts the enumerated type returned by PQresultStatus into - a string constant describing the status code. + a string constant describing the status code. The caller should not + free the result. char *PQresStatus(ExecStatusType status); @@ -1279,7 +1282,10 @@ if there was no error. char *PQresultErrorMessage(const PGresult *res); -If there was an error, the returned string will include a trailing newline. +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. @@ -1307,7 +1313,10 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); 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. +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. @@ -1535,8 +1544,10 @@ int PQnfields(const PGresult *res); PQfnamePQfname - Returns the column name associated with the given column number. - Column numbers start at 0. +Returns the column name associated with the given column number. +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); @@ -1566,8 +1577,8 @@ int PQfnumber(const PGresult *res, The given name is treated like an identifier in an SQL command, - that is, it is downcased unless double-quoted. For example, - given a query result generated from the SQL command + that is, it is downcased unless double-quoted. For example, + given a query result generated from the SQL command select 1 as FOO, 2 as "BAR"; @@ -1747,11 +1758,14 @@ returns 1 only if all columns of the result are binary (format 1). PQgetvaluePQgetvalue - Returns a single field value of one row - of a PGresult. - Row and column numbers start at 0. + 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, +char *PQgetvalue(const PGresult *res, int row_number, int column_number); @@ -1880,12 +1894,15 @@ results. Returns the command status tag from the SQL command that generated the PGresult. -char * PQcmdStatus(PGresult *res); +char *PQcmdStatus(PGresult *res); Commonly this is just the name of the command, but it may include additional -data such as the number of rows processed. +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. @@ -1896,7 +1913,7 @@ data such as the number of rows processed. Returns the number of rows affected by the SQL command. -char * PQcmdTuples(PGresult *res); +char *PQcmdTuples(PGresult *res); @@ -1906,7 +1923,10 @@ char * PQcmdTuples(PGresult *res); UPDATE, DELETE, MOVE, or FETCH, this returns a string containing the number of rows affected. If the - command was anything else, it returns the empty string. + command was anything else, it returns the empty string. The + caller should not free the result directly. It will be freed + when the associated PGresult handle is passed to + PQclear. @@ -1940,7 +1960,7 @@ Oid PQoidValue(const PGresult *res); OIDs.) If the command was not an INSERT, returns an empty string. -char * PQoidStatus(const PGresult *res); +char *PQoidStatus(const PGresult *res); @@ -2522,7 +2542,7 @@ parameters and results substitutes for a fast-path function call. The function PQfnPQfn requests execution of a server function via the fast-path interface: -PGresult* PQfn(PGconn* conn, +PGresult *PQfn(PGconn *conn, int fnid, int *result_buf, int *result_len, @@ -2620,7 +2640,7 @@ The function PQnotifies returned from PQnotifies, it is considered handled and will be removed from the list of notifications. -PGnotify* PQnotifies(PGconn *conn); +PGnotify *PQnotifies(PGconn *conn); typedef struct pgNotify { char *relname; /* notification condition name */ @@ -3291,7 +3311,7 @@ a void pointer that is the same one passed to The default notice processor is simply static void -defaultNoticeProcessor(void * arg, const char * message) +defaultNoticeProcessor(void *arg, const char *message) { fprintf(stderr, "%s", message); }