27.7.6.55 mysql_real_escape_string()

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

Description

此函数创建一个合法的 SQL 字符串以用于 SQL 语句。参见第 9.1.1 节“字符串 Literals”。

Note

如果启用了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和 ControlZ。严格来说，MySQL 只要求转义反斜杠和用于对查询中的字符串加引号的引号字符。 mysql_real_escape_string()引用其他字符以使它们更易于在日志文件中阅读。为了进行比较，请参见 Literals 字符串的引用规则以及第 9.1.1 节“字符串 Literals”和第 12.7 节“字符串函数和运算符”中的QUOTE() SQL 函数。

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

如果必须更改连接的字符集，请使用mysql_set_character_set()函数，而不要执行SET NAMES(或设置字符集)语句。 mysql_set_character_set()的工作方式与SET NAMES类似，但也会影响mysql_real_escape_string()使用的字符集，而SET NAMES不会。

Example

下面的示例将两个转义的字符串插入到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 的指针。

Return Values

置于to参数中的编码字符串的长度，不包括终止的空字节，如果发生错误，则为-1.

因为mysql_real_escape_string()返回无符号值，所以您可以通过将返回值与(unsigned long)-1(或与(unsigned long)~0等效)进行比较来检查-1.

Errors

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

首页