27.7.6.50 mysql_options()

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

Description

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

在mysql_init()之后和mysql_connect()或mysql_real_connect()之前致电mysql_options()。

option参数是您要设置的选项； arg参数是选项的值。如果该选项是整数，则将指向整数值的指针指定为arg参数。

如果可以使用 SSL 证书和密钥文件之类的信息选项来构建加密连接，但是这些选项不强制要求对获得的连接进行加密。要要求加密连接，请使用第 27.7.14 节“加密连接的 C API 支持”中描述的技术。

以下列 table 描述了可能的选项，它们的效果以及每个选项使用arg的方式。对于 table 明arg未使用的选项描述，其值无关紧要；通常会传递 0.只有当应用程序针对libmysqld嵌入式服务器库进行链接时，其中一些选项才适用，而针对libmysqlclientClient 端库进行链接的应用程序则不使用这些选项。

  • MYSQL_DEFAULT_AUTH(参数类型：char *)

要使用的身份验证插件的名称。

  • MYSQL_ENABLE_CLEARTEXT_PLUGIN(参数类型：my_bool *)

启用mysql_clear_password明文身份验证插件。参见第 6.4.1.6 节“Client 端明文可插入身份验证”。

  • MYSQL_INIT_COMMAND(参数类型：char *)

连接到 MySQL 服务器时要执行的 SQL 语句。如果发生重新连接，则自动重新执行。

  • MYSQL_OPT_BIND(参数：char *)

从中连接到服务器的网络接口。当 Client 端主机具有多个网络接口时使用。参数是主机名或 IP 地址(指定为字符串)。

  • MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS(参数类型：my_bool *)

指示 Client 端是否可以处理过期的密码。参见第 6.2.12 节“过期密码的服务器处理”。

  • MYSQL_OPT_COMPRESS(参数：未使用)

尽可能压缩 Client 端和服务器之间发送的所有信息。参见第 4.2.6 节“连接压缩控制”。

  • MYSQL_OPT_CONNECT_ATTR_DELETE(参数类型：char *)

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

另请参见MYSQL_OPT_CONNECT_ATTR_RESET选项的描述以及mysql_options4()函数的描述中的MYSQL_OPT_CONNECT_ATTR_ADD选项的描述。该功能描述还包括一个使用示例。

性能架构通过session_connect_attrs和session_account_connect_attrstable 公开了连接属性。参见第 25.12.9 节“性能架构连接属性 table”。

  • MYSQL_OPT_CONNECT_ATTR_RESET(未使用参数)

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

另请参见MYSQL_OPT_CONNECT_ATTR_DELETE选项的描述以及mysql_options4()函数的描述中的MYSQL_OPT_CONNECT_ATTR_ADD选项的描述。该功能描述还包括一个使用示例。

性能架构通过session_connect_attrs和session_account_connect_attrstable 公开了连接属性。参见第 25.12.9 节“性能架构连接属性 table”。

  • MYSQL_OPT_CONNECT_TIMEOUT(参数类型：unsigned int *)

连接超时(以秒为单位)。

  • MYSQL_OPT_GET_SERVER_PUBLIC_KEY(参数类型：my_bool *)

使 Client 端能够从服务器请求基于 RSA 密钥对的密码交换所需的公共密钥。此选项适用于使用caching_sha2_password身份验证插件进行身份验证的 Client 端。对于该插件，除非请求，否则服务器不会发送公钥。对于未使用该插件进行身份验证的帐户，将忽略此选项。如果不使用基于 RSA 的密码交换，也将被忽略，例如 Client 端使用安全连接连接到服务器时。

如果给出了MYSQL_SERVER_PUBLIC_KEY并指定了有效的公共密钥文件，则它优先于MYSQL_OPT_GET_SERVER_PUBLIC_KEY。

有关caching_sha2_password插件的信息，请参见第 6.4.1.4 节“缓存 SHA-2 可插入身份验证”。

这个选项是在 MySQL 5.7.23 中添加的。

  • MYSQL_OPT_GUESS_CONNECTION(参数：未使用)

对于链接到libmysqld嵌入式服务器库的应用程序，此选项使该库能够猜测是使用嵌入式服务器还是使用远程服务器。 “猜测”table 示如果设置了主机名而不是localhost，则它将使用远程服务器。此行为是默认行为。 MYSQL_OPT_USE_EMBEDDED_CONNECTION和MYSQL_OPT_USE_REMOTE_CONNECTION可用于覆盖它。对于与libmysqlclientClient 端库链接的应用程序，将忽略此选项。

  • MYSQL_OPT_LOCAL_INFILE(参数类型：指向unsigned int的可选指针)

此选项影响 Client 端LOAD DATA操作的LOCAL功能。默认情况下，LOCAL功能由编译到 MySQLClient 端库中的默认值确定。要显式控制此功能，请调用mysql_options()以启用或禁用MYSQL_OPT_LOCAL_INFILE选项：

  • 要启用LOCAL数据加载，请将指针设置为指向具有非零值的unsigned int，或者忽略指针参数。

    • 要禁用LOCAL数据加载，请将指针设置为指向具有零值的unsigned int。

ENABLED_LOCAL_INFILE CMake 选项控制用于本地数据加载的 Client 端库默认设置(请参见第 2.9.7 节“ MySQL 源配置选项”)。

Client 端成功使用LOCAL加载操作还需要服务器允许本地加载。见第 6.1.6 节“ LOAD DATA LOCAL 的安全注意事项”

  • MYSQL_OPT_MAX_ALLOWED_PACKET(参数：unsigned long *)

此选项设置 Client 端/服务器通信的缓冲区的 Client 端最大大小。如果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 和套接字通信的 Client 端缓冲区大小。

  • 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(参数类型：my_bool *)

如果发现连接丢失，则启用或禁用与服务器的自动重新连接。默认情况下，“重新连接”处于关闭状态；此选项提供了一种显式设置重新连接行为的方法。参见第 27.7.19 节“ C API 自动重新连接控制”。

  • MYSQL_OPT_RETRY_COUNT(参数类型：unsigned int *)

与服务器连接或通信时中断的与 I/O 相关的系统调用的重试计数。如果未指定此选项，则默认值为 1(如果初始调用被中断 2 次，则重试 1 次)。

只有链接到与 NDB 群集支持兼容的 CClient 端库的 Client 端才能使用此选项。自 MySQL NDB Cluster 7.5.1 起可用。

  • MYSQL_OPT_SSL_CA(参数类型：char *)

证书颁发机构(CA)证书文件的路径名。如果使用此选项，则必须指定服务器使用的相同证书。

  • MYSQL_OPT_SSL_CAPATH(参数类型：char *)

包含受信任的 SSL CA 证书文件的目录的路径名。

  • MYSQL_OPT_SSL_CERT(参数类型：char *)

Client 端公钥证书文件的路径名。

  • MYSQL_OPT_SSL_CIPHER(参数类型：char *)

SSL 加密的允许密码列 table。

  • MYSQL_OPT_SSL_CRL(参数类型：char *)

包含证书吊销列 table 的文件的路径名。

  • MYSQL_OPT_SSL_CRLPATH(参数类型：char *)

包含文件的目录的路径名，该文件包含证书吊销列 table。

  • MYSQL_OPT_SSL_ENFORCE(参数类型：my_bool *)

是否要求连接使用 SSL。如果启用并且无法构建加密连接，则连接尝试将失败。

从 MySQL 5.7.11 开始不推荐使用该选项，并且在 MySQL 8.0 中已将其删除。而是使用MYSQL_OPT_SSL_MODE的值SSL_MODE_REQUIRED。

  • MYSQL_OPT_SSL_KEY(参数类型：char *)

Client 端私钥文件的路径名。

  • 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 5.7.11 中添加的。

  • MYSQL_OPT_SSL_VERIFY_SERVER_CERT(参数类型：my_bool *)

根据连接到服务器时使用的主机名，启用或禁用服务器证书中的服务器公用名身份验证。如果不匹配，则拒绝连接。对于加密连接，此功能可用于防止中间人攻击。默认情况下，身份验证是禁用的。

此选项不适用于不包含服务器名称作为“通用名称”值的自签名证书。

从 MySQL 5.7.11 开始不推荐使用该选项，并且在 MySQL 8.0 中已将其删除。而是使用MYSQL_OPT_SSL_MODE的值SSL_MODE_VERIFY_IDENTITY。

  • MYSQL_OPT_TLS_VERSION(参数类型：char *)

Client 端允许哪种协议进行加密连接。该值是一个或多个逗号分隔的协议版本的列 table。可以为此选项命名的协议取决于用于编译 MySQL 的 SSL 库。有关详细信息，请参见第 6.3.2 节“加密的连接 TLS 协议和密码”。

MySQL 5.7.10 中添加了此选项。

  • MYSQL_OPT_USE_EMBEDDED_CONNECTION(参数：未使用)

对于链接到libmysqld嵌入式服务器库的应用程序，此选项将强制使用嵌入式服务器进行连接。对于与libmysqlclientClient 端库链接的应用程序，它将被忽略。

  • MYSQL_OPT_USE_REMOTE_CONNECTION(参数：未使用)

对于链接到libmysqld嵌入式服务器库的应用程序，此选项将强制使用远程服务器进行连接。对于与libmysqlclientClient 端库链接的应用程序，它将被忽略。

  • MYSQL_OPT_USE_RESULT(参数：未使用)

此选项未使用。

  • MYSQL_OPT_WRITE_TIMEOUT(参数类型：unsigned int *)

每次尝试写入服务器的超时时间(以秒为单位)。如有必要，请重试，因此总有效超时值是选项值的两倍。

  • MYSQL_PLUGIN_DIR(参数类型：char *)

在其中查找 Client 端插件的目录。

  • MYSQL_READ_DEFAULT_FILE(参数类型：char *)

从命名的选项文件而不是从my.cnf读取选项。

  • MYSQL_READ_DEFAULT_GROUP(参数类型：char *)

从my.cnf或MYSQL_READ_DEFAULT_FILE指定的文件中读取命名组中的选项。

  • MYSQL_REPORT_DATA_TRUNCATION(参数类型：my_bool *)

使用MYSQL_BIND结构的error成员为准备好的语句启用或禁用数据截断错误报告。 (默认：启用.)

  • MYSQL_SECURE_AUTH(参数类型：my_bool *)

是否连接到不支持 MySQL 4.1.1 及更高版本中使用的密码哈希的服务器。默认情况下启用此选项。

  • MYSQL_SERVER_PUBLIC_KEY(参数类型：char *)

PEM 格式的文件的路径名，其中包含服务器用于基于 RSA 密钥对的密码交换所需的公用密钥的 Client 端副本。此选项适用于使用sha256_password身份验证插件进行身份验证的 Client 端。对于未通过这些插件之一进行身份验证的帐户，将忽略此选项。如果不使用基于 RSA 的密码交换，也将被忽略，例如 Client 端使用安全连接连接到服务器时。

如果给出了MYSQL_SERVER_PUBLIC_KEY并指定了有效的公共密钥文件，则它优先于MYSQL_OPT_GET_SERVER_PUBLIC_KEY。

有关sha256_password和caching_sha2_password插件的信息，请参见第 6.4.1.5 节“ SHA-256 可插拔身份验证”和第 6.4.1.4 节“缓存 SHA-2 可插入身份验证”。

  • MYSQL_SET_CHARSET_DIR(参数类型：char *)

包含字符集定义文件的目录的路径名。

  • MYSQL_SET_CHARSET_NAME(参数类型：char *)

用作默认字符集的字符集的名称。参数可以是MYSQL_AUTODETECT_CHARSET_NAME，以根据 os 设置自动检测字符集(请参阅第 10.4 节“连接字符集和排序规则”)。

  • MYSQL_SET_CLIENT_IP(参数类型：char *)

对于链接到libmysqld嵌入式服务器库的应用程序(当使用身份验证支持编译libmysqld时)，此选项 table 示出于身份验证目的，该用户被视为已从指定的 IP 地址(指定为字符串)进行连接。对于与libmysqlclientClient 端库链接的应用程序，它将被忽略。

  • MYSQL_SHARED_MEMORY_BASE_NAME(参数类型：char *)

如果服务器支持共享内存连接，则用于与 Windows 上的服务器通信的共享内存对象的名称。指定与shared_memory_base_name系统变量相同的值。您要连接的mysqld服务器。

如果使用MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP，则始终读取client组。

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

OptionDescription
character-sets-dir=dir_name字符集的安装目录。
compress使用压缩的 Client 端/服务器协议。
connect-timeout=seconds连接超时(以秒为单位)。在 Linux 上，此超时也用于 await 服务器的第一个答案。
database=db_name如果在 connect 命令中未指定数据库，则连接到该数据库。
debugDebug options.
default-character-set=charset_name要使用的默认字符集。
disable-local-infile禁止使用本地加载数据。
enable-cleartext-plugin启用mysql_clear_password明文身份验证插件。
host=host_name默认主机名。
init-command=stmt连接到 MySQL 服务器时要执行的语句。如果发生重新连接，则自动重新执行。
interactive-timeout=seconds与将CLIENT_INTERACTIVE指定为mysql_real_connect()相同。参见第 27.7.6.54 节，“ mysql_real_connect()”。
local-infile[={0|1}]如果没有参数或非零参数，则启用本地加载数据；否则禁用。
max_allowed_packet=bytesClient 端可以从服务器读取的最大数据包大小。
multi-queries , multi-results从多语句执行或存储过程中启用多个结果集。
multi-statements使 Client 端能够在单个字符串(由;个字符分隔)中发送多个语句。
password=passwordDefault password.
pipe使用命名管道连接到 Windows 上的 MySQL 服务器。
port=port_num默认端口号。
protocol={TCP|SOCKET|PIPE|MEMORY}连接到服务器时要使用的协议。
return-found-rows使用UPDATE时，告诉mysql_info()返回找到的行而不是更新的行。
shared-memory-base-name=name用于连接服务器的共享内存名称。
socket={file_name|pipe_name}默认套接字文件。
ssl-ca=file_name认证中心文件。
ssl-capath=dir_name证书颁发机构目录。
ssl-cert=file_nameCertificate file.
ssl-cipher=cipher_list允许的 SSL 密码。
ssl-key=file_nameKey file.
timeout=seconds类似于connect-timeout。
userDefault user.

timeout已由connect-timeout代替，但仍支持timeout以实现向后兼容。

有关 MySQL 程序使用的选项文件的更多信息，请参见第 4.2.2.2 节“使用选项文件”。

Return Values

零成功。如果您指定未知选项，则为非零值。

Example

以下mysql_options()调用请求在 Client 端/服务器协议中使用压缩，导致从选项文件中的[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));
}
Name MySql 中文文档
Version
Language
Badge
Last Updated 2021-07-03T12:24:35