(mysql.info.gz) mysql_real_connect
Info Catalog
(mysql.info.gz) mysql_query
(mysql.info.gz) C API functions
(mysql.info.gz) mysql_real_escape_string
22.2.3.46 `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 of the other API
functions, with the exception of `mysql_get_client_info()'.
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.
`mysql_options()' 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.
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 will be 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 or not 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
will set the default database to this value.
* If `port' is not 0, the value will be 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 in very special circumstances:
*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 will be 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. New in 4.1.
`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. New in
4.1.
`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.
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 will read the `[client]'
and `[your_prog_name]' sections in the `my.cnf' file which will ensure
that your program will work, 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 strictly older than 5.0.3, of `0' in newer versions. A value of
`1' for this flag indicates, in the event that a query cannot be
performed because of a lost connection, to try reconnecting to the
server before giving up.
Info Catalog
(mysql.info.gz) mysql_query
(mysql.info.gz) C API functions
(mysql.info.gz) mysql_real_escape_string
automatically generated byinfo2html