20.4.40 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)

20.4.40.1 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:@:

• mysql is a pointer to a MYSQL connection structure, or NULL. If mysql is NULL, the C API allocates memory for the connection structure automatically and frees it when you call mysql_close(). The disadvantage of this approach is that you can't retrieve an error message if the connection fails. (To get error information from mysql_errno() or mysql_error(), you must provide a valid MYSQL pointer.) If the first parameter is not NULL, it should be the address of an existing MYSQL structure. In this case, before calling mysql_real_connect() you must call mysql_init() to initialize the MYSQL structure. See the example below.
• 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 (Win32), 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. 16.4 Comment remplir les différents champs du gestionnaire ODBC.
• 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 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
  CLIENT_FOUND_ROWS	Return the number of found rows, not the number of affected rows
  CLIENT_NO_SCHEMA	Don't allow the nom_base_de_donnees.nom_table.nom_colonne syntax. This is for ODBC; it causes the parser to generate an error if you use that syntax, which is is useful for trapping bugs in some ODBC programs.
  CLIENT_COMPRESS	Use compression protocol
  CLIENT_ODBC	The client is an ODBC client. This changes mysqld to be more ODBC-friendly.

20.4.40.2 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, unless you pass NULL for that parameter.

20.4.40.3 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 Win32.

CR_NAMEDPIPEWAIT_ERROR;

Failed to wait for a named pipe on Win32.

CR_NAMEDPIPESETSTATE_ERROR;

Failed to get a pipe handler on Win32.

20.4.40.4 Example

MYSQL mysql;

mysql_init(&mysql);
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
fprintf(stderr, "Failed to connect to database:@: Error: %sn",
mysql_error(&mysql));
}