25.2.3.51. 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() 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 parameters are specified as follows:
The first parameter should be the address of an existing
MYSQL structure. Before calling
mysql_real_connect() you must call
mysql_init() to initialize the
MYSQL structure. You can change a lot
of connect options with the
mysql_options() call. See
Section 25.2.3.48, “mysql_options()”.
The value of host may be either a
hostname or an IP address. If host is
NULL or the string
"localhost", a connection to the local
host is assumed. If the OS supports sockets (Unix) or
named pipes (Windows), they are used instead of TCP/IP to
connect to the server.
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 username must be specified explicitly. See
Section 26.1.9.2, “Configuring a MyODBC DSN on Windows”.
-
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 allows 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.
db is the database name. If
db is not NULL, the
connection sets the default database to this value.
If port is not 0, the value is used as
the port number for the TCP/IP connection. Note that the
host parameter determines the type of
the connection.
If unix_socket is not
NULL, the string specifies the socket
or named pipe that should be used. Note that the
host parameter determines the type of
the connection.
-
The value of client_flag is usually 0,
but can be set to a combination of the following flags to
enable certain features:
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.
Errors
-
CR_CONN_HOST_ERROR
Failed to connect to the MySQL server.
-
CR_CONNECTION_ERROR
Failed to connect to the local MySQL server.
-
CR_IPSOCK_ERROR
Failed to create an IP socket.
-
CR_OUT_OF_MEMORY
Out of memory.
-
CR_SOCKET_CREATE_ERROR
Failed to create a Unix socket.
-
CR_UNKNOWN_HOST
Failed to find the IP address for the hostname.
-
CR_VERSION_ERROR
A protocol mismatch resulted from attempting to connect to
a server with a client library that uses a different
protocol version. This can happen if you use a very old
client library to connect to a new server that wasn't
started with the --old-protocol option.
-
CR_NAMEDPIPEOPEN_ERROR
Failed to create a named pipe on Windows.
-
CR_NAMEDPIPEWAIT_ERROR
Failed to wait for a named pipe on Windows.
-
CR_NAMEDPIPESETSTATE_ERROR
Failed to get a pipe handler on Windows.
-
CR_SERVER_LOST
If connect_timeout > 0 and it took
longer than connect_timeout seconds to
connect to the server or if the server died while
executing the init-command.
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));
}
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
non-standard way.
Note that 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. As of MySQL
5.0.13, you can use the MYSQL_OPT_RECONNECT
option to mysql_options() to control
reconnection behavior.
