GNU Info
(mysql.info)mysql_real_connect
`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 int 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. Note:
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', the current user is assumed. Under Unix, this is
the current login name. Under Windows ODBC, the current user name
must be specified explicitly. Note: ODBC administrator.
* 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 meaning* `mysqld' to be more
ODBC-friendly.
`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.
`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
`CLIENT_SSL' Use SSL (encrypted protocol).
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 then `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'. 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.
automatically generated by info2www version 1.2.2.9