5.4.60 mysql_real_escape_string()

unsigned long
mysql_real_escape_string(MYSQL *mysql,
                         char *to,
                         const char *from,
                         unsigned long length)

Описание

Эта функция создает корректную строку SQL для использования в операторе SQL. См. .

Примечание

mysql_real_escape_string() завершается ошибкой, если включен режим SQL. В этом случае функция не может экранировать символы кавычек, кроме как дублированием, и для правильного выполнения этого ей требуется больше информации о контексте кавычек, чем доступно. Вместо этого используйте mysql_real_escape_string_quote(), который принимает дополнительный аргумент для указания контекста кавычек.

Аргумент mysql должен быть валидным открытым соединением, так как экранирование символов зависит от используемой на сервере кодовой страницы.

Строка в аргументе from кодируется для создания экранированной строки SQL с учётом текущей кодовой страницы соединения. Результат помещается в аргумент to, за которым следует завершающий нулевой символ.

Экранируются символы \, ', ", NUL (ASCII 0), \n, \r и Control+Z. Строго говоря, MySQL требует экранирования только обратной косой черты и символа кавычек, используемого для кавычек в запросе. mysql_real_escape_string() экранирует и другие символы, чтобы упростить чтение в файлах журнала. Для сравнения см. правила цитирования строковых литералов и функцию SQL в , и .

Строка, на которую указывает from, должна иметь длину length байт. Буфер to должен быть выделен как минимум на length*2+1 байт. (В худшем случае каждый символ может потребовать кодировки в два байта, и должно быть место для завершающего нулевого символа.) Когда mysql_real_escape_string() возвращает значение, содержимое to является строкой с завершающим нулевым символом. Возвращаемое значение — длина закодированной строки, не включая завершающий нулевой символ.

Если вам нужно изменить кодовую страницу соединения, используйте функцию mysql_set_character_set(), а не выполнение оператора (или ). mysql_set_character_set() работает так же, как , но также влияет на кодовую страницу, используемую mysql_real_escape_string(), что не делает.

Пример

Следующий пример вставляет две экранированные строки в оператор INSERT, каждая из которых заключена в одинарные кавычки:

char query[1000],*end;

end = my_stpcpy(query,"INSERT INTO test_table VALUES('");
end += mysql_real_escape_string(&mysql,end,"What is this",12);
end = my_stpcpy(end,"','");
end += mysql_real_escape_string(&mysql,end,"binary data: \0\r\n",16);
end = my_stpcpy(end,"')");

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&mysql));
}

Функция my_stpcpy(), использованная в примере, включена в библиотеку libmysqlclient и работает как strcpy(), но возвращает указатель на завершающий нулевой символ первого параметра.

Значения возврата

Длина закодированной строки, помещенной в аргумент to, без учета завершающего нулевого символа, или -1 в случае ошибки.

Поскольку mysql_real_escape_string() возвращает беззнаковое значение, вы можете проверить -1, сравнив возвращаемое значение с (unsigned long)-1 (или с (unsigned long)~0, что эквивалентно).

Ошибки

Возникает ошибка, если включен режим SQL, поскольку в этом случае mysql_real_escape_string() не может гарантировать правильный кодированный результат. Чтобы избежать этой ошибки, используйте mysql_real_escape_string_quote() вместо этого.