5.4.55 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().