25.2.3.52. mysql_real_escape_string()
unsigned long mysql_real_escape_string(MYSQL *mysql,
char *to, const char *from, unsigned long length)
Note that mysql must be a valid, open
connection. This is needed because the escaping depends on the
character set in use by the server.
Description
This function is used to create a legal SQL string that you
can use in an SQL statement. See
Section 9.1.1, “Strings”.
The string in from is encoded to an escaped
SQL string, taking into account the current character set of
the connection. The result is placed in to
and a terminating null byte is appended. Characters encoded
are NUL (ASCII 0),
‘\n’,
‘\r’,
‘\’,
‘'’,
‘"’, and Control-Z (see
Section 9.1, “Literal Values”). (Strictly speaking, MySQL
requires only that backslash and the quote character used to
quote the string in the query be escaped. This function quotes
the other characters to make them easier to read in log
files.)
The string pointed to by from must be
length bytes long. You must allocate the
to buffer to be at least
length*2+1 bytes long. (In the worst case,
each character may need to be encoded as using two bytes, and
you need room for the terminating null byte.) When
mysql_real_escape_string() returns, the
contents of to is a null-terminated string.
The return value is the length of the encoded string, not
including the terminating null character.
If you need to change the character set of the connection, you
should use the mysql_set_character_set()
function rather than executing a SET NAMES
(or SET CHARACTER SET) statement.
mysql_set_character_set() works like
SET NAMES but also affects the character
set used by mysql_real_escape_string(),
which SET NAMES does not.
Example
char query[1000],*end;
end = strmov(query,"INSERT INTO test_table values(");
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"What's this",11);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16);
*end++ = '\'';
*end++ = ')';
if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
fprintf(stderr, "Failed to insert row, Error: %s\n",
mysql_error(&mysql));
}
The strmov() function used in the example
is included in the mysqlclient library and
works like strcpy() but returns a pointer
to the terminating null of the first parameter.
Return Values
The length of the value placed into to, not
including the terminating null character.
Errors
None.
