頭檔案
#include<mysql.h>
函式原型
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()調用,可更改多種連線選項。
“host”的值必須是主機名或IP位址。如果“host”是NULL或字元串"localhost",連線將被視為與本地主機的連線。如果作業系統支持套接字(Unix)或命名管道(Windows),將使用它們而不是TCP/IP連線到伺服器。
“user”參數包含用戶的MySQL登錄ID。如果“user”是NULL或空字元串"",用戶將被視為當前用戶。在UNIX環境下,它是當前的登錄名。在Windows ODBC下,必須明確指定當前用戶名。
“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秒的不活動時間。 |
CLIENT_LOCAL_FILES | 允許LOAD DATA LOCAL處理功能。 |
CLIENT_MULTI_STATEMENTS | 通知伺服器,客戶端可能在單個字元串內傳送多條語句。 |
CLIENT_MULTI_RESULTS | 通知伺服器,客戶端能夠處理來自多語句執行。 |
CLIENT_NO_SCHEMA | 禁止db_name.tbl_name.col_name語法。 |
CLIENT_ODBC | 客戶端是ODBC客戶端。它將mysqld變得更為ODBC友好。 |
CLIENT_SSL | 使用SSL,該選項不應由應用程式設定,而是在客戶端庫內部設定。 |
對於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時伺服器消失。
範例
#include<stdio.h>
#include<mysql.h>
int main(){
MYSQL mysql;
mysql_init(&mysql);
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));
}
return 0;
}