34.11. Miscellaneous Functions

As always, there are some functions that just don't fit anywhere.

PQfreemem : Frees memory allocated by libpq.

```synopsis
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.

```synopsis
void PQconninfoFree(PQconninfoOption *connOptions);
```

A simple `PQfreemem` will not do for this, since
the array contains references to subsidiary strings.

PQencryptPasswordConn : Prepares the encrypted form of a PostgreSQL password.

```synopsis
char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);
```

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 **`passwd`** and **`user`** arguments
are the cleartext password, and the SQL name of the user it is for.
**`algorithm`** specifies the encryption algorithm
to use to encrypt the password. Currently supported algorithms are
`md5` and `scram-sha-256` (`on` and
`off` are also accepted as aliases for `md5`, for
compatibility with older server versions). Note that support for
`scram-sha-256` was introduced in PostgreSQL
version 10, and will not work correctly with older server versions. If
**`algorithm`** is `NULL`, this function will query
the server for the current value of the
[password_encryption](runtime-config-connection.md#GUC-PASSWORD-ENCRYPTION) setting. That can block, and
will fail if the current transaction is aborted, or if the connection
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
**`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
result when done with it. On error, returns `NULL`, and
a suitable message is stored in the connection object.

PQencryptPassword : Prepares the md5-encrypted form of a PostgreSQL password.

```synopsis
char *PQencryptPassword(const char *passwd, const char *user);
```

`PQencryptPassword` is an older, deprecated version of
`PQencryptPasswordConn`. The difference is that
`PQencryptPassword` does not
require a connection object, and `md5` is always used as the
encryption algorithm.

PQmakeEmptyPGresult : Constructs an empty PGresult object with the given status.

```synopsis
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 34.13) for each event procedure registered in the PGresult object. Returns non-zero for success, zero if any event procedure fails.

```synopsis
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.

```synopsis
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.

```synopsis
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.

```synopsis
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.

```synopsis
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.

```synopsis
int PQlibVersion(void);
```

The result of this function can be used to determine, at
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`.

The result is formed by multiplying the library's major version
number by 10000 and adding the minor version number. For example,
version 10.1 will be returned as 100001, and version 11.0 will be
returned as 110000.

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
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`
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).

### Note

This function appeared in PostgreSQL version 9.1, so
it cannot be used to detect required functionality in earlier
versions, since calling it will create a link dependency
on version 9.1 or later.