23.8.7.52 mysql_real_connect()

Description

mysql_real_connect() attempts to
establish a connection to a MySQL database engine running on
host.
mysql_real_connect() must
complete successfully before you can execute any other API
functions that require a valid MYSQL
connection handle structure.

The value of host may be either a host
name or an IP address. If host is
NULL or the string
"localhost", a connection to the local
host is assumed. For Windows, the client connects using a
shared-memory connection, if the server has shared-memory
connections enabled. Otherwise, TCP/IP is used. For Unix,
the client connects using a Unix socket file. For local
connections, you can also influence the type of connection
to use with the MYSQL_OPT_PROTOCOL or
MYSQL_OPT_NAMED_PIPE options to
mysql_options(). The type of
connection must be supported by the server. For a
host value of "." on
Windows, the client connects using a named pipe, if the
server has named-pipe connections enabled. If named-pipe
connections are not enabled, an error occurs.

The user parameter contains the user's
MySQL login ID. If user is
NULL or the empty string
"", the current user is assumed. Under
Unix, this is the current login name. Under Windows ODBC,
the current user name must be specified explicitly. See the
Connector/ODBC section of Chapter 23, Connectors and APIs.

The passwd parameter contains the
password for user. If
passwd is NULL, only
entries in the user table for the user
that have a blank (empty) password field are checked for a
match. This enables the database administrator to set up the
MySQL privilege system in such a way that users get
different privileges depending on whether they have
specified a password.

Note

Do not attempt to encrypt the password before calling
mysql_real_connect();
password encryption is handled automatically by the client
API.

Tell the server that the client can handle multiple result sets from
multiple-statement executions or stored procedures.
This flag is automatically enabled if
CLIENT_MULTI_STATEMENTS is
enabled. See the note following this table for more
information about this flag.

CLIENT_MULTI_STATEMENTS

Tell the server that the client may send multiple statements in a single
string (separated by ;
characters). If this flag is not set,
multiple-statement execution is disabled. See the
note following this table for more information about
this flag.

CLIENT_NO_SCHEMA

Do not permit db_name.tbl_name.col_name
syntax. This is for ODBC. It causes the parser to
generate an error if you use that syntax, which is
useful for trapping bugs in some ODBC programs.

CLIENT_ODBC

Unused.

CLIENT_SSL

Use SSL (encrypted protocol). Do not set this option within an
application program; it is set internally in the
client library. Instead, use
mysql_ssl_set()
before calling
mysql_real_connect().

If your program uses CALL
statements to execute stored procedures, the
CLIENT_MULTI_RESULTS flag must be enabled.
This is because each CALL returns
a result to indicate the call status, in addition to any result
sets that might be returned by statements executed within the
procedure. Because CALL can
return multiple results, process them using a loop that calls
mysql_next_result() to determine
whether there are more results.

CLIENT_MULTI_RESULTS can be enabled when you
call mysql_real_connect(),
either explicitly by passing the
CLIENT_MULTI_RESULTS flag itself, or
implicitly by passing CLIENT_MULTI_STATEMENTS
(which also enables CLIENT_MULTI_RESULTS). As
of MySQL 5.5.3, CLIENT_MULTI_RESULTS is
enabled by default.

For some parameters, it is possible to have the value taken from
an option file rather than from an explicit value in the
mysql_real_connect() call. To do
this, call mysql_options() with
the MYSQL_READ_DEFAULT_FILE or
MYSQL_READ_DEFAULT_GROUP option before
calling mysql_real_connect().
Then, in the
mysql_real_connect() call,
specify the “no-value” value for each parameter to
be read from an option file:

For host, specify a value of
NULL or the empty string
("").

For user, specify a value of
NULL or the empty string.

For passwd, specify a value of
NULL. (For the password, a value of the
empty string in the
mysql_real_connect() call
cannot be overridden in an option file, because the empty
string indicates explicitly that the MySQL account must have
an empty password.)

For db, specify a value of
NULL or the empty string.

For port, specify a value of 0.

For unix_socket, specify a value of
NULL.

If no value is found in an option file for a parameter, its
default value is used as indicated in the descriptions given
earlier in this section.

Return Values

A MYSQL* connection handle if the connection
was successful, NULL if the connection was
unsuccessful. For a successful connection, the return value is
the same as the value of the first parameter.

By using mysql_options() the
MySQL library reads the [client] and
[your_prog_name] sections in the
my.cnf file which ensures that your program
works, even if someone has set up MySQL in some nonstandard way.

Upon connection,
mysql_real_connect() sets the
reconnect flag (part of the
MYSQL structure) to a value of
1 in versions of the API older than 5.0.3, or
0 in newer versions. A value of
1 for this flag indicates that if a statement
cannot be performed because of a lost connection, to try
reconnecting to the server before giving up. You can use the
MYSQL_OPT_RECONNECT option to
mysql_options() to control
reconnection behavior.

If you have configured your DNS to return a list of MySQL servers, and you want your client to work through that list until it finds one that works, you can put real_connect inside a getaddrinfo() loop. I wish the client library did it by itself: