25.2.3.48. mysql_options()
int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)
描述
可用於設置額外的連接選項，並影響連接的行爲。可多次調用該函數來設置數個選項。
應在mysql_init()之後、以及mysql_connect()或mysql_real_connect()之前調用mysql_options()。
選項參量指的是你打算設置的選項。Arg參量是選項的值。如果選項是整數，那麼arg應指向整數的值。
可能的選項值：
|
選項 |
參量類型 |
功能 |
|
MYSQL_INIT_COMMAND |
char * |
連接到MySQL服務器時將執行的命令。再次連接時將自動地再次執行。 |
|
MYSQL_OPT_COMPRESS |
未使用 |
使用壓縮客戶端／服務器協議 |
|
MYSQL_OPT_CONNECT_TIMEOUT |
unsigned int * |
以秒爲單位的連接超時。 |
|
MYSQL_OPT_GUESS_CONNECTION |
未使用 |
對於與libmysqld鏈接的應用程序，允許庫“猜測”是否使用嵌入式服務器或遠程服務器。“猜測”表示，如果設置了主機名但不是本地主機，將使用遠程服務器。該行爲是默認行爲。 可使用MYSQL_OPT_USE_EMBEDDED_CONNECTION和MYSQL_OPT_USE_REMOTE_CONNECTION覆蓋它。對於與libmysqlclient鏈接的應用程序，該選項將被忽略。 |
|
MYSQL_OPT_LOCAL_INFILE |
指向單元的可選指針 |
如果未給定指針，或指針指向“unsigned int != 0”，將允許命令LOAD LOCAL INFILE。 |
|
MYSQL_OPT_NAMED_PIPE |
未使用 |
使用命名管道連接到NT平臺上的MySQL服務器。 |
|
MYSQL_OPT_PROTOCOL |
unsigned int * |
要使用的協議類型。應是mysql.h中定義的mysql_protocol_type的枚舉值之一。 |
|
MYSQL_OPT_READ_TIMEOUT |
unsigned int * |
從服務器讀取信息的超時（目前僅在Windows平臺的TCP/IP連接上有效）。 |
|
MYSQL_OPT_RECONNECT |
my_bool * |
如果發現連接丟失，啓動或禁止與服務器的自動再連接。從MySQL 5.0.3開始，默認情況下禁止再連接，這是5.0.13中的新選項，提供了一種以顯式方式設置再連接行爲的方法。 |
|
MYSQL_OPT_SET_CLIENT_IP |
char * |
對於與libmysqld鏈接的應用程序（具備鑑定支持特性的已編譯libmysqld），它意味着，出於鑑定目的，用戶將被視爲從指定的IP地址（指定爲字符串）進行連接。對於與libmysqlclient鏈接的應用程序，，該選項將被忽略。 |
|
MYSQL_OPT_USE_EMBEDDED_CONNECTION |
未使用 |
對於與libmysqld鏈接的應用程序，對於連接來說，它將強制使用嵌入式服務器。對於與libmysqlclient鏈接的應用程序，，該選項將被忽略。 |
|
MYSQL_OPT_USE_REMOTE_CONNECTION |
未使用 |
對於與libmysqld鏈接的應用程序，對於連接來說，它將強制使用遠程服務器。對於與libmysqlclient鏈接的應用程序，，該選項將被忽略。 |
|
MYSQL_OPT_USE_RESULT |
未使用 |
不使用該選項。 |
|
MYSQL_OPT_WRITE_TIMEOUT |
unsigned int * |
寫入服務器的超時（目前僅在Windows平臺的TCP/IP連接上有效）。 |
|
MYSQL_READ_DEFAULT_FILE |
char * |
從命名選項文件而不是從my.cnf讀取選項。 |
|
MYSQL_READ_DEFAULT_GROUP |
char * |
從my.cnf或用MYSQL_READ_DEFAULT_FILE指定的文件中的命名組讀取選項。 |
|
MYSQL_REPORT_DATA_TRUNCATION |
my_bool * |
通過MYSQL_BIND.error，對於預處理語句，允許或禁止通報數據截斷錯誤（默認爲禁止）。 |
|
MYSQL_SECURE_AUTH |
my_bool* |
是否連接到不支持密碼混編功能的服務器，在MySQL 4.1.1和更高版本中，使用了密碼混編功能。 |
|
MYSQL_SET_CHARSET_DIR |
char* |
指向包含字符集定義文件的目錄的路徑名。 |
|
MYSQL_SET_CHARSET_NAME |
char* |
用作默認字符集的字符集的名稱。 |
|
MYSQL_SHARED_MEMORY_BASE_NAME |
char* |
命名爲與服務器進行通信的共享內存對象。應與你打算連接的mysqld服務器使用的選項“-shared-memory-base-name”相同。 |
注意，如果使用了MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP，總會讀取客戶端組。
選項文件中指定的組可能包含下述選項：
|
選項 |
描述 |
|
connect-timeout |
以秒爲單位的連接超時。在Linux平臺上，該超時也用作等待服務器首次迴應的時間。 |
|
compress |
使用壓縮客戶端／服務器協議。 |
|
database |
如果在連接命令中未指定數據庫，連接到該數據庫。 |
|
debug |
調試選項。 |
|
disable-local-infile |
禁止使用LOAD DATA LOCAL。 |
|
host |
默認主機名。 |
|
init-command |
連接到MySQL服務器時將執行的命令。再次連接時將自動地再次執行。 |
|
interactive-timeout |
等同於將CLIENT_INTERACTIVE指定爲mysql_real_connect()。請參見25.2.3.51節，“mysql_real_connect()”。 |
|
local-infile[=(0|1)] |
如果無參量或參量!= 0，那麼將允許使用LOAD DATA LOCAL。 |
|
max_allowed_packet |
客戶端能夠從服務器讀取的最大信息包。 |
|
multi-results |
允許多語句執行或存儲程序的多個結果集。 |
|
multi-statements |
允許客戶端在1個字符串內發送多條語句。（由“;”隔開）。 |
|
password |
默認密碼。 |
|
pipe |
使用命名管道連接到NT平臺上的MySQL服務器。 |
|
protocol={TCP | SOCKET | PIPE | MEMORY} |
連接到服務器時將使用的協議。 |
|
port |
默認端口號。 |
|
return-found-rows |
通知mysql_info()返回發現的行，而不是使用UPDATE時更新的行。 |
|
shared-memory-base-name=name |
共享內存名稱，用於連接到服務器（默認爲"MYSQL"）。 |
|
socket |
默認的套接字文件。 |
|
user |
默認用戶。 |
注意，“timeout”（超時）已被“connect-timeout”（連接超時）取代，但爲了保持向後兼容，在MySQL 5.1.2-alpha中仍支持“timeout”（超時）。
關於選項文件的更多信息，請參見4.3.2節，“使用選項文件”。
返回值
成功時返回0。如果使用了未知選項，返回非0值。
示例：
MYSQL mysql;
mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
fprintf(stderr, "Failed to connect to database: Error: %s\n",
mysql_error(&mysql));
}
該代碼請求客戶端使用壓縮客戶端／服務器協議，並從my.cnf文件的obdc部分讀取額外選項。
int mysql_ping(MYSQL *mysql)
描述
檢查與服務器的連接是否工作。如果連接丟失，將自動嘗試再連接。
該函數可被閒置了較長時間的客戶端使用，用以檢查服務器是否已關閉了連接，並在必要時再次連接。
返回值
如果與服務器的連接有效返回0。如果出現錯誤，返回非0值。返回的非0值不表示MySQL服務器本身是否已關閉，連接可能因其他原因終端，如網絡問題等。
錯誤
· CR_COMMANDS_OUT_OF_SYNC
以不恰當的順序執行了命令。
· CR_SERVER_GONE_ERROR
MySQL服務器不可用。
· CR_UNKNOWN_ERROR
出現未知錯誤。
int mysql_query(MYSQL *mysql, const char *query)
描述
執行由“Null終結的字符串”查詢指向的SQL查詢。正常情況下，字符串必須包含1條SQL語句，而且不應爲語句添加終結分號（‘;’）或“\g”。如果允許多語句執行，字符串可包含多條由分號隔開的語句。請參見25.2.9節，“多查詢執行的C API處理”。
mysql_query()不能用於包含二進制數據的查詢，應使用mysql_real_query()取而代之（二進制數據可能包含字符‘\0’，mysql_query()會將該字符解釋爲查詢字符串結束）。
如果希望瞭解查詢是否應返回結果集，可使用mysql_field_count()進行檢查。請參見25.2.3.22節，“mysql_field_count()”。
返回值
如果查詢成功，返回0。如果出現錯誤，返回非0值。
錯誤
· CR_COMMANDS_OUT_OF_SYNC
以不恰當的順序執行了命令。
· CR_SERVER_GONE_ERROR
MySQL服務器不可用。
· CR_SERVER_LOST
在查詢過程中，與服務器的連接丟失。
· CR_UNKNOWN_ERROR
出現未知錯誤。
MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)
描述
mysql_real_connect()嘗試與運行在主機上的MySQL數據庫引擎建立連接。在你能夠執行需要有效MySQL連接句柄結構的任何其他API函數之前，mysql_real_connect()必須成功完成。
參數的指定方式如下：
· 第1個參數應是已有MYSQL結構的地址。調用mysql_real_connect()之前，必須調用mysql_init()來初始化MYSQL結構。通過mysql_options()調用，可更改多種連接選項。請參見25.2.3.48節，“mysql_options()”。
· “host”的值必須是主機名或IP地址。如果“host”是NULL或字符串"localhost"，連接將被視爲與本地主機的連接。如果操作系統支持套接字（Unix）或命名管道（Windows），將使用它們而不是TCP/IP連接到服務器。
· “user”參數包含用戶的MySQL登錄ID。如果“user”是NULL或空字符串""，用戶將被視爲當前用戶。在UNIX環境下，它是當前的登錄名。在Windows ODBC下，必須明確指定當前用戶名。請參見26.1.9.2節，“在Windows上配置MyODBC DSN”。
· “passwd”參數包含用戶的密碼。如果“passwd”是NULL，僅會對該用戶的（擁有1個空密碼字段的）用戶表中的條目進行匹配檢查。這樣，數據庫管理員就能按特定的方式設置MySQL權限系統，根據用戶是否擁有指定的密碼，用戶將獲得不同的權限。
註釋：調用mysql_real_connect()之前，不要嘗試加密密碼，密碼加密將由客戶端API自動處理。
· “db”是數據庫名稱。如果db爲NULL，連接會將默認的數據庫設爲該值。
· 如果“port”不是0，其值將用作TCP/IP連接的端口號。注意，“host”參數決定了連接的類型。
· 如果unix_socket不是NULL，該字符串描述了應使用的套接字或命名管道。注意，“host”參數決定了連接的類型。
· client_flag的值通常爲0，但是，也能將其設置爲下述標誌的組合，以允許特定功能：
|
標誌名稱 |
標誌描述 |
|
CLIENT_COMPRESS |
使用壓縮協議。 |
|
CLIENT_FOUND_ROWS |
返回發現的行數（匹配的），而不是受影響的行數。 |
|
CLIENT_IGNORE_SPACE |
允許在函數名後使用空格。使所有的函數名成爲保留字。 |
|
CLIENT_INTERACTIVE |
關閉連接之前，允許interactive_timeout（取代了wait_timeout）秒的不活動時間。客戶端的會話wait_timeout變量被設爲會話interactive_timeout變量的值。 |
|
CLIENT_LOCAL_FILES |
允許LOAD DATA LOCAL處理功能。 |
|
CLIENT_MULTI_STATEMENTS |
通知服務器，客戶端可能在單個字符串內發送多條語句（由‘;’隔開）。如果未設置該標誌，將禁止多語句執行。 |
|
CLIENT_MULTI_RESULTS |
通知服務器，客戶端能夠處理來自多語句執行或存儲程序的多個結果集。如果設置了CLIENT_MULTI_STATEMENTS，將自動設置它。 |
|
CLIENT_NO_SCHEMA |
禁止db_name.tbl_name.col_name語法。它用於ODBC。如果使用了該語法，它會使分析程序生成錯誤，在捕獲某些ODBC程序中的缺陷時，它很有用。 |
|
CLIENT_ODBC |
客戶端是ODBC客戶端。它將mysqld變得更爲ODBC友好。 |
|
CLIENT_SSL |
使用SSL（加密協議）。該選項不應由應用程序設置，它是在客戶端庫內部設置的。 |
對於某些參數，能夠從選項文件獲得取值，而不是取得mysql_real_connect()調用中的確切值。爲此，在調用mysql_real_connect()之前，應與MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP選項一起調用mysql_options()。隨後，在mysql_real_connect()調用中，爲準備從選項文件讀取值的每個參數指定“無值”值：
· 對於host，指定NULL值或空字符串("")。
· 對於user，指定NULL值或空字符串。
· 對於passwd，指定NULL值。（對於密碼，mysql_real_connect()調用中的空字符串的值不能被選項文件中的字符串覆蓋，這是因爲，空字符串明確指明MySQL賬戶必須有空密碼）。
· 對於db，指定NULL值或空字符串
· 對於port，指定“0”值。
· 對於unix_socket，指定NULL值。
對於某一參數，如果在選項文件中未發現值，將使用它的默認值，如本節前面介紹的那樣。
返回值
如果連接成功，返回MYSQL*連接句柄。如果連接失敗，返回NULL。對於成功的連接，返回值與第1個參數的值相同。
錯誤
· CR_CONN_HOST_ERROR
無法連接到MySQL服務器。
· CR_CONNECTION_ERROR
無法連接到本地MySQL服務器。
· CR_IPSOCK_ERROR
無法創建IP套接字。
· CR_OUT_OF_MEMORY
內存溢出。
· CR_SOCKET_CREATE_ERROR
無法創建Unix套接字。
· CR_UNKNOWN_HOST
無法找到主機名的IP地址。
· CR_VERSION_ERROR
協議不匹配，起因於：試圖連接到具有特定客戶端庫（該客戶端庫使用了不同的協議版本）的服務器。如果使用很早的客戶端庫來建立與較新的服務器（未使用“--old-protocol”選項開始的）的連接，就會出現該情況。
· CR_NAMEDPIPEOPEN_ERROR
無法在Windows平臺下創建命名管道。
· CR_NAMEDPIPEWAIT_ERROR
在Windows平臺下等待命名管道失敗。
· CR_NAMEDPIPESETSTATE_ERROR
在Windows平臺下獲取管道處理程序失敗。
· CR_SERVER_LOST
如果connect_timeout > 0，而且在連接服務器時所用時間長於connect_timeout秒，或在執行init-command時服務器消失。
示例：
MYSQL mysql;
mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
fprintf(stderr, "Failed to connect to database: Error: %s\n",
mysql_error(&mysql));
}
通過使用mysql_options()，MySQL庫將讀取my.cnf文件的[client]和[your_prog_name]部分，以確保程序工作，即使某人以某種非標準的方式設置MySQL也同樣。
注意，一旦建立了連接，mysql_real_connect()將設置再連接標誌（MYSQL結構的組成部份）的值，在低於5.0.3版的API中，將其設爲“1”，在較新的版本中，將其設爲“0”。對於該標誌，值“1”表示，如果因連接丟失而無法執行語句，放棄前，將嘗試再次連接到服務器。從MySQL 5.0.13開始，可以對mysql_options()使用MYSQL_OPT_RECONNECT選項，對再連接行爲進行控制。
unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)
注意，mysql必須是有效的開放式連接。之所以需要它是因爲，轉義功能取決於服務器使用的字符集。
描述
該函數用於創建可在SQL語句中使用的合法SQL字符串。請參見9.1.1節，“字符串”。
按照連接的當前字符集，將“from”中的字符串編碼爲轉義SQL字符串。將結果置於“to”中，並添加1個終結用NULL字節。編碼的字符爲NUL (ASCII 0)、‘\n’、‘\r’、‘\’、‘'’、‘"’、以及Control-Z（請參見9.1節，“文字值”）。（嚴格地講，MySQL僅需要反斜槓和引號字符，用於引用轉義查詢中的字符串。該函數能引用其他字符，從而使得它們在日誌文件中具有更好的可讀性）。
“from”指向的字符串必須是長度字節“long”。必須爲“to”緩衝區分配至少length*2+1字節。在最壞的情況下，每個字符或許需要使用2個字節進行編碼，而且還需要終結Null字節。當mysql_real_escape_string()返回時，“to”的內容是由Null終結的字符串。返回值是編碼字符串的長度，不包括終結用Null字符。
如果需要更改連接的字符集，應使用mysql_set_character_set()函數，而不是執行SET NAMES (或SET CHARACTER SET)語句。mysql_set_character_set()的工作方式類似於SET NAMES，但它還能影響mysql_real_escape_string()所使用的字符集，而SET NAMES則不能。
示例：
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));
}
該示例中使用的strmov()函數包含在mysqlclient庫中，工作方式與strcpy()類似，但會返回指向第1個參數終結用Null的指針。
返回值
置於“to”中的值的長度，不包括終結用Null字符。
錯誤
無。
int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length)
描述
執行由“query”指向的SQL查詢，它應是字符串長度字節“long”。正常情況下，字符串必須包含1條SQL語句，而且不應爲語句添加終結分號（‘;’）或“\g”。如果允許多語句執行，字符串可包含由分號隔開的多條語句。請參見25.2.9節，“多查詢執行的C API處理”。
對於包含二進制數據的查詢，必須使用mysql_real_query()而不是mysql_query()，這是因爲，二進制數據可能會包含‘\0’字符。此外，mysql_real_query()比mysql_query()快，這是因爲它不會在查詢字符串上調用strlen()。
如果希望知道查詢是否應返回結果集，可使用mysql_field_count()進行檢查25.2.3.22節，“mysql_field_count()”。
返回值
如果查詢成功，返回0。如果出現錯誤，返回非0值。
錯誤
· CR_COMMANDS_OUT_OF_SYNC
以不恰當的順序執行了命令。
· CR_SERVER_GONE_ERROR
MySQL服務器不可用。
· CR_SERVER_LOST
在查詢過程中，與服務器的連接丟失。
· CR_UNKNOWN_ERROR
出現未知錯誤。
int mysql_refresh(MYSQL *mysql, unsigned int options)
描述
該函數用於刷新表或高速緩衝，或復位複製服務器信息。連接的用戶必須具有RELOAD權限。
“options”參量是一種位掩碼，由下述值的任意組合構成。能夠以“Or”（或）方式將多個值組合在一起，用一次調用執行多項操作。
· REFRESH_GRANT
刷新授權表，與FLUSH PRIVILEGES類似。
· REFRESH_LOG
刷新日誌，與FLUSH LOGS類似。
· REFRESH_TABLES
刷新表高速緩衝，與FLUSH TABLES類似。
· REFRESH_HOSTS
刷新主機高速緩衝，與FLUSH HOSTS類似。
· REFRESH_STATUS
復位狀態變量，與FLUSH STATUS類似。
· REFRESH_THREADS
刷新線程高速緩衝。
· REFRESH_SLAVE
在從複製服務器上，復位主服務器信息，並重新啓動從服務器，與RESET SLAVE類似。
· REFRESH_MASTER
在主複製服務器上，刪除二進制日誌索引中列出的二進制日誌文件，並截短索引文件，與RESET MASTER類似。
返回值
0表示成功，非0值表示出現錯誤。
錯誤
· CR_COMMANDS_OUT_OF_SYNC
以不恰當的順序執行了命令。
· CR_SERVER_GONE_ERROR
MySQL服務器不可用。
· CR_SERVER_LOST
在查詢過程中，與服務器的連接丟失。
· CR_UNKNOWN_ERROR
出現未知錯誤。
int mysql_reload(MYSQL *mysql)
描述
請求MySQL服務器重新加載授權表。連接的用戶必須具有RELOAD權限。
該函數已過時。最好使用mysql_query()來發出SQLFLUSH PRIVILEGES語句。
返回值
0表示成功，非0值表示出現錯誤。
錯誤
· CR_COMMANDS_OUT_OF_SYNC
以不恰當的順序執行了命令。
· CR_SERVER_GONE_ERROR
MySQL服務器不可用。
· CR_SERVER_LOST
在查詢過程中，與服務器的連接丟失。
· CR_UNKNOWN_ERROR
出現未知錯誤。
my_bool mysql_rollback(MYSQL *mysql)
描述
回滾當前事務。
該函數的動作取決於completion_type系統變量的值。尤其是，如果completion_type的值爲“2”，終結事務後，服務器將執行釋放操作，並關閉客戶端連接。客戶端程序應調用mysql_close()，從客戶端一側關閉連接。
返回值
如果成功，返回0，如果出現錯誤，返回非0值。
錯誤
無。
MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)
描述
將行光標置於查詢結果集中的任意行。“offset”值是行偏移量，它應是從mysql_row_tell()或mysql_row_seek()返回的值。該值不是行編號，如果你打算按編號查找結果集中的行，請使用mysql_data_seek()。
該函數要求在結果集的結構中包含查詢的全部結果，因此，mysql_row_seek()僅應與mysql_store_result()一起使用，而不是與mysql_use_result()。
返回值
行光標的前一個值。該值可傳遞給對mysql_row_seek()的後續調用。
錯誤
無。