MySQL :: MySQL 8.4 C API 開發者指南 :: 5.4.61 mysql_real_escape_string_quote()

版本 8.4

MySQL 8.4 C API 開發者指南 / ... / mysql_real_escape_string_quote()

5.4.61 mysql_real_escape_string_quote()

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

描述

此函式會建立一個合法的 SQL 字串，以用於 SQL 陳述式中。請參閱字串常值。

mysql 引數必須是有效的開啟連線，因為字元跳脫取決於伺服器所使用的字元集。

from 引數中的字串會經過編碼，以產生跳脫的 SQL 字串，並考量到連線的目前字元集。結果會置於 to 引數中，後面接著一個終止的 Null 位元組。

經過編碼的字元為 \、'、"、NUL (ASCII 0)、\n、\r、Control+Z 和 `。嚴格來說，MySQL 只需要跳脫反斜線和用於在查詢中引用字串的引號字元即可。mysql_real_escape_string_quote() 會引用其他字元，以方便在日誌檔案中閱讀。為了比較，請參閱常值字串的引用規則，以及QUOTE() SQL 函式（位於字串常值）和字串函式和運算子。

注意

如果已啟用 ANSI_QUOTES SQL 模式，則無法使用 mysql_real_escape_string_quote() 跳脫雙引號字元，以用於雙引號識別碼中。（此函式無法判斷是否已啟用該模式，以判斷正確的跳脫字元。）

from 所指向的字串必須是 length 個位元組長。您必須配置 to 緩衝區，使其至少為 length*2+1 個位元組長。（在最差的情況下，每個字元可能需要使用兩個位元組進行編碼，而且必須有空間容納終止的 Null 位元組。）當 mysql_real_escape_string_quote() 傳回時，to 的內容會是 Null 終止的字串。傳回值是編碼字串的長度，不包含終止的 Null 位元組。

quote 引數表示要放置跳脫字串的內容。假設您打算跳脫 from 引數，並將跳脫的字串（此處以 str 表示）插入下列陳述式之一

1) SELECT * FROM table WHERE name = 'str'
2) SELECT * FROM table WHERE name = "str"
3) SELECT * FROM `str` WHERE id = 103

若要針對每個陳述式正確執行跳脫，請如下所示呼叫 mysql_real_escape_string_quote()，其中最後一個引數表示引用的內容

1) len = mysql_real_escape_string_quote(&mysql,to,from,from_len,'\'');
2) len = mysql_real_escape_string_quote(&mysql,to,from,from_len,'"');
3) len = mysql_real_escape_string_quote(&mysql,to,from,from_len,'`');

如果您必須變更連線的字元集，請使用 mysql_set_character_set() 函式，而不是執行 SET NAMES (或 SET CHARACTER SET) 陳述式。mysql_set_character_set() 的運作方式與 SET NAMES 類似，但也會影響 mysql_real_escape_string_quote() 所使用的字元集，而 SET NAMES 則不會。

範例

下列範例會將兩個跳脫字串插入 INSERT 陳述式中，每個字串都在單引號字元內

char query[1000],*end;

end = my_stpcpy(query,"INSERT INTO test_table VALUES('");
end += mysql_real_escape_string_quote(&mysql,end,"What is this",12,'\'');
end = my_stpcpy(end,"','");
end += mysql_real_escape_string_quote(&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 引數中的編碼字串長度，不包含終止的 Null 位元組。

錯誤

無。