MySQL :: MySQL 8.4 C API 开发者指南 :: 5.4.58 mysql_real_connect()

版本 8.4

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

5.4.58 mysql_real_connect()

MYSQL *
mysql_real_connect(MYSQL *mysql,
                   const char *host,
                   const char *user,
                   const char *passwd,
                   const char *db,
                   unsigned int port,
                   const char *unix_socket,
                   unsigned long client_flag)

描述

注意

mysql_real_connect() 是一个同步函数。其异步对应函数是 mysql_real_connect_nonblocking()，供需要与服务器进行异步通信的应用程序使用。请参阅第 7 章 C API 异步接口。

要使用 DNS SRV 记录进行连接，请使用 mysql_real_connect_dns_srv()。请参阅第 5.4.59 节 “mysql_real_connect_dns_srv()”。

mysql_real_connect() 尝试建立与运行在 host 上的 MySQL 服务器的连接。客户端程序必须先成功连接到服务器，然后才能执行任何其他需要有效 MYSQL 连接处理程序结构的 API 函数。

按如下方式指定参数

对于第一个参数，请指定现有 MYSQL 结构的地址。在调用 mysql_real_connect() 之前，请调用 mysql_init() 初始化 MYSQL 结构。您可以使用 mysql_options() 调用更改许多连接选项。请参阅第 5.4.54 节 “mysql_options()”。
host 的值可以是主机名或 IP 地址。客户端尝试按如下方式连接
- 如果 host 为 NULL 或字符串 "localhost"，则假定连接到本地主机
  - 在 Windows 上，如果服务器启用了共享内存连接，则客户端使用共享内存连接进行连接。
  - 在 Unix 上，客户端使用 Unix 套接字文件进行连接。unix_socket 参数或 MYSQL_UNIX_PORT 环境变量可用于指定套接字名称。
- 在 Windows 上，如果 host 为 "."，或者未启用 TCP/IP 且未指定 unix_socket 或主机为空，则客户端使用命名管道进行连接（如果服务器启用了命名管道连接）。如果未启用命名管道连接，则会发生错误。
- 否则，使用 TCP/IP。
您还可以使用 MYSQL_OPT_PROTOCOL 或 MYSQL_OPT_NAMED_PIPE 选项影响 mysql_options() 使用的连接类型。连接类型必须受服务器支持。
user 参数包含用户的 MySQL 登录 ID。如果 user 为 NULL 或空字符串 ""，则假定为当前用户。在 Unix 下，这是当前登录名。在 Windows ODBC 下，必须显式指定当前用户名。请参阅连接器和 API 的 Connector/ODBC 部分。
passwd 参数包含 user 的密码。如果 passwd 为 NULL，则仅检查 user 表中密码字段为空（空）的用户的条目是否匹配。这使数据库管理员能够设置 MySQL 权限系统，以便用户根据是否指定了密码获得不同的权限。

注意

不要尝试在调用 mysql_real_connect() 之前加密密码；密码加密由客户端 API 自动处理。
user 和 passwd 参数使用已为 MYSQL 对象配置的任何字符集。默认情况下，这是 utf8mb4，但可以通过在连接之前调用 mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "charset_name") 来更改。
db 是数据库名称。如果 db 不为 NULL，则连接会将默认数据库设置为该值。
如果 port 不为 0，则该值将用作 TCP/IP 连接的端口号。请注意，host 参数决定了连接的类型。
如果 unix_socket 不为 NULL，则该字符串指定要使用的套接字或命名管道。请注意，host 参数决定了连接的类型。
client_flag 的值通常为 0，但可以设置为以下标志的组合以启用某些功能
- CAN_HANDLE_EXPIRED_PASSWORDS：客户端可以处理过期的密码。有关更多信息，请参阅服务器对过期密码的处理。
- CLIENT_COMPRESS：在客户端/服务器协议中使用压缩。
- CLIENT_FOUND_ROWS：返回找到（匹配）的行数，而不是更改的行数。
- CLIENT_IGNORE_SIGPIPE：防止客户端库安装 SIGPIPE 信号处理程序。这可以用来避免与应用程序已安装的处理程序发生冲突。
- CLIENT_IGNORE_SPACE：允许在函数名后使用空格。使所有函数名都成为保留字。
- CLIENT_INTERACTIVE：允许在关闭连接之前 interactive_timeout 秒的不活动时间（而不是 wait_timeout 秒）。客户端的会话 wait_timeout 变量设置为会话 interactive_timeout 变量的值。
- CLIENT_LOCAL_FILES：启用 LOAD DATA LOCAL 处理。
- CLIENT_MULTI_RESULTS：告诉服务器客户端可以处理来自多语句执行或存储过程的多个结果集。如果启用了 CLIENT_MULTI_STATEMENTS，则会自动启用此标志。有关此标志的更多信息，请参阅此表后面的注释。
- CLIENT_MULTI_STATEMENTS：告诉服务器客户端可以在单个字符串中发送多个语句（用 ; 字符分隔）。如果未设置此标志，则禁用多语句执行。有关此标志的更多信息，请参阅此表后面的注释。
- CLIENT_NO_SCHEMA：不允许使用 db_name.tbl_name.col_name 语法。这是针对 ODBC 的。如果使用该语法，它会导致解析器生成错误，这对于捕获某些 ODBC 程序中的错误很有用。
  
  从 MySQL 8.0.32 开始，CLIENT_NO_SCHEMA 标志已弃用。客户端程序可以省略此标志和 db 参数，以使连接将数据库值设置为当前（或默认）数据库。
- CLIENT_ODBC：未使用。
- CLIENT_OPTIONAL_RESULTSET_METADATA：此标志使结果集元数据可选。抑制元数据传输可以提高性能，特别是对于执行许多查询且每个查询返回的行数很少的会话。有关管理结果集元数据传输的详细信息，请参阅第 3.6.7 节 “可选结果集元数据”。
- CLIENT_SSL：使用 SSL（加密协议）。不要在应用程序程序中设置此选项；它在客户端库中内部设置。请改用 mysql_options() 在调用 mysql_real_connect() 之前进行设置。
- CLIENT_REMEMBER_OPTIONS：记住由对 mysql_options() 的调用所指定的选项。如果没有此选项，如果 mysql_real_connect() 失败，则必须在再次尝试连接之前重复 mysql_options() 调用。使用此选项，则无需重复 mysql_options() 调用。

如果你的程序使用 CALL 语句执行存储过程，则必须启用 CLIENT_MULTI_RESULTS 标志。这是因为除了可能由过程中执行的语句返回的任何结果集之外，每个 CALL 都会返回一个结果以指示调用状态。由于 CALL 可以返回多个结果，因此请使用调用 mysql_next_result() 以确定是否有更多结果的循环来处理它们。

你可以在调用 mysql_real_connect() 时启用 CLIENT_MULTI_RESULTS，可以通过传递 CLIENT_MULTI_RESULTS 标志本身来显式启用，也可以通过传递 CLIENT_MULTI_STATEMENTS（它也会启用 CLIENT_MULTI_RESULTS）来隐式启用。默认情况下会启用 CLIENT_MULTI_RESULTS。

如果启用 CLIENT_MULTI_STATEMENTS 或 CLIENT_MULTI_RESULTS，请使用调用 mysql_next_result() 以确定是否有更多结果的循环来处理对 mysql_real_query() 或 mysql_query() 的每次调用的结果。有关示例，请参阅第 3.6.3 节，“多语句执行支持”。

对于某些参数，可以从选项文件中获取值，而不是从 mysql_real_connect() 调用中的显式值获取值。为此，请在调用 mysql_real_connect() 之前，使用 MYSQL_READ_DEFAULT_FILE 或 MYSQL_READ_DEFAULT_GROUP 选项调用 mysql_options()。然后，在 mysql_real_connect() 调用中，为要从选项文件中读取的每个参数指定 “无值” 值。

对于 host，指定值 NULL 或空字符串 ("")。
对于 user，指定值 NULL 或空字符串。
对于 passwd，指定值 NULL。（对于密码，mysql_real_connect() 调用中空字符串的值不能在选项文件中被覆盖，因为空字符串明确表示 MySQL 帐户必须具有空密码。）
对于 db，指定值 NULL 或空字符串。
对于 port，指定值 0。
对于 unix_socket，指定值 NULL。

如果在选项文件中没有找到参数的值，则使用其默认值，如本节前面所述。

返回值

如果连接成功，则返回 MYSQL* 连接处理程序；如果连接失败，则返回 NULL。对于成功的连接，返回值与第一个参数的值相同。

错误

CR_CONN_HOST_ERROR

无法连接到 MySQL 服务器。
CR_CONNECTION_ERROR

无法连接到本地 MySQL 服务器。
CR_IPSOCK_ERROR

无法创建 IP 套接字。
CR_OUT_OF_MEMORY

内存不足。
CR_SOCKET_CREATE_ERROR

无法创建 Unix 套接字。
CR_UNKNOWN_HOST

无法找到主机名的 IP 地址。
CR_VERSION_ERROR

尝试使用使用不同协议版本的客户端库连接到服务器时，导致协议不匹配。
CR_NAMEDPIPEOPEN_ERROR

无法在 Windows 上创建命名管道。
CR_NAMEDPIPEWAIT_ERROR

无法等待 Windows 上的命名管道。
CR_NAMEDPIPESETSTATE_ERROR

无法在 Windows 上获取管道处理程序。
CR_SERVER_LOST

如果 connect_timeout > 0 并且连接到服务器的时间超过 connect_timeout 秒，或者如果服务器在执行 init-command 时崩溃。
CR_ALREADY_CONNECTED

MYSQL 连接处理程序已连接。

示例

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
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));
}

通过使用 mysql_options()，MySQL 客户端库会读取 my.cnf 文件中的 [client] 和 [your_prog_name] 部分。这使你能够将选项添加到 [your_prog_name] 部分，以确保你的程序正常工作，即使有人以某种非标准方式设置了 MySQL。