Dans les descriptions suivantes, un paramètre ou retour de fonction NULL correspond au NULL dans le sens C du terme, et non dans le sens de la valeur NULL de mySQL. Les fonctions qui retournent une valeur retournent la plupart du temps un pointeur ou un entier. Sauf en cas d'indications contraires, les fonctions retournant un pointeur retournent une valeur non-NULL pour indiquer un succès ou une valeur NULL pour indiquer une erreur, les fonctions retournant un entier retournent zéro pour indiquer un succès et une valeur non-nulle en cas d'erreur. Notez que "non-nulle'' ne signifie rien de plus que cela. Sauf si la description de la fonction le dit, ne testez pas avec une valeur différente de zéro :
if (result) /* correct */
... erreur ...
if (result < 0) /* incorrect */
... erreur ...
if (result == -1) /* incorrect */
... erreur ...
Lorsqu'une fonction retourne une erreur, la section Erreurs du descriptif de la fonction liste les types d'erreurs possibles. Vous pouvez trouver celle qui est arrivée en appelant mysql_errno(). Une chaîne de caractères représentant l'erreur peut être obtenue en appelant mysql_error().
mysql_affected_rows()
my_ulonglong mysql_affected_rows(MYSQL *mysql)
Description : retourne le nombre de lignes modifiées par la dernière commande UPDATE, supprimées par la dernière commande DELETE ou insérée par la dernière commande INSERT. Peut être appelée immédiatement après mysql_query() pour les commandes UPDATE, DELETE, ou INSERT. Pour la commande SELECT, mysql_affected_rows() fonctionne comme mysql_num_rows().
Valeur de retour : un entier supérieur à zéro indique le nombre de lignes affectées ou sélectionnées. Zéro indique qu'aucun enregistrement n'a été mis à jour pour une requête UPDATE, qu'aucune lignes n'a correspondu à la clause WHERE dans la requête ou que celle ci n'a pas encore été exécutée. -1 indique que la requête a renvoyé une erreur ou que, pour une requête SELECT, mysql_affected_rows() a été appelée avant mysql_store_result().
Erreurs : aucune.
Exemple
mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%ld produits mis à jour",(long) mysql_affected_rows(&mysql));
Si on spécifie l'option CLIENT_FOUND_ROWS en se connectant à mysqld, mysql_affected_rows() retournera le nombre d'enregistrements correspondants à la clause WHERE pour une requête UPDATE. Notez que quand on utilise une commande REPLACE, mysql_affected_rows() retournera 2 si le nouvel enregistrement en a remplacé un ancien. 2 en retour car dans ce cas, l'ancienne ligne a été supprimé puis la nouvelle insérée.
mysql_change_user()
my_bool mysql_change_user(MYSQL *mysql, const char *user, const char
*password, const char *db)
Description : Change l'utilisateur et définit la base de données spécifiée par db en tant que base de données par défaut (courante) dans la connexion spécifiée par mysql. Pour les requêtes suivantes, cette base de données sera celle utilisée pour les références aux tables ne spécifiant pas explicitement une base de données. Cette fonction a été introduite à la version 3.23.3 de mySQL.
mysql_change_user() échoue si l'utilisateur ne peut être authentifié ou s'il n'a pas le droit d'utiliser cette base de données. Dans ce cas, l'utilisateur et la base de données ne sont pas changés.
Le paramètre db peut être mis à NULL si vous ne voulez pas avoir de base de données par défaut.
Valeur de retour : zéro en cas de succès. Différent de zéro si une erreur se produit.
Erreurs
Les mêmes que vous pouvez obtenir avec mysql_real_connect().
CR_COMMANDS_OUT_OF_SYNC : les commandes n'ont pas été exécutées dans le bon ordre.
CR_SERVER_GONE_ERROR : le serveur mySQL ne réponds pas.
CR_SERVER_LOST : la connexion au serveur a été perdue au cours la requête.
CR_UNKNOWN_ERROR : une erreur inconnue s'est produite.
ER_UNKNOWN_COM_ERROR : le serveur mySQL n'implémente pas cette commande (probablement un ancien serveur)
ER_ACCESS_DENIED_ERROR : l'utilisateur ou le mot de passe étaient erronés.
ER_BAD_DB_ERROR : la base de données n'existe pas.
ER_DBACCESS_DENIED_ERROR : l'utilisateur n'a pas le droit d'accéder à la base de données.
ER_WRONG_DB_NAME : le nom de la base de données était trop long.
Exemple
if (mysql_change_user(&mysql, "user", "password", "new_database")) {
fprintf(stderr, "Impossible de changer d'utilisateur. Erreur :
%s\n",
mysql_error(&mysql));
}
mysql_character_set_name()
const char *mysql_character_set_name(MYSQL *mysql)
Description : retourne le jeu de caractères par défaut de la connexion courante.
Valeur de retour : le jeu de caractères par défaut Erreurs : aucune.
mysql_close()
void mysql_close(MYSQL *mysql)
Description : ferme la connexion ouverte précédemment. mysql_close() désalloue aussi le pointeur de connexion pointé par mysql, si celui ci avait été alloué dynamiquement par mysql_init() ou mysql_connect().
Valeur de retour : aucune.
Erreurs : aucune.
mysql_create_db()
int mysql_create_db(MYSQL *mysql, const char *db)
Description : crée la base de données nommée avec le paramètre db. Cette fonction est désapprouvée. Il est préférable d'utiliser mysql_query() pour générer une requête SQL CREATE DATABASE à la place.
Valeur de retour : zéro si la base à été crée avec succès. Différente de zéro si une erreur est survenue.
Erreurs
CR_COMMANDS_OUT_OF_SYNC : les commandes n'ont pas été exécutées dans le bon ordre.
CR_SERVER_GONE_ERROR : le serveur mySQL ne réponds pas.
CR_SERVER_LOST : la connexion au serveur a été perdue au cours la requête.
CR_UNKNOWN_ERROR : une erreur inconnue s'est produite.
Exemple
if(mysql_create_db(&mysql, "ma_base")) {
fprintf(stderr, "Impossible de créer une nouvelle base de données.
Erreur : %s\n",
mysql_error(&mysql));
}
mysql_data_seek()
void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)
Description ; se déplace vers une ligne arbitraire d'un jeu de résultat de requête. Cela nécessite que
la structure du jeu de résultat contienne la totalité du résultat de la requête, de ce fait mysql_data_seek() peut être utilisée en conjonction avec mysql_store_result(), mais pas avec mysql_use_result(). L'index de la ligne doit être compris entre 0 et mysql_num_rows(result)-1.
Valeur de retour : aucune.
Erreurs : aucune.
mysql_debug()
void mysql_debug(const char *debug)
Description : provoque un DBUG_PUSH avec la chaîne donnée. mysql_debug() utilises la librairie de débogage Fred Fish. Pour utiliser cette fonction vous devez compiler la librairie client avec le support débogage.
Valeur de retour : aucune.
Erreurs : aucune.
Exemple
L'appel montré ici fais générer à la librairie du client un fichier de trace dans '/tmp/client.trace' sur la machine du client :
mysql_debug("d:t:O,/tmp/client.trace");
mysql_drop_db()
int mysql_drop_db(MYSQL *mysql, const char *db)
Description : supprime la base de données nommée avec le paramètre db. Cette fonction est désapprouvée. Il est préférable d'utiliser mysql_query() pour générer une requête SQL DROP DATABASE à la place.
Valeur de retour : zéro si la base à été effacée avec succès. Différente de zéro si une erreur est survenue.
Erreurs
CR_COMMANDS_OUT_OF_SYNC : les commandes n'ont pas été exécutées dans le bon ordre.
CR_SERVER_GONE_ERROR : le serveur mySQL ne réponds pas.
CR_SERVER_LOST : la connexion au serveur a été perdue au cours la requête.
CR_UNKNOWN_ERROR : une erreur inconnue s'est produite.
Exemple
if(mysql_drop_db(&mysql, "ma_base"))
fprintf(stderr, "Impossible de supprimer la base de données. Erreur :
%s\n",
mysql_error(&mysql));
mysql_dump_debug_info()
int mysql_dump_debug_info(MYSQL *mysql)
Description : demande au serveur d'écrire quelques informations de débogage dans le log. Pour que cela fonctionne, il faut que l'utilisateur ait le droit SUPER.
Valeur de retour : zéro si la commande a été effectuée avec succès. Différente de zéro si une erreur est survenue.
Erreurs
CR_COMMANDS_OUT_OF_SYNC : les commandes n'ont pas été exécutées dans le bon ordre.
CR_SERVER_GONE_ERROR : le serveur mySQL ne réponds pas.
CR_SERVER_LOST : la connexion au serveur a été perdue au cours la requête.
CR_UNKNOWN_ERROR : une erreur inconnue s'est produite.
mysql_errno()
unsigned int mysql_errno(MYSQL *mysql)
Description : pour la connexion spécifiée par mysql, mysql_errno() retourne le code de l'erreur pour l'appel le plus récent à une fonction de l'API qui peut réussir ou échouer. Un zéro en valeur de retour signifie qu'aucune erreur ne s'est produite. Les codes erreur du client sont listés dans le fichier d'entête mySQL ('errmsg.h'). Les codes erreur du serveur sont listés dans le fichier 'mysqld_error.h'. Dans les sources de la distribution mySQL vous pouvez trouver la liste complète des messages d'erreur et le code qui leur est associé dans le fichier 'Docs/mysqld_error.txt'.
Valeur de retour : un code d'erreur. Zéro si aucune erreur n'est survenue.
Erreurs : aucune.
mysql_error()
char *mysql_error(MYSQL *mysql)
Description : pour la connexion spécifiée par mysql, mysql_error() retourne le message d'erreur pour l'appel le plus récent à une fonction de l'API qui peut réussir ou échouer. Une chaîne vide ("") est retournée si aucune erreur n'est survenue. Cela signifie que les deux tests suivants sont équivalents :
if(mysql_errno(&mysql)) {
// une erreur est survenue }
if(mysql_error(&mysql)[0] != '\0') {
// une erreur est survenue }
La langue des messages d'erreurs peut être changée en recompilant la librairie du client mySQL.
Actuellement, vous pouvez choisir les messages d'erreur parmi un choix de plusieurs langues.
Valeur de retour : une chaîne de caractères qui décrit l'erreur. Une chaîne vide si aucune erreur n'est survenue.
Erreurs : aucune.
mysql_fetch_field()
MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)
Description : retourne la définition d'une colonne d'un jeu de résultats en tant que structure MYSQL_FIELD. Appelez cette fonction plusieurs fois pour obtenir des informations à propos de toutes les colonnes dans le jeu de résultat. mysql_fetch_field() retourne NULL quand il ne reste plus de champs. mysql_fetch_field() est mis à zéro pour retourner des informations à propos du premier champ à chaque fois que vous exécutez une nouvelle requête SELECT. Le champ
retourné par mysql_fetch_field() est aussi affecté par les appels à mysql_field_seek(). Si vous avez appelé mysql_query() pour exécuter un SELECT sur une table mais n'avez pas appelé mysql_store_result(), mySQL retourne la longueur par défaut du blob (8K octets) si vous avez appelé mysql_fetch_field() pour obtenir la longueur d'un champ BLOB. (La taille 8K est choisie car mySQL ne connait pas la longueur maximale du BLOB. Cela devrait être un jour configurable.) Une fois que vous avez récupéré le jeu de résultats, field->max_length contient la longueur de la plus grande valeur de cette colonne dans la requête spécifiée.
Valeur de retour : la structure MYSQL_FIELD de la colonne courante. NULL s'il ne reste plus de colonnes.
Erreurs : aucune.
Exemple
MYSQL_FIELD *field;
while((field = mysql_fetch_field(result))) {
printf("nom du champ : %s\n", field->name);
}
mysql_fetch_fields()
MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)
Description : retourne un tableau de toutes les structures MYSQL_FIELD dans un jeu de résultats.
Chaque structure fournit la définition de champ d'une colonne dans le jeu de résultats.
Valeur de retour : un tableau de structures MYSQL_FIELD pour toutes les colonnes dans le jeu de résultat.
Erreurs : aucune.
Exemple
unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *fields;
num_fields = mysql_num_fields(result);
fields = mysql_fetch_fields(result);
for(i = 0; i < num_fields; i++) {
printf("Le champ %u est %s\n", i, fields[i].name);
}
mysql_fetch_field_direct()
MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr) Description : étant donné un numéro de champ fieldnr pour une colonne dans un jeu de résultats, cette fonction retourne la définition de ce champ en tant que structure MYSQL_FIELD. Vous pouvez utiliser cette fonction pour obtenir la définition d'une colonne choisie arbitrairement.
La valeur de fieldnr doit varier entre 0 et mysql_num_fields(result)-1. Valeur de retour : la structure MYSQL_FIELD pour la colonne spécifiée.
Erreurs : aucune.
Exemple
unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *field;
num_fields = mysql_num_fields(result);
for(i = 0; i < num_fields; i++) {
field = mysql_fetch_field_direct(result, i);
printf("La champ %u est %s\n", i, field->name);
}
mysql_fetch_lengths()
unsigned long *mysql_fetch_lengths(MYSQL_RES *result)
Description : retourne les longueurs des colonnes de la ligne courante dans le jeu de résultats. Si vous voulez copier les valeurs des champs, cette information sur la longueur est très utile pour l'optimisation, car vous pouvez éviter les appels à strlen(). De plus, si le jeu de résultat contient des données binaires, vous devez cette fonction pour déterminer la longueur des données, car strlen() retourne des résultats incorrects pour les champs contenant des caractères nuls. La longueur des colonnes vides et des colonnes contenant la valeur NULL est zéro. Pour savoir comment distinguer ces cas, voyez la description de mysql_fetch_row().
Valeur de retour : un tableau d'entiers longs non-signés représentant la taille de chaque colonne (n'incluant pas la caractère nul de terminaison). NULL si une erreur se produit.
Erreurs : mysql_fetch_lengths() n'est valide que pour la ligne courante du jeu de résultats.
Cette fonction retourne NULL si vous l'appelez avant d'appeler mysql_fetch_row() ou après avoir récupéré toutes les lignes du résultat.
Exemple
MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;
row = mysql_fetch_row(result);
if (row) {
num_fields = mysql_num_fields(result);
lengths = mysql_fetch_lengths(result);
for(i = 0; i < num_fields; i++) {
printf("La colonne %u a %l octets de longueur.\n", i, lengths[i]);
} }
mysql_fetch_row()
MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)
Description : récupère la ligne suivante d'un jeu de résultats. Lorsqu'elle est utilisée après mysql_store_result(), mysql_fetch_row() retourne NULL quand il n'y a plus de lignes a récupérer. Lorsqu'elle est utilisée après mysql_use_result(), mysql_fetch_row() retourne NULL quand il n'y a plus de lignes a récupérer ou qu'une erreur est rencontrée. Le nombre de valeurs dans la ligne est donné par mysql_num_fields(result). Si row contient la valeur de retour d'un appel à mysql_fetch_row(), les pointeurs sur les valeurs sont accédées de row[0] à
row[mysql_num_fields(result)-1]. Les valeurs NULL de la ligne sont indiquées par des pointeurs NULL. La longueur de la valeur du champ dans la ligne peut être obtenue en appelant mysql_fetch_lengths(). Les champs vides et les champs contenant NULL ont tous deux une longueur égale à zéro; vous pouvez les distinguer en vérifiant le pointeur sur la valeur du champ. Si le pointeur est NULL, le champ est NULL; sinon, le champ est vide.
Valeur de retour : une structure MYSQL_ROW pour la prochaine ligne. NULL s'il n'y a plus de lignes a récupérer ou qu'une erreur survient.
Erreurs
CR_SERVER_LOST : la connexion au serveur a été perdue durant la requête.
CR_UNKNOWN_ERROR : une erreur inconnue est survenue.
Exemple
MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;
num_fields = mysql_num_fields(result);
while ((row = mysql_fetch_row(result))) {
unsigned long *lengths;
lengths = mysql_fetch_lengths(result);
for(i = 0; i < num_fields; i++) {
printf("[%.*s] ", (int) lengths[i], row[i] ? row[i] : "NULL");
}
printf("\n");
}
mysql_field_count()
unsigned int mysql_field_count(MYSQL *mysql)
Si vous utilisez une version de mySQL plus ancienne que la 3.22.24, vous devez utiliser unsigned int mysql_num_fields(MYSQL *mysql).
Description : retourne le nombre de colonnes pour la requête la plus récente de la connexion.
L'utilisation normale de cette fonction est lorsque mysql_store_result() a retourné NULL (et que vous n'avez donc pas de pointeur sur jeu de résultats). Dans ce cas, vous pouvez appeler mysql_field_count() pour déterminer si mysql_store_result() aurait dû produire un résultat non-vide. Cela permet au programme client d'entreprendre les bonnes actions sans savoir si la requête était un SELECT (ou équivalent). L'exemple suivant illustre comment cela peut être fait.
Valeur de retour : un entier non-signé représentant le nombre de champs dans un jeu de résultats.
Erreurs : aucune.
Exemple
MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;
if (mysql_query(&mysql,query_string)) {
// erreur }
else // requête bonne, traitons les données qu'elle renvoit {
result = mysql_store_result(&mysql);
if (result) // il y a des lignes {
num_fields = mysql_num_fields(result);
// récupère les lignes, puis apelle mysql_free_result(result) }
else // mysql_store_result() n'a rien retourné; est-ce normal ? {
if(mysql_field_count(&mysql) == 0) {
// la requête ne retourne aucune donnée // (ce n'était pas un SELECT)
num_rows = mysql_affected_rows(&mysql);
}
else // mysql_store_result() aurait du retourner des données {
fprintf(stderr, "Erreur : %s\n", mysql_error(&mysql));
} } }
Une alternative est de remplacer l'appel à mysql_field_count(&mysql) par mysql_errno(&mysql). Dans ce cas, vous vérifiez directement les erreurs à partir de mysql_store_result() plutôt qu'à partir de mysql_field_count() si la requête était un SELECT.
mysql_field_seek()
MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)
Description : place le pointeur de champs à la position donnée. Le prochain appel à mysql_fetch_field() récupérera la définition du champ de la colonne associée à cet index.
Pour vous placer au début d'une ligne, passez 0 comme valeur d'offset. Valeur de retour : la dernière valeur de l'index de champ.
Erreurs : aucune.
mysql_field_tell()
MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)
Description : retourne la position du curseur de champ utilisé pour le dernier appel à mysql_fetch_field(). Cette valeur peut être utilisée en argument de mysql_field_seek(). Valeur de retour : l'indice courant du curseur de champ.
Erreurs : aucune.
mysql_free_result()
void mysql_free_result(MYSQL_RES *result)
Description : libère la mémoire alloué à un résultat avec mysql_store_result(), mysql_use_result(), mysql_list_dbs(), etc. Quand vous n'avez plus besoin d'un jeu de résultat, vous devez libérer la mémoire qu'il occupe en appelant mysql_free_result().
Valeur de retour : aucune.
Erreurs : aucune.
mysql_get_client_info()
char *mysql_get_client_info(void)
Description : retourne une chaîne représentant la version de la librairie du client.
Valeur de retour : une chaîne de caractères représentant la version de la librairie du client.
Erreurs : aucune.
mysql_get_host_info()
char *mysql_get_host_info(MYSQL *mysql)
Description : retourne une chaîne de caractères décrivant le type de connexion actuellement utilisé, incluant le nom du serveur.
Valeur de retour : une chaîne de caractères représentant le nom du serveur et le type de connexion.
Erreurs : aucune.
mysql_get_proto_info()
unsigned int mysql_get_proto_info(MYSQL *mysql)
Description : retourne la version du protocole utilisé par la connexion courante.
Valeur de retour : un entier non signé représentant la version du protocole utilisé par la connexion courante.
Erreurs : aucune.
mysql_get_server_info()
char *mysql_get_server_info(MYSQL *mysql)
Description : retourne une chaîne représentant le numéro de version du serveur.
Valeur de retour : une chaîne de caractères représentant le numéro de version du serveur.
Erreurs : aucune.
mysql_info()
char *mysql_info(MYSQL *mysql)
Description : récupère une chaîne de caractères fournissant des informations à propos de la requête exécutée le plus récemment, mais seulement pour celles listées ici. Pour les autres requêtes, mysql_info() retournera NULL. Le format de la chaîne varie selon le type de requête, comme décrit ici. Les nombres présentés sont des exemples; la chaîne retournée contiendra les informations
correspondantes à vos requêtes.
INSERT INTO ... SELECT ...
String format: Records: 100 Duplicates: 0 Warnings: 0 INSERT INTO ... VALUES (...),(...),(...)...
String format: Records: 3 Duplicates: 0 Warnings: 0 LOAD DATA INFILE ...
String format: Records: 1 Deleted: 0 Skipped: 0 Warnings: 0 ALTER TABLE
String format: Records: 3 Duplicates: 0 Warnings: 0 UPDATE
String format: Rows matched: 40 Changed: 40 Warnings: 0
Notez que mysql_info() retourne une valeur non-nulle (NULL) pour les requêtes INSERT ...
VALUES seulement si une liste de valeurs multiples est fournie à la requête.
Valeur de retour : Une chaîne de caractères représentant des informations additionnelles à propos de la dernière requête exécutée. NULL si aucune information n'est disponible pour la requête.
Erreurs : aucune.
mysql_init()
MYSQL *mysql_init(MYSQL *mysql)
Description : alloue ou initialise un objet MYSQL convenable pour mysql_real_connect(). Si mysql est un pointeur NULL, la fonction alloue, initialise et retourne un nouvel objet. Sinon, l'objet est initialisé et son adresse est retournée. Si mysql_init() alloue un nouvel objet, il sera libéré quand mysql_close() sera appelée pour clore la connexion.
Valeur de retour : un gestionnaire MYSQL* initialisé. NULL s'il n'y avait pas assez de mémoire pour allouer le nouvel objet.
Erreurs : si la mémoire est insuffisante, NULL est retourné.
mysql_insert_id()
my_ulonglong mysql_insert_id(MYSQL *mysql)
Description : retourne l'identifiant généré pour une colonne AUTO_INCREMENT par la dernière requête. Utilisez cette commande après avoir exécuté une requête INSERT sur une table qui contient
Description : retourne l'identifiant généré pour une colonne AUTO_INCREMENT par la dernière requête. Utilisez cette commande après avoir exécuté une requête INSERT sur une table qui contient