文件首頁
MySQL 9.0 C API 開發者指南
下載本手冊
PDF (美式信紙) - 1.4Mb
PDF (A4) - 1.4Mb

5.4.58 mysql_real_connect()

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_real_connect_nonblocking()，供需要與伺服器進行非同步通訊的應用程式使用。請參閱 第 7 章，C API 非同步介面。

若要使用 DNS SRV 記錄連線，請使用 mysql_real_connect_dns_srv()。請參閱 第 5.4.59 節，「mysql_real_connect_dns_srv()」。

mysql_real_connect() 嘗試建立與執行於 host 上的 MySQL 伺服器的連線。用戶端程式必須先成功連線至伺服器，才能執行任何其他需要有效 MYSQL 連線處理常式結構的 API 函式。

請依下列方式指定引數

  • 對於第一個引數，請指定現有 MYSQL 結構的位址。在呼叫 mysql_real_connect() 之前，請呼叫 mysql_init() 來初始化 MYSQL 結構。您可以使用 mysql_options() 呼叫來變更許多連線選項。請參閱 第 5.4.54 節，「mysql_options()」。

  • host 的值可以是主機名稱或 IP 位址。用戶端會嘗試依下列方式連線

    • 如果 host 是 NULL 或字串 "localhost"，則會假設連線至本機主機

      • 在 Windows 上，如果伺服器已啟用共用記憶體連線，用戶端會使用共用記憶體連線。

      • 在 Unix 上，用戶端會使用 Unix socket 檔案連線。unix_socket 引數或 MYSQL_UNIX_PORT 環境變數可用於指定 socket 名稱。

    • 在 Windows 上，如果 host 是 "."，或未啟用 TCP/IP 且未指定 unix_socket 或主機為空白，如果伺服器已啟用具名管道連線，用戶端會使用具名管道連線。如果未啟用具名管道連線，則會發生錯誤。

    • 否則，將使用 TCP/IP。

    您也可以使用 mysql_options() 的 MYSQL_OPT_PROTOCOL 或 MYSQL_OPT_NAMED_PIPE 選項來影響要使用的連線類型。伺服器必須支援連線類型。

  • user 引數包含使用者的 MySQL 登入 ID。如果 user 是 NULL 或空字串 ""，則會假設為目前使用者。在 Unix 下，這是目前的登入名稱。在 Windows ODBC 下，必須明確指定目前的使用者名稱。請參閱 連接器和 API 的 Connector/ODBC 章節。

  • passwd 引數包含 user 的密碼。如果 passwd 是 NULL，則只會檢查使用者表格中具有空白（空）密碼欄位的使用者條目是否符合。這可讓資料庫管理員設定 MySQL 權限系統，讓使用者根據是否指定密碼而取得不同的權限。

    注意

    在呼叫 mysql_real_connect() 之前，請勿嘗試加密密碼；用戶端 API 會自動處理密碼加密。

  • user 和 passwd 引數會使用為 MYSQL 物件設定的任何字元集。預設值為 utf8mb4，但可以透過在連線之前呼叫 mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "charset_name") 來變更。

  • db 是資料庫名稱。如果 db 不是 NULL，連線會將預設資料庫設定為此值。

  • 如果 port 不是 0，則該值會用作 TCP/IP 連線的連接埠號碼。請注意，host 引數會決定連線的類型。

  • 如果 unix_socket 不是 NULL，則字串會指定要使用的 socket 或具名管道。請注意，host 引數會決定連線的類型。

  • client_flag 的值通常為 0，但可以設定為下列旗標的組合以啟用某些功能

    • CAN_HANDLE_EXPIRED_PASSWORDS：用戶端可以處理過期的密碼。如需詳細資訊，請參閱 伺服器處理過期密碼。

    • CLIENT_COMPRESS：在用戶端/伺服器協定中使用壓縮。

    • CLIENT_FOUND_ROWS：傳回找到（符合）的列數，而不是變更的列數。

    • CLIENT_IGNORE_SIGPIPE：防止用戶端程式庫安裝 SIGPIPE 訊號處理常式。這可用於避免與應用程式已安裝的處理常式發生衝突。

    • CLIENT_IGNORE_SPACE：允許在函式名稱後方加上空格。讓所有函式名稱成為保留字。

    • CLIENT_INTERACTIVE：允許 interactive_timeout 秒的不活動時間（而不是 wait_timeout 秒），然後關閉連線。用戶端的連線 wait_timeout 變數會設定為連線 interactive_timeout 變數的值。

    • CLIENT_LOCAL_FILES：啟用 LOAD DATA LOCAL 處理。

    • CLIENT_MULTI_RESULTS：告訴伺服器，用戶端可以處理來自多個語句執行或預存程序的結果集。如果已啟用 CLIENT_MULTI_STATEMENTS，則會自動啟用此旗標。請參閱此表格後方的附註，以取得關於此旗標的詳細資訊。

    • CLIENT_MULTI_STATEMENTS：告訴伺服器，用戶端可以在單一字串中傳送多個語句（以 ; 字元分隔）。如果未設定此旗標，則會停用多語句執行。請參閱此表格後方的附註，以取得關於此旗標的詳細資訊。

    • CLIENT_NO_SCHEMA：不允許 db_name.tbl_name.col_name 語法。這是針對 ODBC。如果您使用該語法，它會使剖析器產生錯誤，這對於捕捉某些 ODBC 程式中的錯誤很有用。

      從 MySQL 8.0.32 開始，CLIENT_NO_SCHEMA 旗標已棄用。用戶端程式可以省略此旗標和 db 引數，讓連線將資料庫值設定為目前（或預設）資料庫。

    • CLIENT_ODBC：未使用。

    • CLIENT_OPTIONAL_RESULTSET_METADATA：此旗標使結果集元數據成為可選。抑制元數據傳輸可以提高效能，特別是對於執行許多返回少量列的查詢的會期而言。有關管理結果集元數據傳輸的詳細資訊，請參閱第 3.6.7 節，「可選結果集元數據」。

    • CLIENT_SSL：使用 SSL（加密協定）。請勿在應用程式程式碼中設定此選項；它會在用戶端程式庫中內部設定。請改為在呼叫mysql_real_connect()之前使用mysql_options()。

    • CLIENT_REMEMBER_OPTIONS：記住對mysql_options()的呼叫所指定的選項。若沒有此選項，如果mysql_real_connect()失敗，您必須在再次嘗試連線之前重複mysql_options()的呼叫。使用此選項，則無需重複mysql_options()的呼叫。

如果您的程式使用CALL陳述式來執行預存程序，則必須啟用CLIENT_MULTI_RESULTS旗標。這是因為每個CALL都會返回一個結果來指示呼叫狀態，此外還有程序中執行的陳述式可能返回的任何結果集。由於CALL可以返回多個結果，請使用呼叫mysql_next_result()的迴圈來處理它們，以確定是否有更多結果。

當您呼叫mysql_real_connect()時，可以啟用CLIENT_MULTI_RESULTS，方法是顯式傳遞CLIENT_MULTI_RESULTS旗標本身，或是隱式傳遞CLIENT_MULTI_STATEMENTS（也會啟用CLIENT_MULTI_RESULTS）。預設情況下會啟用CLIENT_MULTI_RESULTS。

如果您啟用CLIENT_MULTI_STATEMENTS或CLIENT_MULTI_RESULTS，請使用呼叫mysql_next_result()的迴圈來處理每次呼叫mysql_real_query()或mysql_query()的結果，以判斷是否有更多結果。如需範例，請參閱第 3.6.3 節，「多重陳述式執行支援」。

對於某些引數，可以從選項檔案中取得值，而不是從mysql_real_connect()呼叫中的顯式值中取得。若要執行此操作，請在呼叫mysql_real_connect()之前，使用MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP選項呼叫mysql_options()。然後，在mysql_real_connect()呼叫中，為每個要從選項檔案讀取的引數指定「no-value」值

  • 對於host，請指定值為NULL或空字串（""）。

  • 對於user，請指定值為NULL或空字串。

  • 對於passwd，請指定值為NULL。（對於密碼，mysql_real_connect()呼叫中的空字串值無法在選項檔案中覆寫，因為空字串明確指出 MySQL 帳戶必須具有空密碼。）

  • 對於db，請指定值為NULL或空字串。

  • 對於port，請指定值為 0。

  • 對於unix_socket，請指定值為NULL。

如果在選項檔案中找不到引數的值，則會使用本節先前描述中指示的預設值。

傳回值

如果連線成功，則為 MYSQL* 連線處理常式；如果連線不成功，則為 NULL。對於成功的連線，傳回值與第一個引數的值相同。

錯誤

範例

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 用戶端程式庫會讀取 [client] 和 [your_prog_name] 區段中的 my.cnf 檔案。這讓您可以在 [your_prog_name] 區段中新增選項，以確保您的程式可以運作，即使有人以非標準方式設定 MySQL 也是如此。


上一個   首頁   上一層   下一個
下載本手冊
PDF (美式信紙) - 1.4Mb
PDF (A4) - 1.4Mb