5.4.54 mysql_options()_MySQL 8.0 C API 开发者指南

MySQL 8.0 C API 开发者指南 / 第 5 章 C API 基本接口 / 5.4 C API 基本功能说明 / 5.4.54 mysql_options()

5.4.54 mysql_options()

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

描述

可用于设置额外的连接选项并影响连接的行为。可以多次调用此函数以设置多个选项。要检索选项值，请使用 mysql_get_option().

在or mysql_options()之后 mysql_init()和之前调用。 mysql_connect()mysql_real_connect()

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_COMPRESS ，因此成为遗留选项。的含义取决于是否指定： MYSQL_OPT_COMPRESSION_ALGORITHMSMYSQL_OPT_COMPRESSMYSQL_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 plus zlib,zstd；也就是说， zlib,zstd。MYSQL_OPT_COMPRESS启用并设置 MYSQL_OPT_COMPRESSION_ALGORITHMS 为zstd,uncompressed, 允许的算法集是zlib plus 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 *：）

给定键名，此选项从当前连接属性集中删除一个键值对，以在连接时传递给服务器。参数是指向命名键的以空字符结尾的字符串的指针。密钥名称与现有密钥的比较区分大小写。

另请参阅 MYSQL_OPT_CONNECT_ATTR_RESET选项说明，以及功能说明中的 MYSQL_OPT_CONNECT_ATTR_ADD选项说明 mysql_options4()。该功能描述还包括一个用法示例。

session_connect_attrs性能模式通过和 session_account_connect_attrs 表公开连接属性。请参阅性能模式连接属性表。
MYSQL_OPT_CONNECT_ATTR_RESET（未使用参数）

此选项重置（清除）当前的连接属性集以在连接时传递给服务器。

另请参阅 MYSQL_OPT_CONNECT_ATTR_DELETE选项说明，以及功能说明中的 MYSQL_OPT_CONNECT_ATTR_ADD选项说明 mysql_options4()。该功能描述还包括一个用法示例。

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 加载操作，直到该值被更改。

CMake选项控制本地数据加载的客户端库默认值（请参阅 MySQL Source-Configuration Options）。 ENABLED_LOCAL_INFILE

客户端成功使用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选项可用于允许限制本地加载位于指定目录中的文件。

CMake选项控制本地数据加载的客户端库默认值（请参阅 MySQL Source-Configuration Options）。 ENABLED_LOCAL_INFILE

客户端成功使用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 *：）

此标志使结果集元数据成为可选的。CLIENT_OPTIONAL_RESULTSET_METADATA 它是为函数设置连接标志的替代 mysql_real_connect() 方法。有关管理结果集元数据传输的详细信息，请参阅第 3.6.7 节，“可选结果集元数据”。
MYSQL_OPT_PROTOCOL（参数类型 unsigned int *：）

用于连接的传输协议。指定在中mysql_protocol_type 定义的枚举值之一mysql.h。
MYSQL_OPT_READ_TIMEOUT（参数类型 unsigned int *：）

每次尝试从服务器读取的超时时间（以秒为单位）。必要时会重试，因此总的有效超时值是选项值的三倍。您可以设置该值，以便在 TCP/IP Close_Wait_Timeout值 10 分钟之前检测到丢失的连接。
MYSQL_OPT_RECONNECT（参数类型 bool *：）

如果发现连接丢失，启用或禁用自动重新连接到服务器。重新连接默认关闭；此选项提供了一种显式设置重新连接行为的方法。请参阅第 3.6.8 节，“自动重新连接控制”。
MYSQL_OPT_RETRY_COUNT（参数类型 unsigned int *：）

在连接到服务器或与其通信时中断的 I/O 相关系统调用的重试计数。如果未指定此选项，则默认值为 1（如果初始呼叫中断总共尝试 2 次，则重试 1 次）。

此选项只能由链接到使用 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 *：）

控制是否在客户端启用 FIPS 模式。该MYSQL_OPT_SSL_FIPS_MODE选项与其他选项的不同之处在于它不用于建立加密连接，而是用于影响允许哪些加密操作。请参阅FIPS 支持。 MYSQL_OPT_SSL_xxx

允许的选项值为 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_ssl_mode 这些模式是中定义的枚举的允许值mysql.h。有关安全状态的更多信息，请参阅加密连接 --ssl-mode 的命令选项中的描述。
MYSQL_OPT_SSL_SESSION_DATA（参数类型void *：）

建立下一个加密连接时用于会话重用的会话数据。它应该设置在之前mysql_real_connect()和之后mysql_init()。它期望返回的 PEM 会话数据 mysql_get_ssl_session_data() 并将结果复制到 MYSQL 句柄中。它在nullptr之后重置为（默认值） mysql_real_connect()，除非通过 CLIENT_REMEMBER_OPTIONS标志另有说明。

如果指定，将尝试在 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_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 *：）

error 使用结构成员为准备好的语句启用或禁用数据截断错误报告MYSQL_BIND。（默认：启用。）
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服务器的名称。

如果您使用或，client则始终读取该组。 MYSQL_READ_DEFAULT_FILEMYSQL_READ_DEFAULT_GROUP

选项文件中的指定组可能包含以下选项。

选项	描述
`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}`	默认套接字文件。
`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));
}