MySQL :: MySQL 8.4 C API 开发者指南 :: 5.4.54 mysql_options()

版本 8.4

MySQL 8.4 C API 开发者指南 / ... / mysql_options()

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 数据加载
- 如果在 MySQL 客户端库中默认启用 LOCAL 数据加载，或者通过显式启用 MYSQL_OPT_LOCAL_INFILE 启用了该功能，则 MYSQL_OPT_LOAD_DATA_LOCAL_DIR 选项无效。
- 如果在 MySQL 客户端库中默认禁用了 LOCAL 数据加载，或者通过显式禁用 MYSQL_OPT_LOCAL_INFILE 禁用了该功能，则可以使用 MYSQL_OPT_LOAD_DATA_LOCAL_DIR 选项为本地加载的文件指定允许的目录。在这种情况下，允许 LOCAL 数据加载，但仅限于位于指定目录中的文件。对 MYSQL_OPT_LOAD_DATA_LOCAL_DIR 值的解释如下：
  - 如果该值为 null 指针（默认值），则它不指定任何目录，结果是不允许任何文件进行 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 连接处理程序的生存期内的任何时候设置 MYSQL_OPT_LOAD_DATA_LOCAL_DIR 选项。设置后，该值将应用于所有后续的 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 *）

每次尝试从服务器读取数据的超时时间（以秒为单位）。如有必要，将进行重试，因此总的有效超时值为选项值的三倍。您可以设置该值，以便比 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 上与服务器通信的共享内存对象的名称。指定与 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}`	默认套接字文件。
`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));
}