5.4.56 mysql_real_escape_string_quote()

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

Описание

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

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

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

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

Примечание

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

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

Аргумент quote указывает контекст, в котором должна быть размещена экранированная строка. Предположим, что вы хотите экранировать аргумент from и вставить экранированную строку (обозначенную здесь как str) в один из следующих операторов:

1) SELECT * FROM table WHERE name = 'str'
2) SELECT * FROM table WHERE name = "str"
3) SELECT * FROM `str` WHERE id = 103

Чтобы выполнить экранирование правильно для каждого оператора, вызовите mysql_real_escape_string_quote() следующим образом, где последний аргумент указывает контекст цитирования:

1) len = mysql_real_escape_string_quote(&mysql,to,from,from_len,'\'');
2) len = mysql_real_escape_string_quote(&mysql,to,from,from_len,'"');
3) len = mysql_real_escape_string_quote(&mysql,to,from,from_len,'`');

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

Пример

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

char query[1000],*end;

end = my_stpcpy(query,"INSERT INTO test_table VALUES('");
end += mysql_real_escape_string_quote(&mysql,end,"What is this",12,'\'');
end = my_stpcpy(end,"','");
end += mysql_real_escape_string_quote(&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, не включая завершающий нулевой байт.

Ошибки

Нет.