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
MYSQLstructure. Before callingmysql_real_connect()you must callmysql_init()to initialize theMYSQLstructure. You can change a lot of connect options with themysql_options()call. See Section 22.9.3.49, “mysql_options()”.The value of
hostmay be either a host name or an IP address. IfhostisNULLor 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 theMYSQL_OPT_PROTOCOLorMYSQL_OPT_NAMED_PIPEoptions tomysql_options(). The type of connection must be supported by the server. For ahostvalue 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
userparameter contains the user's MySQL login ID. IfuserisNULLor 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 22, Connectors and APIs.The
passwdparameter contains the password foruser. IfpasswdisNULL, only entries in theusertable 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.NoteDo not attempt to encrypt the password before calling
mysql_real_connect(); password encryption is handled automatically by the client API.The
userandpasswdparameters use whatever character set has been configured for theMYSQLobject. By default, this islatin1, but can be changed by callingmysql_options(mysql, MYSQL_SET_CHARSET_NAME, "prior to connecting.charset_name")dbis the database name. Ifdbis notNULL, the connection sets the default database to this value.If
portis not 0, the value is used as the port number for the TCP/IP connection. Note that thehostparameter determines the type of the connection.If
unix_socketis notNULL, the string specifies the socket or named pipe that should be used. Note that thehostparameter determines the type of the connection.The value of
client_flagis usually 0, but can be set to a combination of the following flags to enable certain features.Flag Name Flag Description CLIENT_COMPRESSUse compression protocol. CLIENT_FOUND_ROWSReturn the number of found (matched) rows, not the number of changed rows. CLIENT_IGNORE_SIGPIPEPrevents the client library from installing a SIGPIPEsignal handler. This can be used to avoid conflicts with a handler that the application has already installed.CLIENT_IGNORE_SPACEPermit spaces after function names. Makes all functions names reserved words. CLIENT_INTERACTIVEPermit interactive_timeoutseconds (instead ofwait_timeoutseconds) of inactivity before closing the connection. The client's sessionwait_timeoutvariable is set to the value of the sessioninteractive_timeoutvariable.CLIENT_LOCAL_FILESEnable LOAD DATA LOCALhandling.CLIENT_MULTI_RESULTSTell 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_STATEMENTSis enabled. See the note following this table for more information about this flag.CLIENT_MULTI_STATEMENTSTell 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_SCHEMADo not permit the db_name.tbl_name.col_namesyntax. 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_ODBCUnused. CLIENT_SSLUse 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 callingmysql_real_connect().CLIENT_REMEMBER_OPTIONSRemember options specified by calls to mysql_options(). Without this option, ifmysql_real_connect()fails, you must repeat themysql_options()calls before trying to connect again. With this option, themysql_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 22.9.13, “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 ofNULLor the empty string ("").For
user, specify a value ofNULLor the empty string.For
passwd, specify a value ofNULL. (For the password, a value of the empty string in themysql_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 ofNULLor the empty string.For
port, specify a value of 0.For
unix_socket, specify a value ofNULL.
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 thanconnect_timeoutseconds to connect to the server or if the server died while executing theinit-command.The
MYSQLconnection 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.