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

5.4.54 mysql_options()

int
mysql_options(MYSQL *mysql,
              enum mysql_option option,
              const void *arg)

說明

可用於設定額外的連線選項並影響連線的行為。此函式可多次呼叫以設定多個選項。若要擷取選項值，請使用 mysql_get_option()。

在 mysql_init() 之後且在 mysql_connect() 或 mysql_real_connect() 之前呼叫 mysql_options()。

option 引數是您想要設定的選項；arg 引數是該選項的值。如果選項是整數，請指定指向整數值的指標作為 arg 引數。

用於 SSL 憑證和金鑰檔案等資訊的選項可用於建立加密連線（如果此類連線可用），但不強制要求取得的連線必須加密。若要要求加密連線，請使用第 3.6.1 節「支援加密連線」中所述的技術。

以下清單說明了可能的選項、其效果，以及如何將 arg 用於每個選項。對於指示 arg 未使用的選項說明，其值無關緊要；通常會傳遞 0。

  • MYSQL_DEFAULT_AUTH (引數類型：char *)

    要使用的身份驗證外掛程式的名稱。

  • MYSQL_ENABLE_CLEARTEXT_PLUGIN (引數類型：bool *)

    啟用 mysql_clear_password 明文身份驗證外掛程式。請參閱 用戶端明文可插拔驗證。

  • MYSQL_INIT_COMMAND (引數類型：char *)

    連接到 MySQL 伺服器時要執行的 SQL 陳述式。如果發生重新連線，將自動重新執行。

  • MYSQL_OPT_BIND (引數：char *)

    要連線到伺服器的網路介面。當用戶端主機有多個網路介面時，會使用此選項。引數是主機名稱或 IP 位址 (指定為字串)。

  • MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS (引數類型：bool *)

    指出用戶端是否可以處理過期的密碼。請參閱 伺服器處理過期密碼。

  • MYSQL_OPT_COMPRESS (引數：未使用)

    如果可能，壓縮在用戶端和伺服器之間傳送的所有資訊。請參閱 連線壓縮控制。

    從 MySQL 8.0.18 開始，由於引入了 MYSQL_OPT_COMPRESSION_ALGORITHMS 選項來更好地控制連線壓縮（請參閱 設定連線壓縮），MYSQL_OPT_COMPRESS 成為舊版選項。MYSQL_OPT_COMPRESS 的含義取決於是否指定了 MYSQL_OPT_COMPRESSION_ALGORITHMS

    • 如果未指定 MYSQL_OPT_COMPRESSION_ALGORITHMS，則啟用 MYSQL_OPT_COMPRESS 等同於指定用戶端演算法集 zlib,uncompressed。

    • 如果指定了 MYSQL_OPT_COMPRESSION_ALGORITHMS，則啟用 MYSQL_OPT_COMPRESS 等同於指定演算法集 zlib，並且完整的用戶端演算法集是 zlib 加上 MYSQL_OPT_COMPRESSION_ALGORITHMS 指定的演算法的聯集。例如，如果啟用 MYSQL_OPT_COMPRESS 並且將 MYSQL_OPT_COMPRESSION_ALGORITHMS 設定為 zlib,zstd，則允許的演算法集為 zlib 加上 zlib,zstd；也就是說 zlib,zstd。如果啟用 MYSQL_OPT_COMPRESS 並且將 MYSQL_OPT_COMPRESSION_ALGORITHMS 設定為 zstd,uncompressed，則允許的演算法集為 zlib 加上 zstd,uncompressed；也就是說，zlib,zstd,uncompressed。

    從 MySQL 8.0.18 開始，MYSQL_OPT_COMPRESS 已被棄用。它將在未來的 MySQL 版本中移除。請參閱 設定舊版連線壓縮。

  • MYSQL_OPT_COMPRESSION_ALGORITHMS (引數類型：const char *)

    允許連線到伺服器的壓縮演算法。可用的演算法與 protocol_compression_algorithms 系統變數相同。如果未指定此選項，則預設值為 uncompressed。

    如需詳細資訊，請參閱 連線壓縮控制。

    此選項已在 MySQL 8.0.18 中新增。對於非同步作業，此選項在 MySQL 8.0.21 之前無效。

  • MYSQL_OPT_CONNECT_ATTR_DELETE (引數類型：char *)

    給定一個金鑰名稱，此選項會從要傳遞到伺服器（在連線時）的目前連線屬性集中刪除一個鍵值對。引數是指向命名金鑰之 Null 終止字串的指標。金鑰名稱與現有金鑰的比較會區分大小寫。

    另請參閱 MYSQL_OPT_CONNECT_ATTR_RESET 選項的說明，以及 mysql_options4() 函式說明中的 MYSQL_OPT_CONNECT_ATTR_ADD 選項說明。該函式說明也包含一個使用範例。

    效能結構描述透過 session_connect_attrs 和 session_account_connect_attrs 表格公開連線屬性。請參閱 效能結構描述連線屬性表格。

  • MYSQL_OPT_CONNECT_ATTR_RESET (未使用引數)

    此選項會重設 (清除) 要在連線時傳遞到伺服器的目前連線屬性集。

    另請參閱 MYSQL_OPT_CONNECT_ATTR_DELETE 選項的說明，以及 mysql_options4() 函式說明中的 MYSQL_OPT_CONNECT_ATTR_ADD 選項說明。該函式說明也包含一個使用範例。

    效能結構描述透過 session_connect_attrs 和 session_account_connect_attrs 表格公開連線屬性。請參閱 效能結構描述連線屬性表格。

  • MYSQL_OPT_CONNECT_TIMEOUT (引數類型：unsigned int *)

    連線逾時 (秒)。

  • MYSQL_OPT_GET_SERVER_PUBLIC_KEY (引數類型：bool *)

    啟用用戶端從伺服器請求用於 RSA 金鑰對式密碼交換的公鑰。此選項適用於使用 caching_sha2_password 身份驗證外掛程式進行驗證的用戶端。對於該外掛程式，伺服器不會傳送公鑰，除非已要求。對於未使用該外掛程式驗證的帳戶，此選項會被忽略。如果未使用基於 RSA 的密碼交換，也會被忽略，就像用戶端使用安全連線連線到伺服器的情況一樣。

    如果已給定 MYSQL_SERVER_PUBLIC_KEY 並指定了有效的公鑰檔案，它會優先於 MYSQL_OPT_GET_SERVER_PUBLIC_KEY。

    如需有關 caching_sha2_password 外掛程式的資訊，請參閱 快取 SHA-2 可插拔驗證。

  • MYSQL_OPT_LOAD_DATA_LOCAL_DIR (引數類型：char *)

    此選項會影響客戶端 LOAD DATA 操作的 LOCAL 功能。它指定 LOAD DATA LOCAL 陳述式中命名的檔案必須所在的目錄。 MYSQL_OPT_LOAD_DATA_LOCAL_DIR 的效果取決於是否啟用或停用 LOCAL 資料載入。

    • 如果啟用 LOCAL 資料載入，無論是在 MySQL 客戶端程式庫中預設啟用，還是透過明確啟用 MYSQL_OPT_LOCAL_INFILE，MYSQL_OPT_LOAD_DATA_LOCAL_DIR 選項都無效。

    • 如果停用 LOCAL 資料載入，無論是在 MySQL 客戶端程式庫中預設停用，還是透過明確停用 MYSQL_OPT_LOCAL_INFILE，則可以使用 MYSQL_OPT_LOAD_DATA_LOCAL_DIR 選項來指定允許載入本機檔案的目錄。在此情況下，允許 LOCAL 資料載入，但僅限於位於指定目錄中的檔案。MYSQL_OPT_LOAD_DATA_LOCAL_DIR 值的解讀如下：

      • 如果值為空指標（預設值），則表示未命名目錄，因此不允許任何檔案用於 LOCAL 資料載入。

      • 如果值為目錄路徑名稱，則允許 LOCAL 資料載入，但僅限於位於指定目錄中的檔案。無論底層檔案系統是否區分大小寫，目錄路徑名稱與要載入的檔案路徑名稱的比較都會區分大小寫。

    例如，若要明確停用本機資料載入，但允許位於 /my/local/data 目錄中的檔案，請如下調用 mysql_options()：

    unsigned int i = 0;
mysql_options(&mysql,MYSQL_OPT_LOCAL_INFILE,&i);
mysql_options(&mysql,MYSQL_OPT_LOAD_DATA_LOCAL_DIR,"/my/local/data");

    MYSQL_OPT_LOAD_DATA_LOCAL_DIR 選項可以在 mysql 連線處理程式的生命週期中的任何時間設定。一旦設定，該值將應用於所有後續的 LOCAL 載入操作，直到該值被變更。

    ENABLED_LOCAL_INFILE CMake 選項控制本機資料載入的客戶端程式庫預設值（請參閱MySQL 來源組態選項）。

    客戶端成功使用 LOCAL 載入操作也需要伺服器允許本機載入；請參閱LOAD DATA LOCAL 的安全考量

    MYSQL_OPT_LOAD_DATA_LOCAL_DIR 選項是在 MySQL 8.0.21 中新增的。

  • MYSQL_OPT_LOCAL_INFILE (引數類型：指向 unsigned int 的可選指標)

    此選項會影響客戶端 LOAD DATA 操作的 LOCAL 功能。預設情況下，LOCAL 功能由編譯到 MySQL 客戶端程式庫中的預設值決定。若要明確控制此功能，請調用 mysql_options() 來啟用或停用 MYSQL_OPT_LOCAL_INFILE 選項

    • 若要啟用 LOCAL 資料載入，請將指標設定為指向具有非零值的 unsigned int，或者省略指標引數。

    • 若要停用 LOCAL 資料載入，請將指標設定為指向具有零值的 unsigned int。

    如果停用 LOCAL 功能，則可以使用 MYSQL_OPT_LOAD_DATA_LOCAL_DIR 選項來允許限制性本機載入位於指定目錄中的檔案。

    ENABLED_LOCAL_INFILE CMake 選項控制本機資料載入的客戶端程式庫預設值（請參閱MySQL 來源組態選項）。

    客戶端成功使用 LOCAL 載入操作也需要伺服器允許本機載入；請參閱LOAD DATA LOCAL 的安全考量

  • MYSQL_OPT_MAX_ALLOWED_PACKET (引數：unsigned long *)

    此選項設定客戶端/伺服器通訊的客戶端緩衝區最大大小。如果 mysql 引數為非 NULL，則該呼叫會設定該會話的選項值。如果 mysql 為 NULL，則該呼叫會針對所有後續未指定會話特定值的會話全域設定選項值。

    由於可以根據 mysql 引數為非 NULL 或 NULL 設定會話或全域最大緩衝區大小，mysql_get_option() 也會根據其 mysql 引數傳回會話或全域值。

  • MYSQL_OPT_NAMED_PIPE (引數：未使用)

    如果伺服器允許具名管道連線，則使用具名管道連線到 Windows 上的 MySQL 伺服器。

  • MYSQL_OPT_NET_BUFFER_LENGTH (引數：unsigned long *)

    此選項設定 TCP/IP 和通訊端的客戶端緩衝區大小。

  • MYSQL_OPT_OPTIONAL_RESULTSET_METADATA (引數類型：bool *)

    此旗標使結果集元資料成為可選的。它是為 mysql_real_connect() 函式設定 CLIENT_OPTIONAL_RESULTSET_METADATA 連線旗標的替代方案。有關管理結果集元資料傳輸的詳細資訊，請參閱第 3.6.7 節「可選結果集元資料」。

  • MYSQL_OPT_PROTOCOL (引數類型：unsigned int *)

    用於連線的傳輸協定。指定 mysql.h 中定義的 mysql_protocol_type 的其中一個列舉值。

  • MYSQL_OPT_READ_TIMEOUT (引數類型：unsigned int *)

    每次嘗試從伺服器讀取時的逾時秒數。如有必要，會進行重試，因此總有效逾時值為選項值的三倍。您可以設定該值，以便比 10 分鐘的 TCP/IP Close_Wait_Timeout 值更早偵測到連線遺失。

  • MYSQL_OPT_RECONNECT (引數類型：bool *)

    注意

    MYSQL_OPT_RECONNECT 選項仍然可用，但已被棄用；預計在未來版本的 MySQL 中將會移除。

    如果發現連線遺失，則啟用或停用與伺服器的自動重新連線。重新連線預設為關閉；此選項提供了一種明確設定重新連線行為的方式。請參閱第 3.6.8 節「自動重新連線控制」。

  • MYSQL_OPT_RETRY_COUNT (引數類型：unsigned int *)

    在連線到伺服器或與伺服器通訊時中斷的 I/O 相關系統呼叫的重試計數。如果未指定此選項，則預設值為 1（如果初始呼叫中斷，則重試 1 次，共嘗試 2 次）。

    此選項只能由連結到具有 NDB Cluster 支援的 C 客戶端程式庫的客戶端使用。

  • MYSQL_OPT_SSL_CA (引數類型：char *)

    憑證授權單位 (CA) 憑證檔案的路徑名稱。如果使用此選項，則必須指定伺服器使用的相同憑證。

  • MYSQL_OPT_SSL_CAPATH (引數類型：char *)

    包含受信任 SSL CA 憑證檔案的目錄路徑名稱。

  • MYSQL_OPT_SSL_CERT (引數類型：char *)

    客戶端公開金鑰憑證檔案的路徑名稱。

  • MYSQL_OPT_SSL_CIPHER (引數類型：char *)

    用於 SSL 加密的允許密碼清單。

  • MYSQL_OPT_SSL_CRL (引數類型：char *)

    包含憑證撤銷清單的檔案路徑名稱。

  • MYSQL_OPT_SSL_CRLPATH (引數類型：char *)

    包含憑證撤銷清單的檔案所在目錄的路徑名稱。

  • MYSQL_OPT_SSL_FIPS_MODE (引數類型：unsigned int *)

    MYSQL_OPT_SSL_FIPS_MODE 選項已棄用，可能會在未來版本的 MySQL 中移除。

    控制是否在客戶端啟用 FIPS 模式。MYSQL_OPT_SSL_FIPS_MODE 選項與其他 MYSQL_OPT_SSL_xxx 選項不同之處在於，它不用於建立加密連線，而是影響允許哪些加密操作。請參閱FIPS 支援。

    允許的選項值為 SSL_FIPS_MODE_OFF、SSL_FIPS_MODE_ON 和 SSL_FIPS_MODE_STRICT。

    注意

    如果 OpenSSL FIPS 物件模組不可用，則 MYSQL_OPT_SSL_FIPS_MODE 的唯一允許值為 SSL_FIPS_MODE_OFF。在這種情況下，將 MYSQL_OPT_SSL_FIPS_MODE 設定為 SSL_FIPS_MODE_ON 或 SSL_FIPS_MODE_STRICT 會導致客戶端在啟動時產生警告，並在非 FIPS 模式下執行。

  • MYSQL_OPT_SSL_KEY (引數類型：char *)

    客戶端私密金鑰檔案的路徑名稱。

  • MYSQL_OPT_SSL_MODE (引數類型：unsigned int *)

    用於與伺服器連線的安全性狀態：SSL_MODE_DISABLED、SSL_MODE_PREFERRED、SSL_MODE_REQUIRED、SSL_MODE_VERIFY_CA、SSL_MODE_VERIFY_IDENTITY。如果未指定此選項，則預設值為 SSL_MODE_PREFERRED。這些模式是 mysql.h 中定義的 mysql_ssl_mode 列舉的允許值。有關安全性狀態的詳細資訊，請參閱--ssl-mode 在加密連線的命令選項中的說明。

  • MYSQL_OPT_SSL_SESSION_DATA (引數類型：void *)

    在建立下一個加密連線時用於會話重用的會話資料。它應在 mysql_real_connect() 之前和 mysql_init() 之後設定。它需要 mysql_get_ssl_session_data() 傳回的 PEM 會話資料，並將結果複製到 MYSQL 控制代碼。除非透過 CLIENT_REMEMBER_OPTIONS 旗標另行指定，否則它會在 mysql_real_connect() 之後重設為 nullptr（預設值）。

    如果已指定，則會在 TLS 建立時嘗試重用會話。mysql_get_option() 傳回 mysql_options() 設定的控制代碼（如果有的話），並且不會增加參考計數。

    此選項是在 MySQL 8.0.29 中新增的。

  • MYSQL_OPT_TLS_CIPHERSUITES (引數類型：char *)

    客戶端允許用於使用 TLSv1.3 的加密連線的密碼套件。該值是一個或多個以冒號分隔的密碼套件名稱的清單。可以為此選項命名的密碼套件取決於用於編譯 MySQL 的 SSL 程式庫。有關詳細資訊，請參閱加密連線 TLS 協定和密碼。

    此選項是在 MySQL 8.0.16 中新增的。

  • MYSQL_OPT_TLS_SNI_SERVERNAME (引數類型：char *)

    客戶端在 TLS 交握開始時嘗試連線的伺服器。此選項必須在連線到伺服器之前設定。伺服器名稱包含客戶端理解的伺服器完整 DNS 主機名稱。伺服器名稱表示為使用 ASCII 編碼的位元組字串，沒有尾隨點，並且不區分大小寫。

    伺服器名稱指示 (SNI) 是 TLS 通訊協定的延伸（OpenSSL 必須使用 TLS 延伸功能編譯，此選項才能運作）。MySQL 對於 SNI 的實作僅代表用戶端。

  • MYSQL_OPT_TLS_VERSION (引數類型：char *)

    用戶端允許用於加密連線的協定。值是以逗號分隔的一或多個協定版本清單。此選項可命名的協定取決於用於編譯 MySQL 的 SSL 程式庫。如需詳細資訊，請參閱加密連線 TLS 協定和密碼。

  • MYSQL_OPT_USE_RESULT (引數：未使用)

    此選項未使用。

  • MYSQL_OPT_WRITE_TIMEOUT (引數類型：unsigned int *)

    每次嘗試寫入伺服器的逾時時間，以秒為單位。如有必要，會重試，因此總有效逾時值是選項值的兩倍。

  • MYSQL_OPT_ZSTD_COMPRESSION_LEVEL (引數類型：unsigned int *)

    用於連線至使用 zstd 壓縮演算法的伺服器的壓縮層級。允許的層級為 1 到 22，數值越大表示壓縮層級越高。如果未指定此選項，則預設的 zstd 壓縮層級為 3。壓縮層級設定對未使用 zstd 壓縮的連線沒有影響。

    如需詳細資訊，請參閱 連線壓縮控制。

    此選項已在 MySQL 8.0.18 中新增。對於非同步作業，此選項在 MySQL 8.0.21 之前無效。

  • MYSQL_PLUGIN_DIR (引數類型：char *)

    尋找用戶端外掛程式的目錄。

  • MYSQL_READ_DEFAULT_FILE (引數類型：char *)

    從指定的選項檔讀取選項，而不是從 my.cnf 讀取。

  • MYSQL_READ_DEFAULT_GROUP (引數類型：char *)

    從 my.cnf 或使用 MYSQL_READ_DEFAULT_FILE 指定的檔案中，讀取指定群組的選項。

  • MYSQL_REPORT_DATA_TRUNCATION (引數類型：bool *)

    啟用或停用針對使用 MYSQL_BIND 結構的 error 成員的預備語句，報告資料截斷錯誤。(預設值：已啟用。)

  • MYSQL_SERVER_PUBLIC_KEY (引數類型：char *)

    PEM 格式的檔案路徑名稱，其中包含伺服器要求以 RSA 金鑰組為基礎的密碼交換的用戶端副本公開金鑰。此選項適用於使用 sha256_password 或 caching_sha2_password 驗證外掛程式進行驗證的用戶端。對於不使用這些外掛程式之一進行驗證的帳戶，此選項會被忽略。如果未使用以 RSA 為基礎的密碼交換，也會被忽略，例如當用戶端使用安全連線連線到伺服器時。

    如果已給定 MYSQL_SERVER_PUBLIC_KEY 並指定了有效的公鑰檔案，它會優先於 MYSQL_OPT_GET_SERVER_PUBLIC_KEY。

    有關 sha256_password 和 caching_sha2_password 外掛程式的資訊，請參閱SHA-256 可插入驗證，以及快取 SHA-2 可插入驗證。

  • MYSQL_SET_CHARSET_DIR (引數類型：char *)

    包含字元集定義檔案的目錄路徑名稱。

  • MYSQL_SET_CHARSET_NAME (引數類型：char *)

    要用作預設字元集的字元集名稱。引數可以是 MYSQL_AUTODETECT_CHARSET_NAME，以根據作業系統設定自動偵測字元集（請參閱連線字元集和定序）。

  • MYSQL_SHARED_MEMORY_BASE_NAME (引數類型：char *)

    如果伺服器支援共用記憶體連線，則在 Windows 上用於與伺服器通訊的共用記憶體物件名稱。指定與shared_memory_base_name系統變數相同的值。您要連線的 mysqld 伺服器。

如果您使用 MYSQL_READ_DEFAULT_FILE 或 MYSQL_READ_DEFAULT_GROUP，則會永遠讀取 client 群組。

選項檔中指定的群組可能包含以下選項。

選項 描述
character-sets-dir=dir_name 安裝字元集的目錄。
compress 使用壓縮的用戶端/伺服器通訊協定。
connect-timeout=seconds 連線逾時時間，以秒為單位。在 Linux 上，此逾時時間也用於等待伺服器的第一個回覆。
database=db_name 如果未在連線命令中指定資料庫，則連線到此資料庫。
debug 偵錯選項。
default-character-set=charset_name 要使用的預設字元集。
disable-local-infile 停用 LOAD DATA LOCAL 的使用。
enable-cleartext-plugin 啟用 mysql_clear_password 明文驗證外掛程式。
host=host_name 預設主機名稱。
init-command=stmt 連線到 MySQL 伺服器時要執行的語句。如果發生重新連線，則會自動重新執行。
interactive-timeout=seconds 與為 mysql_real_connect() 指定 CLIENT_INTERACTIVE 相同。請參閱第 5.4.58 節「mysql_real_connect()」。
local-infile[={0|1}] 如果沒有引數或非零引數，則啟用 LOAD DATA LOCAL 的使用；否則停用。
max_allowed_packet=bytes 用戶端可從伺服器讀取的封包最大大小。
multi-queries、multi-results 啟用來自多語句執行或預存程序的多次結果集。
multi-statements 允許用戶端在單一字串中傳送多個語句（以 ; 字元分隔）。
password=password 預設密碼。
pipe 使用具名管道連線到 Windows 上的 MySQL 伺服器。
port=port_num 預設連接埠號碼。
protocol={TCP|SOCKET|PIPE|MEMORY} 連線至伺服器時要使用的通訊協定。
return-found-rows 告訴 mysql_info() 在使用 UPDATE 時傳回找到的列，而不是更新的列。
shared-memory-base-name=name 用於連線至伺服器的共用記憶體名稱。
socket={file_name|pipe_name} 預設 Socket 檔案。
ssl-ca=file_name 憑證授權單位檔案。
ssl-capath=dir_name 憑證授權單位目錄。
ssl-cert=file_name 憑證檔案。
ssl-cipher=cipher_list 允許的 SSL 密碼。
ssl-key=file_name 金鑰檔案。
timeout=seconds 與 connect-timeout 相似。
user 預設使用者。

timeout 已由 connect-timeout 取代，但為了回溯相容性，仍然支援 timeout。

如需有關 MySQL 程式所使用選項檔案的詳細資訊，請參閱使用選項檔案。

傳回值

成功則傳回零。如果指定未知的選項，則傳回非零值。

範例

以下 mysql_options() 呼叫會要求在用戶端/伺服器通訊協定中使用壓縮，從選項檔案中的 [odbc] 群組讀取選項，並停用交易自動認可模式

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
mysql_options(&mysql,MYSQL_INIT_COMMAND,"SET autocommit=0");
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));
}

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