linkend="libpq-async"/>. If the query returns any rows, they are returned
as individual PGresult objects, which look like
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 <function>PQgetResult> until it returns null.) All of
+ calling <xref linkend="libpq-PQgetResult"/> 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 <function>PQclear> as usual.
+ Each object should be freed with <xref linkend="libpq-PQclear"/> as usual.
This function can only be called immediately after
- <function>PQsendQuery> or one of its sibling functions,
+ <xref linkend="libpq-PQsendQuery"/> or one of its sibling functions,
before any other operation on the connection such as
- <function>PQconsumeInput> or
- <function>PQgetResult>. If called at the correct time,
+ <xref linkend="libpq-PQconsumeInput"/> or
+ <xref linkend="libpq-PQgetResult"/>. 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
- <function>PQgetCancel> creates a
+ <xref linkend="libpq-PQgetCancel"/> creates a
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 <function>PQcancel>
- or <function>PQfreeCancel>.
+ application; it can only be passed to <xref linkend="libpq-PQcancel"/>
+ or <xref linkend="libpq-PQfreeCancel"/>.
- Frees a data structure created by <function>PQgetCancel>.
+ Frees a data structure created by <xref linkend="libpq-PQgetCancel"/>.
void PQfreeCancel(PGcancel *cancel);
- <function>PQfreeCancel> frees a data object previously created
- by <function>PQgetCancel>.
+ <xref linkend="libpq-PQfreeCancel"/> frees a data object previously created
+ by <xref linkend="libpq-PQgetCancel"/>.
- <function>PQcancel> can safely be invoked from a signal
+ <xref linkend="libpq-PQcancel"/> 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 <function>PQcancel> is concerned, so it can
+ as far as <xref linkend="libpq-PQcancel"/> is concerned, so it can
also be invoked from a thread that is separate from the one
manipulating the PGconn object.
- <function>PQrequestCancel> is a deprecated variant of
- <function>PQcancel>.
+ <xref linkend="libpq-PQrequestCancel"/> is a deprecated variant of
+ <xref linkend="libpq-PQcancel"/>.
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 <function>PQerrorMessage>). Although
+ be retrieved by <xref linkend="libpq-PQerrorMessage"/>). 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
+ The function
id="libpq-PQfn">PQfnPQfn requests execution of a server function via the fast-path interface:
PGresult *PQfn(PGconn *conn,
PGresult pointer. The result status should be
checked before the result is used. The caller is responsible for
freeing the PGresult with
- <function>PQclear> when it is no longer needed.
+ <xref linkend="libpq-PQclear"/> when it is no longer needed.
and NOTIFY commands as
ordinary SQL commands. The arrival of NOTIFY
messages can subsequently be detected by calling
+
id="libpq-PQnotifies">PQnotifies.PQnotifies
After processing a PGnotify object returned
by PQnotifies, be sure to free it with
- <function>PQfreemem>. It is sufficient to free the
+ <xref linkend="libpq-PQfreemem"/>. It is sufficient to free the
PGnotify pointer; the
relname and extra
fields do not represent separate allocations. (The names of these fields
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
- <function>PQexec>. While this still works, it is deprecated
+ <xref linkend="libpq-PQexec"/>. While this still works, it is deprecated
as a waste of processing power.
A better way to check for NOTIFY messages when you have no
useful commands to execute is to call
- <function>PQconsumeInput>, then check
+ <xref linkend="libpq-PQconsumeInput"/>, 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 <function>PQsocket> to obtain the file
+ something to do. (See <xref linkend="libpq-PQsocket"/> to obtain the file
descriptor number to use with select().) Note that
this will work OK whether you submit commands with
- <function>PQsendQuery/PQgetResult> or
- simply use <function>PQexec>. You should, however, remember
+ <xref linkend="libpq-PQsendQuery"/>/> or
+ simply use <xref linkend="libpq-PQexec"/>. You should, however, remember
to check PQnotifies after each
- <function>PQgetResult or PQexec>, to
+ <xref linkend="libpq-PQgetResult"/> or >, to
see if any notifications came in during the processing of the command.
The overall process is that the application first issues the SQL
- COPY command via <function>PQexec> or one
+ COPY command via <xref linkend="libpq-PQexec"/> 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
PGRES_COMMAND_OK for success or
PGRES_FATAL_ERROR if some problem was encountered.
At this point further SQL commands can be issued via
- <function>PQexec>. (It is not possible to execute other SQL
+ <xref linkend="libpq-PQexec"/>. (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
- <function>PQexec> in a string that could contain additional
+ <xref linkend="libpq-PQexec"/> in a string that could contain additional
commands, the application must continue fetching results via
- <function>PQgetResult> after completing the COPY
- sequence. Only when <function>PQgetResult> returns
- NULL is it certain that the <function>PQexec>
+ <xref linkend="libpq-PQgetResult"/> after completing the COPY
+ sequence. Only when <xref linkend="libpq-PQgetResult"/> returns
+ NULL is it certain that the <xref linkend="libpq-PQexec"/>
command string is done and it is safe to issue more commands.
The functions of this section should be executed only after obtaining
a result status of PGRES_COPY_OUT or
- PGRES_COPY_IN from <function>PQexec> or
- <function>PQgetResult>.
+ PGRES_COPY_IN from <xref linkend="libpq-PQexec"/> or
+ <xref linkend="libpq-PQgetResult"/>.
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 <function>PQerrorMessage> to retrieve details if
+ (Use <xref linkend="libpq-PQerrorMessage"/> to retrieve details if
the return value is -1. If the value is zero, wait for write-ready
and try again.)
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 <function>PQflush>, repeating until it
+ write-ready and call <xref linkend="libpq-PQflush"/>, 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 <function>PQputCopyEnd> call
+ write-ready and try the <xref linkend="libpq-PQputCopyEnd"/> call
again.) If a hard error occurs, -1 is returned; you can use
- <function>PQerrorMessage> to retrieve details.
+ <xref linkend="libpq-PQerrorMessage"/> to retrieve details.
- After successfully calling <function>PQputCopyEnd>, call
- <function>PQgetResult> to obtain the final result status of the
+ After successfully calling <xref linkend="libpq-PQputCopyEnd"/>, call
+ <xref linkend="libpq-PQgetResult"/> 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.
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 <function>PQfreemem> when no longer
+ buffer should be freed using <xref linkend="libpq-PQfreemem"/> when no longer
needed.
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 <function>PQerrorMessage> for the reason).
+ error occurred (consult <xref linkend="libpq-PQerrorMessage"/> for the reason).
When
async is true (not zero),
- <function>PQgetCopyData> will not block waiting for input; it
+ <xref linkend="libpq-PQgetCopyData"/> 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 <function>PQconsumeInput> before calling
- <
function>PQgetCopyData> again.) When async is- false (zero), <function>PQgetCopyData> will block until data is
+ and then call <xref linkend="libpq-PQconsumeInput"/> before calling
+ <
xref linkend="libpq-PQgetCopyData"/> again.) When
async is
+ false (zero), <xref linkend="libpq-PQgetCopyData"/> will block until data is
available or the operation completes.
- After <function>PQgetCopyData> returns -1, call
- <function>PQgetResult> to obtain the final result status of the
+ After <xref linkend="libpq-PQgetCopyData"/> returns -1, call
+ <xref linkend="libpq-PQgetResult"/> 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.
This function copies up to
length-1 characters into
the buffer and converts the terminating newline into a zero byte.
- <function>PQgetline> returns EOF at the
+ <xref linkend="libpq-PQgetline"/> 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.
- This function is similar to <function>PQgetline>, but it can be used
+ This function is similar to <xref linkend="libpq-PQgetline"/>, 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 <function>PQconsumeInput> and
- <function>PQgetlineAsync> until the
+ application should call <xref linkend="libpq-PQconsumeInput"/> and
+ <xref linkend="libpq-PQgetlineAsync"/> until the
end-of-data signal is detected.
- Unlike <function>PQgetline>, this function takes
+ Unlike <xref linkend="libpq-PQgetline"/>, this function takes
responsibility for detecting end-of-data.
- On each call, <function>PQgetlineAsync> will return data if a
+ On each call, <xref linkend="libpq-PQgetlineAsync"/> 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
- <function>PQendcopy>, and then return to normal processing.
+ <xref linkend="libpq-PQendcopy"/>, and then return to normal processing.
The COPY data stream sent by a series of calls
- to <function>PQputline> has the same format as that
- returned by <function>PQgetlineAsync>, except that
+ to <xref linkend="libpq-PQputline"/> has the same format as that
+ returned by <xref linkend="libpq-PQgetlineAsync"/>, except that
applications are not obliged to send exactly one data row per
- <function>PQputline> call; it is okay to send a partial
+ <xref linkend="libpq-PQputline"/> call; it is okay to send a partial
line or multiple lines per call.
\. 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 <function>PQendcopy> after
+ future release. It is sufficient to call <xref linkend="libpq-PQendcopy"/> after
having sent the actual data.
- This is exactly like <function>PQputline>, except that the data
+ This is exactly like <xref linkend="libpq-PQputline"/>, 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.
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 <function>PQputline> or when the
+ to the server using <xref linkend="libpq-PQputline"/> 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 <function>PQerrorMessage> to
+ nonzero otherwise. (Use <xref linkend="libpq-PQerrorMessage"/> to
retrieve details if the return value is nonzero.)
- When using <function>PQgetResult>, the application should
+ When using <xref linkend="libpq-PQgetResult"/>, the application should
respond to a PGRES_COPY_OUT result by executing
- <function>PQgetline> repeatedly, followed by
- <function>PQendcopy> after the terminator line is seen.
- It should then return to the <function>PQgetResult> loop
- until <function>PQgetResult> returns a null pointer.
+ <xref linkend="libpq-PQgetline"/> repeatedly, followed by
+ <xref linkend="libpq-PQendcopy"/> after the terminator line is seen.
+ It should then return to the <xref linkend="libpq-PQgetResult"/> loop
+ until <xref linkend="libpq-PQgetResult"/> returns a null pointer.
Similarly a PGRES_COPY_IN result is processed
- by a series of <function>PQputline> calls followed by
- <function>PQendcopy>, then return to the
- <function>PQgetResult> loop. This arrangement will
+ by a series of <xref linkend="libpq-PQputline"/> calls followed by
+ <xref linkend="libpq-PQendcopy"/>, then return to the
+ <xref linkend="libpq-PQgetResult"/> 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 <function>PQexec> and assume that the transaction
- is done after <function>PQendcopy>. This will work
+ via <xref linkend="libpq-PQexec"/> and assume that the transaction
+ is done after <xref linkend="libpq-PQendcopy"/>. This will work
correctly only if the COPY is the only
SQL command in the command string.
and 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 <function>PQclientEncoding>.
+ determined by using <xref linkend="libpq-PQclientEncoding"/>.
Determines the verbosity of messages returned by
- <function>PQerrorMessage and PQresultErrorMessage>.
+ <xref linkend="libpq-PQerrorMessage"/> and >.
typedef enum
{
PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
- <function>PQsetErrorVerbosity> sets the verbosity mode,
+ <xref linkend="libpq-PQsetErrorVerbosity"/> sets the verbosity mode,
returning the connection's previous setting.
In TERSE mode, returned messages include
severity, primary text, and position only; this will normally fit on a
Changing the verbosity setting does not affect the messages available
from already-existing PGresult objects, only
subsequently-created ones.
- (But see <function>PQresultVerboseErrorMessage> if you
+ (But see <xref linkend="libpq-PQresultVerboseErrorMessage"/> if you
want to print a previous error with a different verbosity.)
Determines the handling of CONTEXT fields in messages
- returned by <function>PQerrorMessage>
- and <function>PQresultErrorMessage>.
+ returned by <xref linkend="libpq-PQerrorMessage"/>
+ and <xref linkend="libpq-PQresultErrorMessage"/>.
typedef enum
{
PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context);
- <function>PQsetErrorContextVisibility> sets the context display mode,
+ <xref linkend="libpq-PQsetErrorContextVisibility"/> 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
affect the messages available from
already-existing PGresult objects, only
subsequently-created ones.
- (But see <function>PQresultVerboseErrorMessage> if you
+ (But see <xref linkend="libpq-PQresultVerboseErrorMessage"/> if you
want to print a previous error with a different display mode.)
- Disables tracing started by <function>PQtrace>.
+ Disables tracing started by <xref linkend="libpq-PQtrace"/>.
void PQuntrace(PGconn *conn);
Frees memory allocated by
libpq, particularly
- <function>PQescapeByteaConn>,
- <function>PQescapeBytea>,
- <function>PQunescapeBytea>,
+ <xref linkend="libpq-PQescapeByteaConn"/>,
+ <xref linkend="libpq-PQescapeBytea"/>,
+ <xref linkend="libpq-PQunescapeBytea"/>,
and PQnotifies.
It is particularly important that this function, rather than
free(), be used on Microsoft Windows. This is because
Frees the data structures allocated by
- <function>PQconndefaults or PQconninfoParse>.
+ <xref linkend="libpq-PQconndefaults"/> or >.
void PQconninfoFree(PQconninfoOption *connOptions);
- A simple <function>PQfreemem> will not do for this, since
+ A simple <xref linkend="libpq-PQfreemem"/> will not do for this, since
the array contains references to subsidiary strings.
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
- <function>PQencryptPasswordConn>, and pass that value as the
+ <xref linkend="libpq-PQencryptPasswordConn"/>, and pass that value as the
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 <function>PQfreemem> to free the
+ that would require escaping. Use <xref linkend="libpq-PQfreemem"/> to free the
result when done with it. On error, returns NULL, and
a suitable message is stored in the connection object.
char *PQencryptPassword(const char *passwd, const char *user);
- <function>PQencryptPassword> is an older, deprecated version of
- <function>PQencryptPasswordConn>. The difference is that
- <function>PQencryptPassword> does not
+ <xref linkend="libpq-PQencryptPassword"/> is an older, deprecated version of
+ <xref linkend="libpq-PQencryptPasswordConn"/>. The difference is that
+ <xref linkend="libpq-PQencryptPassword"/> does not
require a connection object, and md5 is always used as the
encryption algorithm.
registered in the connection are copied into the
PGresult. (They do not get
PGEVT_RESULTCREATE calls, but see
- <function>PQfireResultCreateEvents>.)
- Note that <function>PQclear> should eventually be called
+ <xref linkend="libpq-PQfireResultCreateEvents"/>.)
+ Note that <xref linkend="libpq-PQclear"/> should eventually be called
on the object, just as with a PGresult
returned by
libpq itself.
The main reason that this function is separate from
- <function>PQmakeEmptyPGresult> is that it is often appropriate
+ <xref linkend="libpq-PQmakeEmptyPGresult"/> is that it is often appropriate
to create a PGresult and fill it with data
before invoking the event procedures.
Makes a copy of a PGresult object. The copy is
not linked to the source result in any way and
- <function>PQclear> must be called when the copy is no longer
+ <xref linkend="libpq-PQclear"/> must be called when the copy is no longer
needed. If the function fails, NULL is returned.
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 <function>PQntuples>, meaning this
+ less than or equal to <xref linkend="libpq-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.
This value is the sum of all malloc requests
associated with the PGresult object, that is,
- all the space that will be freed by <function>PQclear>.
+ all the space that will be freed by <xref linkend="libpq-PQclear"/>.
This information can be useful for managing memory consumption.
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
- <function>PQconnectdb>.
+ <xref linkend="libpq-PQconnectdb"/>.
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, <function>PQlibVersion> uses two digits for each
+ versions, <xref linkend="libpq-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 <function>PQlibVersion>
+ applications should divide the result of <xref linkend="libpq-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).
- The function PQsetNoticeReceiver
+ The function id="libpq-PQsetNoticeReceiver">PQsetNoticeReceiver
PQsetNoticeReceiver sets or
examines the current notice receiver for a connection object.
- Similarly, PQsetNoticeProcessor
+ Similarly, id="libpq-PQsetNoticeProcessor">PQsetNoticeProcessor
PQsetNoticeProcessor sets or
examines the current notice processor.
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 <function>PQresultErrorField>, or obtain a
- complete preformatted message using <function>PQresultErrorMessage>
- or <function>PQresultVerboseErrorMessage>.) The same
+ individual fields using <xref linkend="libpq-PQresultErrorField"/>, or obtain a
+ complete preformatted message using <xref linkend="libpq-PQresultErrorMessage"/>
+ or <xref linkend="libpq-PQresultVerboseErrorMessage"/>.) The same
void pointer passed to PQsetNoticeReceiver is also
passed. (This pointer can be used to access application-specific state
if needed.)
The default notice receiver simply extracts the message (using
- <function>PQresultErrorMessage>) and passes it to the notice
+ <xref linkend="libpq-PQresultErrorMessage"/>) and passes it to the notice
processor.
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
- <function>PQgetvalue>.
+ <xref linkend="libpq-PQgetvalue"/>.
In addition there is an instance data pointer, which starts
out NULL in every PGconn and PGresult.
This pointer can be manipulated using the
- <function>PQinstanceData>,
- <function>PQsetInstanceData>,
- <function>PQresultInstanceData> and
+ <xref linkend="libpq-PQinstanceData"/>,
+ <xref linkend="libpq-PQsetInstanceData"/>,
+ <xref linkend="libpq-PQresultInstanceData"/> and
PQsetResultInstanceData functions. Note that
unlike the passthrough pointer, instance data of a PGconn
is not automatically inherited by PGresults created from
PGEVT_REGISTER
- The register event occurs when <function>PQregisterEventProc>
+ The register event occurs when <xref linkend="libpq-PQregisterEventProc"/>
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
PGEventRegister *. This structure contains a
PGconn that should be in the
CONNECTION_OK status; guaranteed if one calls
- <function>PQregisterEventProc> right after obtaining a good
+ <xref linkend="libpq-PQregisterEventProc"/> right after obtaining a good
PGconn. When returning a failure code, all
cleanup must be performed as no PGEVT_CONNDESTROY
event will be sent.
The connection reset event is fired on completion of
- <function>PQreset> or PQresetPoll. In
+ <xref linkend="libpq-PQreset"/> 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
The connection destroy event is fired in response to
- <function>PQfinish>. It is the event procedure's
+ <xref linkend="libpq-PQfinish"/>. 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.
When a PGEVT_CONNDESTROY event is received, the
evtInfo pointer should be cast to a
PGEventConnDestroy *. This event is fired
- prior to <function>PQfinish> performing any other cleanup.
+ prior to <xref linkend="libpq-PQfinish"/> performing any other cleanup.
The return value of the event procedure is ignored since there is no
- way of indicating a failure from <function>PQfinish>. Also,
+ way of indicating a failure from <xref linkend="libpq-PQfinish"/>. Also,
an event procedure failure should not abort the process of cleaning up
unwanted memory.
The result creation event is fired in response to any query execution
function that generates a result, including
- <function>PQgetResult>. This event will only be fired after
+ <xref linkend="libpq-PQgetResult"/>. This event will only be fired after
the result has been created successfully.
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
- <function>PQclear> the result object for itself. When returning a
+ <xref linkend="libpq-PQclear"/> the result object for itself. When returning a
failure code, all cleanup must be performed as no
PGEVT_RESULTDESTROY event will be sent.
The result copy event is fired in response to
- <function>PQcopyResult>. This event will only be fired after
+ <xref linkend="libpq-PQcopyResult"/>. 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
The result destroy event is fired in response to a
- <function>PQclear>. It is the event procedure's
+ <xref linkend="libpq-PQclear"/>. 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.
When a PGEVT_RESULTDESTROY event is received, the
evtInfo pointer should be cast to a
PGEventResultDestroy *. This event is fired
- prior to <function>PQclear> performing any other cleanup.
+ prior to <xref linkend="libpq-PQclear"/> performing any other cleanup.
The return value of the event procedure is ignored since there is no
- way of indicating a failure from <function>PQclear>. Also,
+ way of indicating a failure from <xref linkend="libpq-PQclear"/>. Also,
an event procedure failure should not abort the process of cleaning up
unwanted memory.
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 <function>PQregisterEventProc> when the event
+ provided to <xref linkend="libpq-PQregisterEventProc"/> when the event
procedure was registered. The function should return a non-zero value
if it succeeds and zero if it fails.
Beware that any storage represented by
data- will not be accounted for by <function>PQresultMemorySize>,
- unless it is allocated using <function>PQresultAlloc>.
+ will not be accounted for by <xref linkend="libpq-PQresultMemorySize"/>,
+ unless it is allocated using <xref linkend="libpq-PQresultAlloc"/>.
(Doing so is recommendable because it eliminates the need to free
such storage explicitly when the result is destroyed.)
The following environment variables can be used to select default
connection parameter values, which will be used by
- <function>PQconnectdb, PQsetdbLogin> and
- <function>PQsetdb> if no value is directly specified by the calling
+ <xref linkend="libpq-PQconnectdb"/>, > and
+ <xref linkend="libpq-PQsetdb"/> if no value is directly specified by the calling
code. These are useful to avoid hard-coding database connection
information into simple client applications, for example.
If your application initializes libssl and/or
libcrypto libraries and
libpq
is built with
SSL support, you should call
- <
function>PQinitOpenSSL> to tell libpq+ <
xref linkend="libpq-PQinitOpenSSL"/> 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.
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 <function>PQinitOpenSSL> is not called), both libraries
+ default (if <xref linkend="libpq-PQinitOpenSSL"/> is not called), both libraries
are initialized. When SSL support is not compiled in, this function is
present but does nothing.
- <function>PQinitSSL> has been present since
-
PostgreSQL 8.0, while <
function>PQinitOpenSSL>- was added in
PostgreSQL 8.4, so <
function>PQinitSSL>+ <xref linkend="libpq-PQinitSSL"/> has been present since
+
PostgreSQL 8.0, while <
xref linkend="libpq-PQinitOpenSSL"/>
+ was added in
PostgreSQL 8.4, so <
xref linkend="libpq-PQinitSSL"/>
might be preferable for applications that need to work with older
- The deprecated functions <function>PQrequestCancel> and
- <function>PQoidStatus> are not thread-safe and should not be
- used in multithread programs. <function>PQrequestCancel>
- can be replaced by <function>PQcancel>.
- <function>PQoidStatus> can be replaced by
- <function>PQoidValue>.
+ The deprecated functions <xref linkend="libpq-PQrequestCancel"/> and
+ <xref linkend="libpq-PQoidStatus"/> are not thread-safe and should not be
+ used in multithread programs. <xref linkend="libpq-PQrequestCancel"/>
+ can be replaced by <xref linkend="libpq-PQcancel"/>.
+ <xref linkend="libpq-PQoidStatus"/> can be replaced by
+ <xref linkend="libpq-PQoidValue"/>.
projects / postgresql.git / commitdiff