Skip navigation links
24.2.3.47 mysql_real_escape_string() »
Section Navigation      [Toggle]

24.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() essaye de se connecter à une base de données MySQL tournant sur l'hôte. mysql_real_connect() doit se terminer correctement avant que vous ne puissiez aucune autre fonction de l'API, à l'exception de mysql_get_client_info().

Les paramètres sont spécifiés comme suit :

  • Le premier paramètre doit être l'adresse d'une structure MYSQL existante. Avant d'appeler mysql_real_connect() vous devez appeler mysql_init() pour initialiser la structure MYSQL. Vous pouvez changer un tas d'options de connexion en appelant mysql_options(). See Section 24.2.3.43, « mysql_options() ».

  • La valeur de host peut être un nom de domaine ou une adresse IP. Si host est NULL ou égal à la chaîne "localhost", une connexion à la machine local est essayée. Si le système supporte les sockets (Unix) ou les tunnels nommés (Windows), elles sont utilisées au lieu de TCP/IP pour se connecter au serveur.

  • La paramètre user contient l'identifiant MySQL de l'utilisateur. Si user est NULL, l'utilisateur courant est sous-entendu. Avec Unix c'est l'utilisateur courant. Avec Windows ODBC, le nom de l'utilisateur courant doit être spécifié explicitement. See Section 25.1.9.2, « Configuration du DSN MyODBC sur Windows ».

  • La paramètre passwd contient le mot de passe de user. Si passwd est NULL, seules les entrées de la table user pour l'utilisateur ayant un champ vide seront testées. Cela permet à l'administrateur de mettre en place le système de privilèges MySQL de fa¸on à ce que les utilisateurs aient divers privilèges selon qu'ils aient spécifié ou pas de mot de passe.

    Note : N'essayez pas d'encrypter le mot de passe avant l'appel à mysql_real_connect(); l'encryptage du mot de passe est gérée automatiquement par l'API du client.

  • db est le nom de la base de données. Si db n'est pas NULL, la connexion changera la base par défaut en cette valeur.

  • Si port est différent de 0, sa valeur sera utilisé comme port de connexion TCP/IP. Notez que le paramètre host détermine le type de la connexion.

  • Si unix_socket n'est pas NULL, la chaîne spécifie la socket ou le tunnel nommé à utiliser. Notez que le paramètre host détermine le type de la connexion.

  • La valeur de client_flag est habituellement 0, mais peut être la combinaison des options suivantes dans des circonstances très spéciales :

    Nom de l'option Description
    CLIENT_COMPRESS Utilise le protocole compressé.
    CLIENT_FOUND_ROWS Retourne le nombre de lignes trouvées, et non de lignes affectées.
    CLIENT_IGNORE_SPACE Autorise les espaces après les noms de fonctions. Rend tous les noms de fonctions des mots réservés.
    CLIENT_INTERACTIVE Autorise interactive_timeout secondes (au lieu de wait_timeout secondes) d'innactivité avant de fermer la connexion.
    CLIENT_LOCAL_FILES Active le support de LOAD DATA LOCAL.
    CLIENT_MULTI_STATEMENTS Indique au serveur que le client peut envoyer des requêtes multiples (séparées par des ‘;’). Si cette option n'est pas configurée, les commandes multiples sont désactivées. Nouveau en 4.1.
    CLIENT_MULTI_RESULTS Indique au serveru que le client peut gérer des jeux de résultats multiples, issus de commandes multiples, ou de procédures stockées. C'est automatique si l'option CLIENT_MULTI_STATEMENTS est active. Nouveau en 4.1.
    CLIENT_NO_SCHEMA N'autorise pas la syntaxe db_name.tbl_name.col_name. Cela est fait pour ODBC. Il fait génèrer une erreur à l'analyseur si vous utilisez cette syntaxe, ce qui peut se réveler fort utile pour la chasse aux bogues dans les programmes ODBC.
    CLIENT_ODBC Le client est un client ODBC. Cela rend mysqld plus accueillant vis à vis de ODBC.
    CLIENT_SSL Utilise SSL (protocole encrypté).

Valeur de retour

Un gestionnaire de connexion MYSQL* si la connexion a réussi, NULL si elle a échoué. Pour une connexion à succès, la valeur de retour est la même que la valeur du premier paramètre.

Erreurs

  • CR_CONN_HOST_ERROR

    Impossible de se connecter au serveur MySQL.

  • CR_CONNECTION_ERROR

    Impossible de se connecter au serveur MySQL local.

  • CR_IPSOCK_ERROR

    Impossible de créer une socket IP.

  • CR_OUT_OF_MEMORY

    Plus de mémoire.

  • CR_SOCKET_CREATE_ERROR

    Impossible de créer une socket UNIX.

  • CR_UNKNOWN_HOST

    Impossible de trouver l'adresse IP de l'hôte.

  • CR_VERSION_ERROR

    Une disparité de protocole a résulté de la tentative de connexion à un serveur avec une bibliothèque de client qui utilise une version différente du protocole. Cela peut arriver si vous utilisez une très vieille bibliothèque cliente pour vous connecter à un serveur qui n'a pas été démarré avec l'option --old-protocol.

  • CR_NAMEDPIPEOPEN_ERROR

    Impossible de créer un tunnel nommé sur Windows.

  • CR_NAMEDPIPEWAIT_ERROR

    Impossible d'attendre un tunnel nommé sur Windows.

  • CR_NAMEDPIPESETSTATE_ERROR

    Impossible d'obtenir un gestionnaire de tunnel sur Windows.

  • CR_SERVER_LOST

    Si connect_timeout > 0 et qu'il a fallu plus de connect_timeout secondes pour se connecter au serveur, ou que celui-ci n'a plus répondu durant l'exécution de init-command.

Exemple 

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, "Impossible de se connecter à la base de données, erreur : %s\n",
          mysql_error(&mysql));
}

En utilisant mysql_options() la bibliothèque MySQL lira les sections [client] et [your_prog_name] dans le fichier my.cnf ce qui assurera le bon fonctionnement de votre programme, même si quelqu'un a configuré MySQL d'une fa¸on non-standard.

Notez que pendant la connexion, mysql_real_connect() configure l'option reconnect (partie de la structure MYSQL) à 1. Cette option indique, dans le cas où une requête ne peut être exécutée à cause d'une déconnexion, d'essayer de se reconnecter au serveur avant d'abandonner.

This is a translation of the MySQL Reference Manual that can be found at dev.mysql.com. The original Reference Manual is in English, and this translation is not necessarily as up to date as the English version.