27.7.6.54 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)
Description
mysql_real_connect()尝试构建与在host上运行的 MySQL 服务器的连接。在执行需要有效MYSQL连接处理程序结构的任何其他 API 函数之前，Client 端程序必须成功连接到服务器。
指定参数，如下所示：
-
对于第一个参数，请指定现有
MYSQL结构的地址。在调用mysql_real_connect()之前，请调用mysql_init()初始化MYSQL结构。您可以通过mysql_options()调用更改许多连接选项。参见第 27.7.6.50 节“ mysql_options()”。 -
host的值可以是主机名或 IP 地址。Client 端尝试如下连接： -
如果
host为NULL或字符串"localhost"，则假定与 localhost 的连接： -
在 Windows 上，如果服务器启用了共享内存连接，则 Client 端将使用共享内存连接进行连接。
-
在 Unix 上，Client 端使用 Unix 套接字文件进行连接。
unix_socket参数或MYSQL_UNIX_PORT环境变量可用于指定套接字名称。 -
在 Windows 上，如果
host为"."，或者未启用 TCP/IP 且未指定unix_socket或主机为空，则如果服务器启用了命名管道连接，则 Client 端将使用命名管道进行连接。如果未启用命名管道连接，则会发生错误。 -
否则，将使用 TCP/IP。
-
您还可以影响mysql_options()的MYSQL_OPT_PROTOCOL或MYSQL_OPT_NAMED_PIPE选项使用的连接类型。服务器必须支持连接类型。
-
user参数包含用户的 MySQL 登录 ID。如果user是NULL或空字符串""，则假定为当前用户。在 Unix 下，这是当前的登录名。在 Windows ODBC 下，必须显式指定当前用户名。请参阅第 27 章，连接器和 API的连接器/ ODBC 部分。 -
passwd参数包含user的密码。如果passwd为NULL，则仅检查用户在usertable 中具有空白(空)密码字段的条目是否匹配。这使数据库 Management 员可以通过以下方式设置 MySQL 特权系统：根据用户是否指定了密码，他们可以获得不同的特权。
Note
请勿在致电mysql_real_connect()之前尝试对密码进行加密；密码加密由 Client 端 API 自动处理。
-
user和passwd参数使用为MYSQL对象配置的任何字符集。默认情况下，它是latin1，但是可以在连接之前通过调用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 端可以处理过期的密码。有关更多信息，请参见第 6.2.12 节“过期密码的服务器处理”。-
CLIENT_COMPRESS：在 Client 端/服务器协议中使用压缩。 -
CLIENT_FOUND_ROWS：返回找到(匹配)的行数，而不是更改的行数。 -
CLIENT_IGNORE_SIGPIPE：防止 Client 端库安装SIGPIPEsignal 处理程序。这可以用来避免与应用程序已经安装的处理程序发生冲突。
-
-
CLIENT_IGNORE_SPACE：函数名称后的空格。使所有函数名称保留字。 -
CLIENT_INTERACTIVE：允许关闭连接前interactive_timeout秒钟(而不是wait_timeout秒钟)不活动。Client 端的会话wait_timeout变量设置为会话interactive_timeout变量的值。 -
CLIENT_LOCAL_FILES：启用本地加载数据处理。 -
CLIENT_MULTI_RESULTS：告诉服务器 Client 端可以处理来自多个语句执行或存储过程的多个结果集。如果启用了CLIENT_MULTI_STATEMENTS，则会自动启用此标志。有关此标志的更多信息，请参见此 table 后面的 Comments。 -
CLIENT_MULTI_STATEMENTS：告诉服务器 Client 端可以在单个字符串(由;个字符分隔)中发送多个语句。如果未设置此标志，则禁用多语句执行。有关此标志的更多信息，请参见此 table 后面的 Comments。 -
CLIENT_NO_SCHEMA不允许*db_name.tbl_name.col_name*语法。这是用于 ODBC 的。如果使用该语法，它将导致解析器生成错误，这对于捕获某些 ODBC 程序中的错误很有用。 -
CLIENT_ODBC：未使用。 -
CLIENT_SSL：使用 SSL(加密协议)。不要在应用程序中设置此选项。它在 Client 端库中内部设置。相反，请在调用mysql_real_connect()之前使用mysql_options()或mysql_ssl_set()。 -
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)。在 MySQL 5.7 中，默认启用CLIENT_MULTI_RESULTS。
如果启用CLIENT_MULTI_STATEMENTS或CLIENT_MULTI_RESULTS，则使用调用mysql_next_result()的循环来确定是否有更多结果，从而处理对mysql_query()或mysql_real_query()的每次调用的结果。有关示例，请参见第 27.7.15 节“ C API 多语句执行支持”。
对于某些参数，可以从选项文件中获取值，而不是从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()调用中空字符串的值，因为该空字符串明确 table 示 MySQL 帐户必须具有空密码。) -
对于
db，指定值NULL或空字符串。 -
对于
port，将值指定为 0. -
对于
unix_socket，将值指定为NULL。
如果在选项文件中找不到自变量的值，则使用默认值，如本节前面的描述所示。
Return Values
如果连接成功，则为MYSQL*连接处理程序；如果连接失败，则为NULL。对于成功的连接，返回值与第一个参数的值相同。
Errors
无法连接到 MySQL 服务器。
无法连接到本地 MySQL 服务器。
无法创建 IP 套接字。
记不清。
创建 Unix 套接字失败。
找不到主机名的 IP 地址。
尝试通过使用使用其他协议版本的 Client 端库连接到服务器导致协议不匹配。
在 Windows 上无法创建命名管道。
无法在 Windows 上 await 命名管道。
无法在 Windows 上获取管道处理程序。
如果connect_timeout> 0，并且连接服务器花费的时间超过connect_timeout秒，或者服务器在执行init-command时死了。
MYSQL连接处理程序已连接。
Example
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()，MySQLClient 端库读取my.cnf文件中的[client]和[your_prog_name]部分。这使您可以向[your_prog_name]部分添加选项，以确保您的程序正常运行，即使有人以某种非标准方式设置了 MySQL。
