9.1.3.43 mysql_real_escape_string()

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

Description

This function is used to create a legal SQL string that you can use in a SQL statement. See section 6.1.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 6.1.1 Literals: How to Write Strings and Numbers). (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 will be a null-terminated string. The return value is the length of the encoded string, not including the terminating null character.

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.

User Comments

Documentation is unclear (at least to me):

> taking into account the current character
> set of the connection

What does this mean? How is mysql_real_escape_string affected by the character set?

To test the feature, I run the mysql server with default-character-set=usa7

Then I used mysql_real_escape_string on a string containing german special characters (äöüß), which should be illegal for the usa7 charset; nothing happened, i.e. mysql_real_escape_string neither removed nor changed these characters.

Thus, I experienced no change compared to mysql_escape_string.

This doesn't work when using the VC++ APIs for Win32 (and maybe also not in the BCB APIs), you get an unresolved external, even with all libs included.
Here is a solution that does the same. Buffer1 is your binary data, Buffer 2 is the data you put into the query;

char Buffer1[100]
char Buffer2[201]

for(int x = 0; x < 100; x++)
{
switch(Buffer[x])
{
case '\0':
Picture += "\\0";
break;
case '\n':
Picture += "\\n";
break;
case '\r':
Picture += "\\r";
break;
case '\'':
Picture += "\\'";
break;
case '"':
Picture += "\\\"";
break;
case '\\':
Picture += "\\\\";
break;
default:
Picture += Buffer[y];
break;
}

Errata: of course the 'Picture' should be 'Buffer2', sorry for the inconvenience.

Please add a note on how to scape the % character in strings, so that it can be later used in LIKE expressions.

It would be most useful to add a function that provides the programmer with the length returned by mysql_real_escape_string() because the *to buffer usually needs to be allocated a particular size before this function is called. If that size is unknown before the function is called a paradox exists. Simply allocating twice the memory for the *to buffer with respect to the *from buffer is unsatisfactory.

Add your own comment.