文件首頁
MySQL 9.0 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 *）

    此選項會影響用戶端 LOCAL 功能，用於 LOAD DATA 操作。它指定 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 的可選指標)

    此選項會影響用戶端 LOCAL 功能，用於 LOAD DATA 操作。預設情況下，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 和 Socket 通訊的用戶端緩衝區大小。

  • 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 *)

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

  • 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 協定的擴充功能（必須使用 TLS 擴充功能編譯 OpenSSL，此選項才能正常運作）。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 上與伺服器通訊的共用記憶體物件的名稱。指定與您要連線的 mysqld 伺服器的shared_memory_base_name系統變數相同的值。

如果您使用 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 與將 CLIENT_INTERACTIVE 指定給mysql_real_connect() 相同。請參閱第 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