Отправляет команду на сервер и ожидает завершения выполнения.

PGresult *PQexec(PGconn *conn, const char *command);

Возвращает PGresult указатель или, возможно, пустой указатель. Как правило, возвращается ненулевой указатель, за исключением ситуаций с нехваткой памяти или критических ошибок, таких как невозможность передачи команды на сервер. Данная PQresultStatus функция должна быть вызвана для проверки возвращаемого значения на наличие ошибок (включая случай получения пустого указателя, при котором будет возвращено PGRES_FATAL_ERROR). Используйте PQerrorMessage для получения подробных сведений о таких ошибках.

Отправляет команду серверу и ожидает результат, с возможностью передачи параметров отдельно от текста SQL- команды.

PGresult *PQexecParams(PGconn *conn,
                       const char *command,
                       int nParams,
                       const Oid *paramTypes,
                       const char * const *paramValues,
                       const int *paramLengths,
                       const int *paramFormats,
                       int resultFormat);

PQexecParams аналогична PQexec, но предоставляет дополнительные возможности: значения параметров могут быть указаны отдельно от самой строки команды, а результаты запроса могут быть запрошены в текстовом или двоичном формате.

Аргументы функции:

Отправляет запрос на создание подготовленного оператора с заданными параметрами и ожидает завершения.

тип PGresult *PQprepare(тип PGconn *объект conn,
                    const char *stmtName,
                    const char *query,
                    int nParams,
                    const тип Oid *paramTypes);

PQprepare создает подготовленный оператор для последующего выполнение с использованием PQexecPrepared. Данная функция позволяет многократно выполнять команды без необходимости их повторного синтаксического анализа и планирования; см. PREPARE для получения подробных сведений.

Функция создает подготовленный оператор с именем stmtName на основе запроса строки, которая должна содержать одну команду SQL. stmtName могут быть "" для создания неименованного оператора; в этом случае любой ранее существовавший неименованный оператор автоматически заменяется. В противном случае возникает ошибка, если имя оператора уже определено в текущем сеансе. Если используются какие-либо параметры, ссылки на них в запросе указываются как в запросе как $1, $2и т. д. nParams является количеством параметров, типы которых предварительно определены в массиве paramTypes[]. (Указатель на массив может быть NULL, значение NULL когда параметр nParams равен нулю.) paramTypes[] определяет по типам Oid типы данных, которые должны быть назначены символам параметров. Если параметр paramTypes имеет значение NULL значение NULL, или если какой-либо конкретный элемент массива равен нулю, сервер назначает тип данных символу параметра таким же образом, как это было бы сделано для нетипизированной литеральной строки. Кроме того, в запросе могут использоваться символы параметров с номерами, превышающими nParams; типы данных для этих символов также будут выведены. (См. PQdescribePrepared раздел, в котором описывается способ определения того, какие типы данных были выведены.)

Как и в случае с функцией PQexec, результатом обычно является PGresult объект, содержимое которого указывает на успешное или неудачное выполнение операции на стороне сервера. На нехватку памяти или на невозможность отправки команды указывает результат со значением NULL. Для получения подробных сведений о таких ошибках используйте PQerrorMessage функцию PQerrorMessage.

Отправляет запрос на выполнение подготовленного оператора с заданными параметрами и ожидает получения результата.

PGresult *PQexecPrepared(PGconn *conn,
                         const char *stmtName,
                         int nParams,
                         const char * const *paramValues,
                         const int *paramLengths,
                         const int *paramFormats,
                         int resultFormat);

PQexecPrepared аналогична PQexecParams, но подлежащая выполнению команда задается путем указания имени ранее подготовленного оператора вместо передачи строки запроса. Данная функциональность позволяет выполнять разбор и планирование многократно используемых команд всего один раз, а не при каждом их выполнении. Оператор должен быть предварительно подготовлен в рамках текущего сеанса.

Параметры идентичны параметрам функции PQexecParams, за исключением того, что вместо строки запроса передается имя подготовленного оператора, а paramTypes[] параметр отсутствует (он не требуется, так как типы параметров подготовленного оператора были определены при его создании).

Отправляет запрос на получение информации об указанном подготовленном операторе и ожидает завершения выполнения.

PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);

PQdescribePrepared позволяет приложению получить сведения о ранее подготовленном операторе.

stmtName может быть "" или значение NULL для обращения к неименованному оператору; в противном случае должно быть указано имя существующего подготовленного оператора. В случае успешного выполнения PGresult с статусом PGRES_COMMAND_OK возвращается. Тип функции PQnparams и PQparamtype могут быть применены к данному объекту PGresult для получения сведений о параметрах подготовленного оператора, а функции PQnfields, PQfname, PQftypeи т. д. предоставляют сведения о столбцах результата (если они есть) этого оператора.

Отправляет запрос на получение информации об указанном портал и ожидает завершения операции.

PGresult *PQdescribePortal(PGconn *conn, const char *portalName);

PQdescribePortal позволяет приложению получить сведения о ранее созданном портале. (libpq не предоставляет прямого доступа к порталам, однако для проверки свойств можно использовать данную функцию курсора, созданного с помощью DECLARE CURSOR SQL-команды.)

portalName может быть "" или значение NULL для обращения к соответствует неименованному порталу; в противном случае значением параметра должно быть имя существующего портала. В случае успешного выполнения PGresult со статусом PGRES_COMMAND_OK возвращается. Функции PQnfields, PQfname, PQftype, и т. д. могут быть применены к PGresult для получения информации о результирующих столбцах (если таковые имеются) портала.

Отправляет запрос на закрытие указанного подготовленного оператора и ожидает завершения операции.

PGresult *PQclosePrepared(PGconn *conn, const char *stmtName);

PQclosePrepared позволяет приложению закрыть ранее подготовленный оператор. При закрытии оператора освобождаются все связанные с ним ресурсы на сервере, что позволяет использовать его имя повторно.

stmtName может быть "" или значение NULL для ссылки на неименованный оператор. Допускается ситуация, когда оператор с таким именем отсутствует — в этом случае операция будет пустой (no-op). В случае успеха PGresult с статусом PGRES_COMMAND_OK возвращается объект.

Отправляет запрос на закрытие указанного портала и ожидает завершения.

PGresult *PQclosePortal(PGconn *conn, const char *portalName);

PQclosePortal позволяет приложению инициировать закрытие ранее созданного портала. Закрытие портала освобождает все связанные с ним ресурсы на сервере, что позволяет использовать его имя использовать повторно. (libpq не предоставляет прямого доступа к порталам, однако данную функцию можно использовать для закрытия курсора, созданного с помощью DECLARE CURSOR SQL-команды.)

portalName может быть "" или значение NULL для обращения к неименованному порталу. Допускается ситуация, когда портал с таким именем не существует; в этом случае данная операция — это пустой (no-op). В случае успеха PGresult со статусом PGRES_COMMAND_OK возвращается объект.

Функция PQresultStatus возвращает статус результата выполнения команды.

ExecStatusType PQresultStatus(const PGresult *res);

PQresultStatus функция может возвращать одно из следующих значений:

Если код состояния результата — PGRES_TUPLES_OK, PGRES_SINGLE_TUPLE, или PGRES_TUPLES_CHUNK, то для извлечения возвращённых запросом строк можно использовать описанные ниже функции возвращённых запросом. Обратите внимание, что SELECT команда, которая извлекает ноль строк, всё равно возвращает код PGRES_TUPLES_OK. PGRES_COMMAND_OK используется для команд, которые никогда не могут возвращать строки (INSERT или UPDATE без RETURNING предложения, и т. д.). Ответ PGRES_EMPTY_QUERY может свидетельствовать о наличии ошибки в клиентском программном обеспечении.

Результат со статусом PGRES_NONFATAL_ERROR будет никогда не возвращается напрямую функцией PQexec или другими функциями выполнения запросов; вместо этого результаты такого рода передаются обработчику уведомлений (см. Раздел 4.1.13).

Преобразует возвращаемый функцией перечисляемый тип PQresultStatus в строковую константу, описывающую код состояния. Вызывающая сторона не должна освобождать данный результат.

char *PQresStatus(ExecStatusType status);

Возвращает сообщение об ошибке, связанное с командой, или пустую строку в случае отсутствия ошибки.

char *PQresultErrorMessage(const PGresult *res);

В случае возникновения ошибки возвращаемая строка будет содержать в конце символ перевода строки. Вызывающей программе не следует освобождать результат напрямую. Он будет освобожден, когда соответствующий PGresult дескриптор будет передан в функцию PQclear.

Непосредственно после вызова PQexec или PQgetResult функции, PQerrorMessage (для соединения) будет возвращена та же строка, что и функцией PQresultErrorMessage (для результата). Однако PGresult будет сохраняет сообщение об ошибке до момента своего удаления, тогда как сообщение об ошибке соединения будет изменяться при выполнении последующих операций. Для этого вызовите функцию PQresultErrorMessage если требуется узнать состояние, связанное с конкретным PGresult; используйте функцию PQerrorMessage когда необходимо узнать статус последней операции, выполненной в данном соединении.

Возвращает переформатированную версию сообщения об ошибке, связанного с зашифрованное PGresult объект.

char *PQresultVerboseErrorMessage(const PGresult *res,
                                  PGVerbosity verbosity,
                                  PGContextVisibility show_context);

В определенных ситуациях клиенту может потребоваться более подробная версия ранее полученного сообщения об ошибке. PQresultVerboseErrorMessage решает эту задачу посредством формирования сообщения, которое было бы создано функцией PQresultErrorMessage если бы заданные параметры детализации были применены к соединению в момент, когда конкретный PGresult был сформирован. Если параметров PGresult не содержит сведений об ошибке, «PGresult не содержит сведений об ошибке» вместо этого выводится соответствующее уведомление. Возвращаемая строка содержит в конце символ новой строки.

В отличие от большинства других функций извлечения данных из зашифрованное PGresult, результатом данной функции является заново выделенная строка. Вызывающая сторона должна освободить её с помощью функции PQfreemem() когда строка больше не требуется.

При нехватке памяти может быть возвращено значение NULL.

Возвращает отдельное поле отчета об ошибке.

char *PQresultErrorField(const PGresult *res, int fieldcode);

fieldcode представляет собой идентификатор поля ошибки; см. символы, перечисленные ниже. значение NULL возвращается в том случае, если PGresult не является результатом ошибки или предупреждения, или не содержит указанного поля. Значения полей обычно не содержат завершающего символа новой строки. Вызывающая сторона не должна освобождать этот результат напрямую. Он будет освобожден при освобождении связанного с ним объекта PGresult идентификатор будет передан функции PQclear.

Доступны следующие коды полей:

За форматирование отображаемой информации для удовлетворения своих потребностей отвечает клиент; в частности, при необходимости ему следует разбивать длинные строки. Символы новой строки, встречающиеся в полях сообщения об ошибке, следует интерпретировать как разрывы абзацев, а не как разрывы строк.

Ошибки, генерируемые компонентами libpq будет содержат уровень серьезности и основное сообщение, но обычно не имеют других полей.

Обратите внимание, что поля ошибок доступны только в PGresult объектах, а не в PGconn объекты; отсутствует PQerrorField функция.

Освобождает область памяти, связанную с PGresult. Каждый результат команды должен быть освобожден с помощью функции PQclear когда он больше не требуется.

void PQclear(PGresult *res);

Если аргумент представляет собой значение NULL указатель, никакая операция не выполняется.

Вы можете сохранять PGresult объект типа PGresult в течение необходимого времени; он не уничтожается при выполнении новой команды или даже при закрытии соединения. Чтобы удалить его, необходимо вызвать PQclear. Невыполнение этого требования приведет к возникновению в приложении утечек памяти.

Функция возвращает количество строк (кортежей) в результате запроса. (Обратите внимание, что PGresult количество строк в объектах типа PGresult не превышает значения INT_MAX , поэтому int для представления результата достаточно.)

int PQntuples(const PGresult *res);

Функция возвращает количество столбцов (полей) в каждой строке результата запроса.

int PQnfields(const PGresult *res);

Функция возвращает имя столбца, соответствующее указанному номеру столбца. Нумерация столбцов начинается с 0. Вызывающая сторона не должна освобождать результат напрямую. Она будет освобождена, когда соответствующий PGresult идентификатор будет передан функции PQclear.

char *PQfname(const PGresult *res,
              int column_number);

значение NULL возвращается, если номер столбца находится вне диапазона.

Функция возвращает номер столбца, соответствующий указанному имени столбца.

int PQfnumber(const PGresult *res,
              const char *column_name);

Если заданное имя не соответствует ни одному столбцу, возвращается -1.

Заданное имя обрабатывается так же, как идентификатор в SQL-команде, то есть он приводится к нижнему регистру, если не заключен в двойные кавычки. Например, если задан результат запроса, сформированный SQL-командой:

SELECT 1 AS FOO, 2 AS "BAR";

будут получены следующие результаты:

PQfname(res, 0)              foo
PQfname(res, 1)              BAR
PQfnumber(res, "FOO")        0
PQfnumber(res, "foo")        0
PQfnumber(res, "BAR")        -1
PQfnumber(res, "\"BAR\"")    1

Возвращает тип Oid таблицы, из которой был извлечен заданный столбец. Нумерация столбцов начинается с 0.

Oid PQftable(const PGresult *res,
             int column_number);

InvalidOid возвращается в том случае, если номер столбца выходит за пределы диапазона, или если указанный столбец не является простой ссылкой на столбец таблицы. Вы можете выполнить запрос к системной таблице, pg_class чтобы определить, на какую именно таблицу указывает ссылка.

Тип данных Oid и константа InvalidOid будут определены при включении параметров libpq заголовочного файла. Оба этих элемента будут иметь целочисленный тип.

Возвращает номер столбца (внутри соответствующей таблицы), который формирует указанный столбец результата запроса. Номера столбцов в результате запроса начинаются с 0, тогда как столбцы таблицы имеют ненулевые номера.

int PQftablecol(const PGresult *res,
                int column_number);

Если номер столбца находится вне диапазона или если, возвращается значение 0 указанный столбец не является простой ссылкой на столбец таблицы.

Возвращает код формата, указывающий на формат заданного столбца. Нумерация столбцов начинается с 0.

int PQfformat(const PGresult *res,
              int column_number);

Код формата 0 означает текстовое представление данных, в то время как код формата 1 указывает на двоичное представление. (Другие коды зарезервированы для использования в будущем.)

Возвращает связанный с заданным номером столбца тип данных. Возвращаемое целое число представляет собой внутренний номер тип Oid этого типа. Нумерация столбцов начинается с 0.

Oid PQftype(const PGresult *res,
            int column_number);

Вы можете выполнить запрос к системной таблице, pg_type для получения имен и свойств различных типов данных. Значения OIDвстроенных типов данных определены в файле catalog/pg_type_d.h в Digital Q.DataBase установки заголовочных файлов каталоге.

Возвращает модификатор типа для столбца с заданным номером. Нумерация столбцов начинается с 0.

int PQfmod(const PGresult *res,
           int column_number);

Интерпретация значений модификатора зависит от конкретного типа; обычно они указывают на ограничения точности или размера. Для обозначения используется значение -1, «когда информация отсутствует». В большинстве типов данных модификаторы не используются, и в этом случае значение всегда -1.

Возвращает размер в байтах для столбца с заданным номером. Нумерация столбцов начинается с 0.

int PQfsize(const PGresult *res,
            int column_number);

PQfsize возвращает объем памяти, выделенный для данного столбца в строке базы данных, иными словами — размер внутреннего представления типа данных на сервере. (Соответственно, этот параметр не слишком полезен для клиентских приложений.) Отрицательное значение указывает на то, что тип данных имеет переменную длину.

Функция возвращает 1, если PGresult содержит двоичные данные, и 0, если он содержит текстовые данные.

int PQbinaryTuples(const PGresult *res);

Данная функция считается устаревшей (за исключением её использования в сочетании с командой COPY), так как один PGresult может содержать текстовые данные в одних столбцах и двоичные данные в других. PQfformat является предпочтительным. PQbinaryTuples возвращает 1 только в том случае, если все столбцы результата содержат данные в двоичном формате (формат 1).

Возвращает значение одного поля одной строки PGresult. Нумерация строк и столбцов начинается с 0. Вызывающая сторона не должна освобождать память результата напрямую. Она будет освобожден, когда соответствующий PGresult дескриптор будет передан в функцию PQclear.

char *PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);

Для данных в текстовом формате значение, которое возвращает функция PQgetvalue представляет собой завершающуюся нулевым байтом символьную строку, которая является представлением значения поля. Для данных в двоичном формате значение возвращается в двоичном представлении, которое определяют относящиеся к типу данных typsend и typreceive функции. (В данном случае за значением также следует нулевой байт, но обычно это не имеет практической пользы, так как значение, вероятно, содержит встроенные нулевые байты.)

Если значение поля является значением NULL, возвращается пустая строка. См. PQgetisnull чтобы отличить значения NULL от пустых строк.

Указатель, возвращаемый функцией PQgetvalue указывает на область памяти, являющуюся частью PGresult структуры. Не следует изменять данные, на которые указывает этот указатель, и их необходимо явно скопировать в другую область памяти, если они будут использоваться после завершения времени жизни PGresult самой структуры.

Проверяет поле на наличие значения NULL. Нумерация строк и столбцов начинается с 0.

int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);

Данная функция возвращает 1, если поле содержит значение NULL, и 0, если оно содержит значение, отличное от NULL. (Обратите внимание, что функция PQgetvalue будет возвращать пустую строку, а не значение NULL, для поля со значением NULL.)

Функция возвращает фактическую длину значения поля в байтах. Нумерация строк и столбцов начинается с 0.

int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);

Данный параметр определяет фактическую длину конкретного значения данных, то есть размер объекта, на который указывает функция PQgetvalue. Для текстового формата данных это значение эквивалентно результату функции strlen(). Для двоичного формата данная информация является существенной. Обратите внимание, что следует пытаться использовать функцию PQfsize для получения фактической длины данных.

Функция возвращает количество параметров подготовленного оператора.

int PQnparams(const PGresult *res);

Данная функция полезна только при анализе результата функции PQdescribePrepared. Для других типов результатов данная функция возвращает ноль.

Функция возвращает тип данных указанного параметра оператора. Нумерация параметров начинается с 0.

Oid PQparamtype(const PGresult *res, int param_number);

Данная функция полезна только при анализе результата функции PQdescribePrepared. Для других типов результатов данная функция возвращает ноль.

Функция выводит все строки и, при необходимости, имена столбцов в заданный выходной поток.

void PQprint(FILE *fout,      /* выходной поток */
             const PGresult *res,
             const PQprintOpt *po);
typedef struct
{
    pqbool  header;      /* вывод заголовков полей и количества строк */
    pqbool  align;       /* выравнивание полей */
    pqbool  standard;    /* устаревший формат */
    pqbool  html3;       /* вывод таблиц HTML */
    pqbool  expanded;    /* развертывание таблиц */
    pqbool  pager;       /* использование программы постраничного вывода при необходимости */
    char    *fieldSep;   /* разделитель полей */
    char    *tableOpt;   /* атрибуты для элемента таблицы HTML */
    char    *caption;    /* заголовок таблицы HTML */
    char    **fieldName; /* массив имен полей для замены, завершающийся значением NULL */
} PQprintOpt;

Ранее эта функция использовалась программой psql для вывода результатов запроса, однако в настоящее время она для этого не применяется. Обратите внимание, что все данные должны быть представлены в текстовом формате.

Функция возвращает тег статуса команды SQL, в результате выполнения которой был создан параметров PGresult.

char *PQcmdStatus(PGresult *res);

Обычно возвращается только имя команды, но оно может включать в себя дополнительные данные, такие как количество обработанных строк. Вызывающая сторона не должна освобождать результат напрямую. Он будет освобожден при освобождении связанного с ним объекта PGresult идентификатор будет передан функции PQclear.

Возвращает количество строк, затронутых SQL-командой.

char *PQcmdTuples(PGresult *res);

Данная функция возвращает строку, содержащую количество строк, затронутых SQL инструкцией, сгенерировавшей PGresult. Данную функцию можно использовать только после выполнения инструкции SELECT, CREATE TABLE AS, INSERT, UPDATE, DELETE, MERGE, MOVE, FETCH, или COPY или инструкции EXECUTE для подготовленного запроса, содержащего INSERT, UPDATE, DELETE, или MERGE оператор. Если команда, сгенерировавшая PGresult была чем-то иным, PQcmdTuples возвращается пустая строка. Вызывающая сторона не должна освобождать возвращаемое значение напрямую. Оно будет освобождено, когда связанный PGresult идентификатор будет передан функции PQclear.

Возвращает OID вставленной строки, если SQL команда представляла собой INSERT оператор, вставивший ровно одну строку в таблицу, которая содержит типы Oid, или EXECUTE подготовленного запроса, содержащего соответствующий INSERT оператор. В противном случае данная функция возвращает значение InvalidOid. Данная функция также возвращает значение InvalidOid в том случае, если затронутая оператором INSERT таблица не содержит идентификаторов типа Oid.

Oid PQoidValue(const PGresult *res);

Данная функция признана устаревшей в пользу функции PQoidValue и не является потокобезопасной. Она возвращает строку, содержащую идентификатор типа Oid вставленной строки, тогда как функция PQoidValue возвращает само значение типа Oid.

char *PQoidStatus(const PGresult *res);

char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);

PQescapeLiteral экранирует строку для использования в SQL-команде. Это полезно при вставке значений данных в SQL-команды в качестве литеральных констант. Для предотвращения специальной интерпретации SQL-парсером определённых символов (таких как кавычки и обратная косая черта) необходимо выполнять их экранирование. PQescapeLiteral выполняет эту операцию.

PQescapeLiteral возвращает экранированную версию параметра str в памяти, выделенной с помощью функции malloc(). Данную память следует освободить с помощью функции PQfreemem() , когда результат больше не требуется. Завершающий нулевой байт не является обязательным и не должен учитываться в параметре length. (Если до указанного предела будет обнаружен завершающий нулевой байт length байт, PQescapeLiteral работа функции останавливается на нуле; таким образом, поведение во многом аналогично strncpy.) В возвращаемой строке все специальные символы заменяются так, чтобы они могли быть правильно обработаны Digital Q.DataBase парсером строковых литералов. Также добавляется завершающий нулевой байт. Одинарные кавычки, которыми должны быть окружены Digital Q.DataBase строковые литералы, включаются в результирующую строку.

В случае возникновения ошибки PQescapeLiteral возвращает значение NULL соответствующее сообщение сохраняется в объект conn объекте conn.

Следует отметить, что выполнять экранирование не нужно и неправильно, когда значение данных передается как отдельный параметр в функцию PQexecParams или в родственные ей функции.

char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);

PQescapeIdentifier выполняет экранирование строки для использования в качестве SQL-идентификатора, например, имени таблицы, столбца или функции. Это полезно, когда предоставленный пользователем идентификатор может содержать специальные символы, которые иначе не были бы восприняты парсером SQL как часть идентификатора, или когда идентификатор может содержать символы в верхнем регистре, регистр которых необходимо сохранить.

PQescapeIdentifier возвращает версию str параметра, экранированную как SQL-идентификатор, в памяти, выделенной с помощью функции malloc(). Данную память необходимо освободить с помощью функции PQfreemem() , когда результат больше не требуется. Завершающий нулевой байт не требуется и не должен учитываться в параметре length. (Если до указанного предела будет обнаружен завершающий нулевой байт length байт, PQescapeIdentifier работа функции останавливается на нуле; таким образом, поведение во многом аналогично strncpy.) В возвращаемой строке все специальные символы заменяются для её корректной обработки в качестве SQL-идентификатора. Также добавляется завершающий нулевой байт. Кроме того, возвращаемая строка заключается в двойные кавычки.

В случае возникновения ошибки PQescapeIdentifier возвращает значение NULL соответствующее сообщение сохраняется в объект conn объекте conn.

size_t PQescapeStringConn(PGconn *conn,
                          char *to, const char *from, size_t length,
                          int *error);

PQescapeStringConn экранирует строковые литералы аналогично функции PQescapeLiteral. В отличие от функции PQescapeLiteral, вызывающая сторона обязана предоставить буфер соответствующего размера. Кроме того, PQescapeStringConn не генерирует одинарные кавычки, которыми должны быть окружены Digital Q.DataBase строковые литералы; их следует указывать в SQL-команде, в которую вставляется полученный результат. Параметр from указывает на первый символ строки, которую необходимо экранировать, а length параметр задаёт количество байтов в этой строке. Завершающий нулевой байт не требуется и не должен учитываться в параметре length. (Если до указанного предела будет обнаружен завершающий нулевой байт length байт, PQescapeStringConn работа функции останавливается на нуле; таким образом, поведение во многом аналогично strncpy.) to должен указывать на буфер, размер которого позволяет вместить как минимум на один байт больше удвоенного значения length, в противном случае поведение функции не определено. Поведение также не определено, если to и from строки перекрываются.

Если параметр error не равен значение NULL, то *error устанавливается в ноль при успешном выполнении и в ненулевое значение — при возникновении ошибки. В настоящее время единственные возможные условия ошибки связаны с некорректной многобайтовой кодировкой в исходной строке. Выходная строка всё равно генерируется при ошибке, но следует ожидать, что сервер отклонит её как некорректно сформированную. В случае ошибки соответствующее сообщение сохраняется в объект conn объекте conn, независимо от того, error имеет значение NULL значение NULL.

PQescapeStringConn возвращает количество байтов, записанных в to, не включая завершающий нулевой байт.

PQescapeString является устаревшей версией функции PQescapeStringConn.

size_t PQescapeString (char *to, const char *from, size_t length);

Единственное отличие от функции PQescapeStringConn заключается в том, что PQescapeString не принимает PGconn или error параметры. Вследствие этого функция не может корректировать своё поведение в зависимости от свойств соединения (таких как кодировка символов), и поэтому она может возвращать неверные результаты. Кроме того, в ней не предусмотрена возможность сообщения об ошибках.

PQescapeString может безопасно использоваться в клиентских программах, работающих только с одним Digital Q.DataBase соединением одновременно (в этом случае она может получить необходимую информацию «автоматически»). В иных контекстах использование этой функции представляет угрозу безопасности, поэтому её следует избегать в пользу PQescapeStringConn.

Данная функция экранирует двоичные данные для использования в SQL-команде с типом bytea. Как и в случае с функцией PQescapeStringConn, этот механизм применяется только при вставке данных непосредственно в строку SQL-команды.

unsigned char *PQescapeByteaConn(PGconn *conn,
                                 const unsigned char *from,
                                 size_t from_length,
                                 size_t *to_length);

При использовании в составе bytea литерала в SQL-команде определенные значения байтов должны быть экранированы. SQL оператор. PQescapeByteaConn функция экранирует байты, используя либо шестнадцатеричное кодирование, либо экранирование обратной косой чертой. Подробности см. в разделе Раздел 2.5.4 for more information.

Параметр from Параметр from указывает на первый байт строки, подлежащей экранированию, а from_length параметр from_length задает количество байтов в данной двоичной строке. (Завершающий нулевой байт не является обязательным и не учитывается.) Данный параметр to_length указывает на переменную, в которой будет сохранена длина результирующей экранированной строки. В указанную длину результирующей строки включен завершающий нулевой байт.

PQescapeByteaConn возвращает экранированную версию from двоичной строки параметра в области памяти, выделенной функцией malloc(). Данную память следует освободить с помощью функции PQfreemem() когда результат больше не требуется. В возвращаемой строке все специальные символы заменяются для их корректной обработки Digital Q.DataBase анализатором строковых литералов и bytea функцией ввода. Кроме того, добавляется завершающий нулевой байт. Одинарные кавычки, которые должны обрамлять Digital Q.DataBase строковые литералы не входят в состав результирующей строки.

При возникновении ошибки возвращается нулевой указатель, а соответствующее сообщение об ошибке записывается в объект conn объект conn. В настоящее время единственной возможной ошибкой является нехватка памяти для формирования результирующей строки.

PQescapeBytea является устаревшей версией функции PQescapeByteaConn.

unsigned char *PQescapeBytea(const unsigned char *from,
                             size_t from_length,
                             size_t *to_length);

Единственное отличие от функции PQescapeByteaConn состоит в том, что PQescapeBytea не принимает PGconn параметр. В силу этого функция PQescapeBytea может безопасно использоваться только в клиентских приложениях, использующих в каждый момент времени одно Digital Q.DataBase соединение (в данном случае функция может получить необходимые сведения «скрыто от пользователя»). Это может привести к получению неверных результатов если используется в программах с несколькими соединениями с базой данных (в таких случаях используйте PQescapeByteaConn в подобных ситуациях).

Преобразует строковое представление двоичных данных в двоичные данные — операция, обратная PQescapeBytea. Это требуется при получении bytea данных в текстовом формате, но не при их получении в двоичном формате.

unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);

Параметр from параметр указывает на строку которая может быть возвращена функцией PQgetvalue при применении к bytea столбцу. PQunescapeBytea преобразует данное строковое представление в двоичную форму. Она возвращает указатель на буфер, выделенный функцией malloc(), или значение NULL при возникновении ошибки и записывает размер буфера в параметр to_length. Полученный результат должен быть освобождён с помощью функции PQfreemem после того, как он перестанет быть необходимым.

Данное преобразование не является в точности обратным функции PQescapeBytea, так как не предполагается, что строка должна быть предварительно «экранирована» при получении из PQgetvalue. В частности, это означает отсутствие необходимости учитывать правила экранирования строк кавычками, вследствие чего отпадает необходимость в PGconn параметре.