mysql.h

Función mysql_real_connect()

MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *usuario, const char *password, 
   const char *database, unsigned int puerto, const char *unix_socket, unsigned long client_flag);

mysql_real_connect intenta establecer una conexión con un motor de bases de datos MySQL ejecutándose en host. mysql_real_connect debe completarse con éxito antes de que se puedan ejecutar otras funciones del API, con la excepción de mysql_get_client_info.

Los parámetros a especificar son los siguientes:

mysql: El primer parámetro debe ser la dirección de una estructura MYSQL existente. Antes de llamar a mysql_real_connect se debe llamar a mysql_init para inicializar la estructura MYSQL. Se pueden modificar muchas opciones de conexión mediante la función mysql_options.
host: El valor de host puede ser tanto un nombre como una dirección IP. Si host es NULL o la cadena "localhost", se asume que se trata de una conexión al host local. Si el sistema operativo soporta sockets (Unix) o tuberías con nombre (Windows), se en lugar del protocolo TCP/IP para conectar con el servidor.
usuario: contiene el identificador de login del usuario MySQL. Si el user es NULL o una cadena vacía "", se asume el usuario actual. Bajo Unix, es el nombre de login actual. Bajo Windows ODBC, el nombre de usuario debe especificarse explícitamente.
password contiene el password del usuario. Si es NULL, sólo se verificarán usuarios de la tabla que tengan como password una cadena vacía. Esto permite al administrador de la base de datos configurar el sistema de privilegios de MySQL de modo que existan usuarios con diferentes privilegios dependiendo del password especificado. Nota: no se debe intentar encriptar el password antes de llamar a mysql_real_connect; la encriptación del password se hace automáticamente por el API del cliente.
database es el nombre de la base de datos. Si database no es NULL, la conexión hará que esa sea la base de datos por defecto.
puerto si no es 0, el valor se usará como número de puerto en la conexión TCP/IP. Hay que tener en cuenta que el parámetro host determina el tipo de conexión.
unix_socket si no es NULL, la cadena especifica el socket o tubería con nombre que se usará. Hay que tener en cuenta que el parámetro host determina el tipo de conexión.
client_flag es normalmente 0, pero puede usarse una combinación de los siguientes flags en circunstancias muy especiales:

Flag Descripción

CLIENT_COMPRESS Usar un protocolo de compresión.

CLIENT_FOUND_ROWS Devuelve el número de líneas encontradas (coincidentes) en lugar del número de líneas afectadas.

CLIENT_IGNORE_SPACE Permite espacios después de los nombres de función. Hace de todos los nombres de función palabras reservadas.

CLIENT_INTERACTIVE Permite segundos "interactive_timeout" (en lugar de segundos "wait_timeout") de inactividad antes de cerrar la conexión.

CLIENT_LOCAL_FILES Permite manipulación LOAD DATA LOCAL.

CLIENT_MULTI_STATEMENTS Informa al servidor de que el cliente puede enviar consultas multilínea (separadas con `;'). Si este flag no se activa, las consultas multilínea serán desactivadas. Nuevo en versión 4.1.

CLIENT_MULTI_RESULTS Informa al servidor de que el cliente puede manipular conjuntos de resultados multiples procedentes de multi-consultas o procedimientos almacenados. Esto es agrupado automáticamente si CLIENT_MULTI_STATEMENTS es activado. Nuevo en 4.1.

CLIENT_NO_SCHEMA No permite la sintaxis db_name.tbl_name.col_name. Esto es para ODBC. Hace que el analizador sintáctico genere un error si se usa tal sintaxis, lo que resulta útil para encontrar errores en algunos programas ODBC.

CLIENT_ODBC El cliente es un cliente ODBC. Esto hace que mysqld se adapte más a ODBC.

CLIENT_SSL Usar SSL (protocolo de encriptado). Esta opción no debe ser activada por aplicaciones; se activa internamente por la biblioteca del cliente.

Flag	Descripción
CLIENT_COMPRESS	Usar un protocolo de compresión.
CLIENT_FOUND_ROWS	Devuelve el número de líneas encontradas (coincidentes) en lugar del número de líneas afectadas.
CLIENT_IGNORE_SPACE	Permite espacios después de los nombres de función. Hace de todos los nombres de función palabras reservadas.
CLIENT_INTERACTIVE	Permite segundos "interactive_timeout" (en lugar de segundos "wait_timeout") de inactividad antes de cerrar la conexión.
CLIENT_LOCAL_FILES	Permite manipulación LOAD DATA LOCAL.
CLIENT_MULTI_STATEMENTS	Informa al servidor de que el cliente puede enviar consultas multilínea (separadas con `;'). Si este flag no se activa, las consultas multilínea serán desactivadas. Nuevo en versión 4.1.
CLIENT_MULTI_RESULTS	Informa al servidor de que el cliente puede manipular conjuntos de resultados multiples procedentes de multi-consultas o procedimientos almacenados. Esto es agrupado automáticamente si CLIENT_MULTI_STATEMENTS es activado. Nuevo en 4.1.
CLIENT_NO_SCHEMA	No permite la sintaxis db_name.tbl_name.col_name. Esto es para ODBC. Hace que el analizador sintáctico genere un error si se usa tal sintaxis, lo que resulta útil para encontrar errores en algunos programas ODBC.
CLIENT_ODBC	El cliente es un cliente ODBC. Esto hace que mysqld se adapte más a ODBC.
CLIENT_SSL	Usar SSL (protocolo de encriptado). Esta opción no debe ser activada por aplicaciones; se activa internamente por la biblioteca del cliente.

Valores de retorno

Si la conexión ha tenido éxito, el valor de retorno es un manipulador de conexión MYSQL*, NULL si la conexión no ha tenido éxito. Para una conexión exitosa, el valor de retorno es el mismo que el valor del primer parámetro.

Errores

CR_CONN_HOST_ERROR: fallo al conectar con el servidor MySQL.

CR_CONNECTION_ERROR: fallo al conectar al servidor local MySQL.

CR_IPSOCK_ERROR: fallo al crear un socket IP.

CR_OUT_OF_MEMORY: falta memoria.

CR_SOCKET_CREATE_ERROR: fallo al crear un socket Unix.

CR_UNKNOWN_HOST: fallo al encontrar una dirección IP para el nombre de host.

CR_VERSION_ERROR: al intentar conectar con el servidor se ha producido un error de protocolo por el uso de una biblioteca de cliente que usa un protocolo de una versión diferente. Esto puede ocurrir si se usa una biblioteca de cliente muy antigua para conectarse con un servidor que no se ha arrancado con la opción "--old-protocol".

CR_NAMEDPIPEOPEN_ERROR: fallo al crear una tubería con nombre en Windows.

CR_NAMEDPIPEWAIT_ERROR: fallo al esperar uan tubería con nombre en Windows.

CR_NAMEDPIPESETSTATE_ERROR: fallo al tomar un manipulador de tubería en Windows.

CR_SERVER_LOST: si el connect_timeout > 0 y se tarda más de connect_timeout segundos en conectar con el servidor o si el servidor ha muerto mientras se ejecuta el comando de inicialización.

Ejemplo

 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, "Fallo al conectar con la base de datos: Error: %s\n",
           mysql_error(&mysql));
 }

Mediante el uso de mysql_options() la biblioteca MySQL leerá las secciones [client] y [your_prog_name] del fichero 'my.cnf', lo que asegura que el programa funcionará, aunque alquien haya arrancado MySQL de algún modo no estándar.

Notar que una vez conectado, mysql_real_connect() activa la opción de reconexión (parte de la estructura MYSQL) a un valor de 1 en versiones del API anteriores a 5.0.3, y de 0 en versiones más recientes. Un valor 1 para esta opción indica, en el caso de que una consulta no pueda ser completada por una pérdida de conexión, se intente reconectar al servidor antes de abandonar.