(mysql.info) mysql-real-connect
Info Catalog
(mysql.info) mysql-query
(mysql.info) c-api-functions
(mysql.info) mysql-real-escape-string
22.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
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
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.
`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:
*Flag Name* *Flag Description*
`CLIENT_COMPRESS' Use compression protocol.
`CLIENT_FOUND_ROWS' Return the number of found (matched) rows,
not the number of affected rows.
`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_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.
`CLIENT_MULTI_RESULTS'Tell the server that the client can handle
multiple result sets from
multiple-statement executions or stored
procedures. This is automatically set if
`CLIENT_MULTI_STATEMENTS' is set.
`CLIENT_NO_SCHEMA' Don't 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' The client is an ODBC client. This changes
`mysqld' to be more ODBC-friendly.
`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()'.
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.
Info Catalog
(mysql.info) mysql-query
(mysql.info) c-api-functions
(mysql.info) mysql-real-escape-string
automatically generated byinfo2html