MySQL :: MySQL 9.0 C API 开发者指南 :: 5.4.60 mysql_real_escape_string()

版本 9.0

8.4 当前
8.0
5.7

MySQL 9.0 C API 开发者指南 / ... / 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 语句中。请参阅字符串字面量。

注意

如果启用了 NO_BACKSLASH_ESCAPES SQL 模式，则 mysql_real_escape_string() 将会失败并产生 CR_INSECURE_API_ERR 错误。在这种情况下，该函数无法转义引号字符，除非将其加倍，并且要正确执行此操作，它必须比可用信息更多地了解引号上下文。请改用 mysql_real_escape_string_quote()，它接受一个额外的参数来指定引号上下文。

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

from 参数中的字符串将被编码以生成转义后的 SQL 字符串，并考虑连接的当前字符集。结果将放置在 to 参数中，后跟一个终止空字节。

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

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

如果必须更改连接的字符集，请使用 mysql_set_character_set() 函数，而不是执行 SET NAMES（或 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()，但返回指向第一个参数的终止空字符的指针。

返回值

放置在 to 参数中的编码字符串的长度，不包括终止空字节，如果发生错误则返回 -1。

由于 mysql_real_escape_string() 返回一个无符号值，因此您可以通过将返回值与 (unsigned long)-1（或与等效的 (unsigned long)~0）进行比较来检查 -1。

错误

CR_INSECURE_API_ERR

如果启用了 NO_BACKSLASH_ESCAPES SQL 模式，则会发生此错误，因为在这种情况下，不能保证 mysql_real_escape_string() 产生正确编码的结果。为了避免此错误，请改用 mysql_real_escape_string_quote()。