Documentation Home
MySQL 8.0 C API 开发者指南  / 第 5 章 C API 基本接口  / 5.4 C API 基本功能说明  /  5.4.60 mysql_real_escape_string()

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 模式,则会 失败并产生 CR_INSECURE_API_ERR错误。NO_BACKSLASH_ESCAPES在这种情况下,该函数无法转义引号字符,除非将它们加倍,并且要正确执行此操作,它必须了解有关引用上下文的更多信息。相反,使用 mysql_real_escape_string_quote(),它需要一个额外的参数来指定引用上下文。

参数必须是有效的mysql、开放的连接,因为字符转义取决于服务器使用的字符集。

from考虑到连接的当前字符集, 对参数中的字符串进行编码以生成转义的 SQL 字符串。结果放在to参数中,后跟一个终止空字节。

编码的字符为\, ', ", NUL(ASCII 0), \n, \r, 和 Control+Z。严格来说,MySQL 只需要对反斜杠和用于引用查询中的字符串的引号字符进行转义。 mysql_real_escape_string() 引用其他字符,使它们更容易在日志文件中阅读。为了进行比较,请参阅字符串文字字符串函数和运算符QUOTE()中的文字字符串和SQL 函数的引用规则。

指向的字符串from必须是 length字节长。您必须分配 to至少 length*2+1字节长的缓冲区。(在最坏的情况下,每个字符可能需要编码为使用两个字节,并且必须有空终止字节的空间。) mysql_real_escape_string() 返回时,内容to是一个空终止字符串。返回值是编码字符串的长度,不包括终止空字节。

如果必须更改连接的字符集,请使用mysql_set_character_set() 函数而不是执行SET NAMES(or SET CHARACTER SET) 语句。 mysql_set_character_set() 工作方式类似SET NAMES,但也会影响 所使用的字符集 mysql_real_escape_string(),而后者SET NAMES不会。

例子

以下示例将两个转义字符串插入到一个 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(),但返回指向第一个参数的终止 null 的指针。

返回值

放入 to参数中的编码字符串的长度,不包括终止空字节,如果发生错误则为 -1。

因为 mysql_real_escape_string() 返回一个无符号值,所以您可以通过将返回值与(unsigned long)-1(或与(unsigned long)~0,这是等效的)进行比较来检查是否为 -1。

错误