| PostgreSQL 9.1.14 Documentation | ||||
|---|---|---|---|---|
| Prev | Up | Chapter 31. libpq - C Library | Next | |
As always, there are some functions that just don't fit anywhere.
PQfreemem
     Frees memory allocated by libpq.
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
      allocating memory in a DLL and releasing it in the application works
      only if multithreaded/single-threaded, release/debug, and static/dynamic
      flags are the same for the DLL and the application.  On non-Microsoft
      Windows platforms, this function is the same as the standard library
      function free().
     
PQconninfoFree
           Frees the data structures allocated by
      PQconndefaults or PQconninfoParse.
void PQconninfoFree(PQconninfoOption *connOptions);
      A simple PQfreemem will not do for this, since
      the array contains references to subsidiary strings.
     
PQencryptPassword
     Prepares the encrypted form of a PostgreSQL password.
char * PQencryptPassword(const char *passwd, const char *user);
      This function is intended to be used by client applications that
      wish to send commands like ALTER USER joe PASSWORD
      'pwd'.  It is good practice not to send the original cleartext
      password in such a command, because it might be exposed in command
      logs, activity displays, and so on.  Instead, use this function to
      convert the password to encrypted form before it is sent.  The
      arguments are the cleartext password, and the SQL name of the user
      it is for.  The return value is a string allocated by
      malloc, or NULL if out of
      memory.  The caller can assume the string doesn't contain any
      special characters that would require escaping.  Use
      PQfreemem to free the result when done with it.
     
PQmakeEmptyPGresult
     Constructs an empty PGresult object with the given status.
PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
      This is libpq's internal function to allocate and
      initialize an empty PGresult object.  This
      function returns NULL if memory could not be allocated. It is
      exported because some applications find it useful to generate result
      objects (particularly objects with error status) themselves.  If
      conn is not null and status
      indicates an error, the current error message of the specified
      connection is copied into the PGresult.
      Also, if conn is not null, any event procedures
      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
      on the object, just as with a PGresult
      returned by libpq itself.
     
PQfireResultCreateEvents
     Fires a PGEVT_RESULTCREATE event (see Section 31.12) for each event procedure registered in the PGresult object. Returns non-zero for success, zero if any event procedure fails.
int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
The conn argument is passed through to event procedures but not used directly. It can be NULL if the event procedures won't use it.
Event procedures that have already received a PGEVT_RESULTCREATE or PGEVT_RESULTCOPY event for this object are not fired again.
      The main reason that this function is separate from
      PQmakeEmptyPGResult is that it is often appropriate
      to create a PGresult and fill it with data
      before invoking the event procedures.
     
PQcopyResult
           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
      needed.  If the function fails, NULL is returned.
PGresult *PQcopyResult(const PGresult *src, int flags);
This is not intended to make an exact copy. The returned result is always put into PGRES_TUPLES_OK status, and does not copy any error message in the source. (It does copy the command status string, however.) The flags argument determines what else is copied. It is a bitwise OR of several flags. PG_COPYRES_ATTRS specifies copying the source result's attributes (column definitions). PG_COPYRES_TUPLES specifies copying the source result's tuples. (This implies copying the attributes, too.) PG_COPYRES_NOTICEHOOKS specifies copying the source result's notify hooks. PG_COPYRES_EVENTS specifies copying the source result's events. (But any instance data associated with the source is not copied.)
PQsetResultAttrs
     Sets the attributes of a PGresult object.
int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
The provided attDescs are copied into the result. If the attDescs pointer is NULL or numAttributes is less than one, the request is ignored and the function succeeds. If res already contains attributes, the function will fail. If the function fails, the return value is zero. If the function succeeds, the return value is non-zero.
PQsetvalue
     Sets a tuple field value of a PGresult object.
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
      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.
      If len is -1 or
      value is NULL, the field value
      will be set to an SQL null value.  The
      value is copied into the result's private storage,
      thus is no longer needed after the function
      returns.  If the function fails, the return value is zero.  If the
      function succeeds, the return value is non-zero.
     
PQresultAlloc
     Allocate subsidiary storage for a PGresult object.
void *PQresultAlloc(PGresult *res, size_t nBytes);
      Any memory allocated with this function will be freed when
      res is cleared.  If the function fails,
      the return value is NULL.  The result is
      guaranteed to be adequately aligned for any type of data,
      just as for malloc.
     
PQlibVersion
     Return the version of libpq that is being used.
int PQlibVersion(void);
      The result of this function can be used to determine, at
      run time, if 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 for
      PQconnectdb or if the hex bytea
      output added in PostgreSQL 9.0 is supported.
     
The number is formed by converting the major, minor, and revision numbers into two-decimal-digit numbers and appending them together. For example, version 9.1 will be returned as 90100, and version 9.1.2 will be returned as 90102 (leading zeroes are not shown).
Note: This function appeared in PostgreSQL version 9.1, so it cannot be used to detect required functionality in earlier versions, since linking to it will create a link dependency on version 9.1.