Documentation Home
MySQL 8.0 C API 开发者指南

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()尝试与运行在 上的 MySQL 服务器建立连接 host。在执行任何其他需要有效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指定 no 或主机为空，则如果服务器启用了命名管道连接，则客户端使用命名管道进行连接。如果未启用命名管道连接，则会发生错误。

    • 否则，使用 TCP/IP。

    MYSQL_OPT_PROTOCOL您还可以通过或 的MYSQL_OPT_NAMED_PIPE选项 影响要使用的连接类型mysql_options()。服务器必须支持连接类型。

  • 该user参数包含用户的 MySQL 登录 ID。如果user是 NULL或空字符串 ""，则假定为当前用户。在 Unix 下，这是当前的登录名。在 Windows ODBC 下，必须明确指定当前用户名。请参阅连接器和 API的连接器/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 程序中的错误很有用。

    • CLIENT_ODBC： 没用过。

    • CLIENT_OPTIONAL_RESULTSET_METADATA：此标志使结果集元数据可选。抑制元数据传输可以提高性能，特别是对于执行许多查询且每个查询返回几行的会话而言。有关管理结果集元数据传输的详细信息，请参阅 第 3.6.7 节，“可选结果集元数据”。

    • CLIENT_SSL: 使用 SSL（加密协议）。不要在应用程序中设置此选项；它在客户端库内部设置。相反， 在调用之前 使用mysql_options()or 。 mysql_ssl_set()mysql_real_connect()

    • CLIENT_REMEMBER_OPTIONS: 记住调用指定的选项 mysql_options()。如果没有此选项，如果 mysql_real_connect() 失败，您必须 mysql_options()在尝试再次连接之前重复调用。使用此选项， mysql_options()无需重复调用。

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

CLIENT_MULTI_RESULTS可以在调用时启用mysql_real_connect()，可以显式地传递 CLIENT_MULTI_RESULTS标志本身，也可以隐式地传递 CLIENT_MULTI_STATEMENTS（这也启用 CLIENT_MULTI_RESULTS）。 CLIENT_MULTI_RESULTS默认情况下启用。

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

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

  • 对于host，指定一个值 NULL或空字符串 ( "")。

  • 对于user，指定一个值 NULL或空字符串。

  • 对于passwd，指定一个值 NULL。（对于密码， mysql_real_connect()调用中的空字符串的值不能在选项文件中被覆盖，因为空字符串明确表示MySQL帐户必须有一个空密码。）

  • 对于db，指定一个值 NULL或空字符串。

  • 对于port，指定值 0。

  • 对于unix_socket，指定一个值 NULL。

如果在参数的选项文件中未找到任何值，则使用其默认值，如本节前面给出的描述中所示。

返回值

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

错误

例子

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 客户端库读取文件中的[client]和 [your_prog_name]部分 my.cnf。这使您能够向该[your_prog_name]部分添加选项以确保您的程序工作，即使有人以某种非标准方式设置了 MySQL。