Documentation Home
MySQL 5.7 C API 开发者指南

5.4.50 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。几个选项仅在应用程序链接到 libmysqld嵌入式服务器库时适用，而未用于链接到 libmysqlclient客户端库的应用程序。

  • MYSQL_DEFAULT_AUTH（参数类型 char *：）

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

  • MYSQL_ENABLE_CLEARTEXT_PLUGIN（参数类型my_bool *：）

    启用mysql_clear_password 明文身份验证插件。请参阅 客户端明文可插入身份验证。

  • MYSQL_INIT_COMMAND（参数类型 char *：）

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

  • MYSQL_OPT_BIND（参数char *：）

    连接到服务器的网络接口。这在客户端主机有多个网络接口时使用。参数是主机名或 IP 地址（指定为字符串）。

  • MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS （参数类型my_bool *：）

    指示客户端是否可以处理过期密码。请参阅服务器处理过期密码。

  • MYSQL_OPT_COMPRESS（参数：未使用）

    如果可能，压缩客户端和服务器之间发送的所有信息。请参阅 连接压缩控制。

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

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

    如果MYSQL_SERVER_PUBLIC_KEY给出并指定一个有效的公钥文件，它优先于MYSQL_OPT_GET_SERVER_PUBLIC_KEY.

    有关该 caching_sha2_password插件的信息，请参阅 缓存 SHA-2 可插入身份验证。

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

  • MYSQL_OPT_GUESS_CONNECTION（参数：未使用）

    对于链接到 libmysqld嵌入式服务器库的应用程序，此选项使库能够猜测是使用嵌入式服务器还是远程服务器。“猜测” 表示如果设置了主机名但未设置 localhost，则使用远程服务器。此行为是默认行为。 MYSQL_OPT_USE_EMBEDDED_CONNECTION并且 MYSQL_OPT_USE_REMOTE_CONNECTION可以用来覆盖它。libmysqlclient对于链接到客户端库 的应用程序，此选项将被忽略 。

  • MYSQL_OPT_LOCAL_INFILE（参数类型：指向 的可选指针unsigned int）

    此选项会影响客户端LOCAL 的操作能力LOAD DATA 。默认情况下，LOCAL 能力是由默认编译到 MySQL 客户端库中的。要显式控制此功能，请调用 mysql_options()以启用或禁用该MYSQL_OPT_LOCAL_INFILE 选项：

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

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

    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_PROTOCOL（参数类型 unsigned int *：）

    用于连接的传输协议。指定在 中mysql_protocol_type 定义的枚举值之一mysql.h。

  • MYSQL_OPT_READ_TIMEOUT（参数类型 unsigned int *：）

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

  • MYSQL_OPT_RECONNECT（参数类型 my_bool *：）

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

  • MYSQL_OPT_RETRY_COUNT（参数类型 unsigned int *：）

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

    此选项只能由链接到使用 NDB Cluster 支持编译的 C 客户端库的客户端使用。它从 MySQL NDB Cluster 7.5.1 开始可用。

  • 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_ENFORCE（参数类型 my_bool *：）

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

    从 MySQL 5.7.11 开始不推荐使用此选项，并在 MySQL 8.0 中删除。相反，使用 MYSQL_OPT_SSL_MODE值 SSL_MODE_REQUIRED.

  • 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 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 *：）

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

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

  • MYSQL_OPT_USE_EMBEDDED_CONNECTION （参数：未使用）

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

  • MYSQL_OPT_USE_REMOTE_CONNECTION （参数：未使用）

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

  • MYSQL_OPT_USE_RESULT（参数：未使用）

    此选项未使用。

  • MYSQL_OPT_WRITE_TIMEOUT（参数类型 unsigned int *：）

    每次尝试写入服务器的超时秒数。必要时会重试，因此总有效超时值是选项值的两倍。

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

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

  • MYSQL_SECURE_AUTH（参数类型 my_bool *：）

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

  • MYSQL_SERVER_PUBLIC_KEY（参数类型 char *：）

    PEM 格式文件的路径名，其中包含服务器所需的公钥客户端副本，用于基于 RSA 密钥对的密码交换。此选项适用于使用 sha256_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_SET_CLIENT_IP（参数类型 char *：）

    对于链接到 libmysqld嵌入式服务器库的应用程序（当 libmysqld编译时带有身份验证支持），此选项意味着用户被视为已从指定的 IP 地址（指定为字符串）进行连接以进行身份​​验证。libmysqlclient对于链接到客户端库 的应用程序，它会被忽略。

  • 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.54 节，“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));
}