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 21.9.3.49, “mysql_options()
”.
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
MyODBC section of Chapter 21, 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 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.
Do not attempt to encrypt the password before calling
mysql_real_connect()
;
password encryption is handled automatically by the client
API.
The user
and passwd
parameters use whatever character set has been configured
for the MYSQL
object. By default, this is
latin1
, but can be changed by calling
mysql_options(mysql,
MYSQL_SET_CHARSET_NAME,
"
prior
to connecting.
charset_name
")
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.
Flag Name | Flag Description |
CLIENT_COMPRESS |
Use compression protocol. |
CLIENT_FOUND_ROWS |
Return the number of found (matched) rows, not the number of changed rows. |
CLIENT_IGNORE_SIGPIPE |
Prevents the client library from installing a SIGPIPE
signal handler. This can be used to avoid conflicts
with a handler that the application has already
installed. |
CLIENT_IGNORE_SPACE |
Allow spaces after function names. Makes all functions names reserved words. |
CLIENT_INTERACTIVE |
Allow interactive_timeout seconds
(instead of
wait_timeout
seconds) of inactivity before closing the
connection. The client's session
wait_timeout
variable is set to the value of the session
interactive_timeout
variable. |
CLIENT_LOCAL_FILES |
Enable LOAD DATA
LOCAL handling. |
CLIENT_MULTI_RESULTS |
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
“; ”). 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 allow the 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). This option should not be set by
application programs; it is set internally in the
client library. Instead, use
mysql_ssl_set()
before calling
mysql_real_connect() . |
CLIENT_REMEMBER_OPTIONS |
Remember options specified by calls to
mysql_options() .
Without this option, if
mysql_real_connect()
fails, you must repeat the
mysql_options()
calls before trying to connect again. With this
option, the
mysql_options()
calls need not be repeated. |
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, you should 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.
If you enable CLIENT_MULTI_STATEMENTS
or
CLIENT_MULTI_RESULTS
, you should process the
result for every call to
mysql_query()
or
mysql_real_query()
by using a
loop that calls
mysql_next_result()
to determine
whether there are more results. For an example, see
Section 21.9.12, “C API Support for Multiple Statement Execution”.
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
Failed to connect to the MySQL server.
Failed to connect to the local MySQL server.
Failed to create an IP socket.
Out of memory.
Failed to create a Unix socket.
Failed to find the IP address for the host name.
A protocol mismatch resulted from attempting to connect to a server with a client library that uses a different protocol version.
Failed to create a named pipe on Windows.
Failed to wait for a named pipe on Windows.
Failed to get a pipe handler on Windows.
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
.
The MYSQL
connection handle is already
connected.
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 nonstandard 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. You can use the
MYSQL_OPT_RECONNECT
option to
mysql_options()
to control
reconnection behavior.
User Comments
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:
struct addrinfo *addr, *addrlist;
struct addrinfo hints = {0, PF_UNSPEC, SOCK_STREAM,
0, 0, 0, 0, 0};
int gai_result = getaddrinfo(host, 0, &hints, &addrlist);
if (gai_result) bomb(Unknown host);
for (addr = addrlist; addr; addr = addr->ai_next) {
#define IPNAMELEN 20
char ipnamebuff[IPNAMELEN];
const char *ipname = inet_ntop(((struct sockaddr_in *) addr->ai_addr) ->sin_family,
(void *)&((struct sockaddr_in *) addr->ai_addr) ->sin_addr,
ipnamebuff, IPNAMELEN-1);
mysql_real_connect(mysql, ipname, user, pass, database, ...);
}
Andrew,
I believe this has been done, or will be done in 6.0.
Cheers,
-Brian
Add your own comment.