Soumet une commande au serveur et attend le résultat.

PGresult *PQexec(PGconn *conn, const char *command);
        

Renvoie un pointeur PGresult ou peut-être un pointeur NULL. Un pointeur non NULL sera généralement renvoyé sauf dans des conditions particulières comme un manque de mémoire ou lors d'erreurs sérieuses telles que l'incapacité à envoyer la commande au serveur. La fonction PQresultStatus devrait être appelée pour vérifier le code retour pour toute erreur (incluant la valeur d'un pointeur NULL, auquel cas il renverra PGRES_FATAL_ERROR). Utilisez PQerrorMessage pour obtenir plus d'informations sur l'erreur.

Soumet une commande au serveur et attend le résultat, avec la possibilité de passer des paramètres séparément du texte de la commande SQL.

PGresult *PQexecParams(PGconn *conn,
                            const char *command,
                            int nParams,
                            const Oid *paramTypes,
                            const char * const *paramValues,
                            const int *paramLengths,
                            const int *paramFormats,
                            int resultFormat);
        

PQexecParams est identique à PQexec mais offre des fonctionnalités supplémentaires : des valeurs de paramètres peuvent être spécifiées séparément de la chaîne de commande et les résultats de la requête peuvent être demandés soit au format texte soit au format binaire.

Voici les arguments de la fonction :

Soumet une requête pour créer une instruction préparée avec les paramètres donnés et attends la fin de son exécution.

PGresult *PQprepare(PGconn *conn,
         const char *stmtName,
         const char *query,
         int nParams,
         const Oid *paramTypes);

PQprepare crée une instruction préparée pour une exécution ultérieure avec PQexecPrepared. Cette fonction autorise les commandes à être exécutées de façon répétée sans être analysées et planifiées à chaque fois ; voir PREPARE pour les détails.

La fonction crée une instruction préparée nommée stmtName à partir de la chaîne query, qui ne doit contenir qu'une seule commande SQL. stmtName peut être "" pour créer une instruction non nommée, auquel cas toute instruction non nommée déjà existante est automatiquement remplacée par cette dernière  sinon une erreur sera levée si le nom de l'instruction est déjà définie dans la session en cours. Si des paramètres sont utilisés, ils sont référencés dans la requête avec $1, $2, etc. nParams est le nombre de paramètres pour lesquels des types sont prédéfinis dans le tableau paramTypes[] (le pointeur du tableau pourrait être NULL quand nParams vaut zéro). paramTypes[] spécifie les types de données à affecter aux symboles de paramètres par leur OID. Si paramTypes est NULL ou si un élément particulier du tableau vaut zéro, le serveur affecte un type de données au symbole du paramètre de la même façon qu'il le ferait pour une chaîne littérale non typée. De plus, la requête peut utiliser des symboles de paramètre avec des nombres plus importants que nParams ; les types de données seront aussi inférés pour ces symboles. (Voir PQdescribePrepared pour un moyen de trouver les types de données inférés.)

Comme avec PQexec, le résultat est normalement un objet PGresult dont le contenu indique le succès ou l'échec côté serveur. Un résultat NULL indique un manque de mémoire ou une incapacité à envoyer la commande. Utilisez PQerrorMessage pour obtenir plus d'informations sur de telles erreurs.

Envoie une requête pour exécuter une instruction séparée avec les paramètres donnés, et attend le résultat.

PGresult *PQexecPrepared(PGconn *conn,
                                const char *stmtName,
                                int nParams,
                                const char * const *paramValues,
                                const int *paramLengths,
                                const int *paramFormats,
                                int resultFormat);
        

PQexecPrepared est identique à PQexecParams mais la commande à exécuter est spécifiée en nommant l'instruction préparée précédemment au lieu de donner une chaîne de requête. Cette fonctionnalité permet aux commandes utilisées de façon répétée d'être analysées et planifiées seulement une fois plutôt que chaque fois qu'ils sont exécutés. L'instruction doit avoir été préparée précédemment dans la session en cours.

Les paramètres sont identiques à PQexecParams, sauf que le nom d'une instruction préparée est donné au lieu d'une chaîne de requête et que le paramètre paramTypes[] n'est pas présent (il n'est pas nécessaire car les types des paramètres de l'instruction préparée ont été déterminés à la création).

Soumet une requête pour obtenir des informations sur l'instruction préparée indiquée et attend le retour de la requête.

         PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
        

PQdescribePrepared permet à une application d'obtenir des informations sur une instruction préparée précédente.

stmtName peut être "" ou NULL pour référencer l'instruction non nommée. Sinon, ce doit être le nom d'une instruction préparée existante. En cas de succès, un PGresult est renvoyé avec le code retour PGRES_COMMAND_OK. Les fonctions PQnparams et PQparamtype peuvent utiliser ce PGresult pour obtenir des informations sur les paramètres de l'instruction préparée, et les fonctions PQnfields, PQfname, PQftype, etc. fournissent des informations sur les colonnes résultantes (s'il y en a) de l'instruction.

Soumet une requête pour obtenir des informations sur le portail indiqué et attend le retour de la requête.

         PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
        

PQdescribePortal permet à une application d'obtenir des informations sur un portail précédemment créé. (libpq ne fournit pas d'accès direct aux portails mais vous pouvez utiliser cette fonction pour inspecter les propriétés d'un curseur créé avec la commande SQL DECLARE CURSOR.) PQdescribePortal est seulement supporté dans les connexions en protocole 3.0 et ultérieurs ; il échouera lors de l'utilisation du protocole 2.0.

portalName peut être "" ou NULL pour référencer un portail sans nom. Sinon, il doit correspondre au nom d'un portail existant. En cas de succès, un PGresult est renvoyé avec le code de retour PGRES_COMMAND_OK. Les fonctions PQnfields, PQfname, PQftype, etc. peuvent utiliser ce PGresult pour obtenir des informations sur les colonnes résultantes (s'il y en a) du portail.

Renvoie l'état du résultat d'une commande.

ExecStatusType PQresultStatus(const PGresult *res);
        

PQresultStatus peut renvoyer une des valeurs suivantes :

Si le statut du résultat est PGRES_TUPLES_OK ou PGRES_SINGLE_TUPLE, alors les fonctions décrites ci-dessous peuvent être utilisées pour récupérer les lignes renvoyées par la requête. Notez qu'une commande SELECT qui récupère zéro ligne affichera toujours PGRES_TUPLES_OK. PGRES_COMMAND_OK est pour les commandes qui ne peuvent jamais renvoyer de lignes (INSERT ou UPDATE sans une clause RETURNING, etc.). Une réponse PGRES_EMPTY_QUERY pourrait indiquer un bogue dans le logiciel client.

Un résultat de statut PGRES_NONFATAL_ERROR ne sera jamais renvoyé directement par PQexec ou d'autres fonctions d'exécution de requêtes ; les résultats de ce type sont passés à l'exécuteur de notifications (voir la Section 34.13).

Convertit le type énuméré renvoyé par PQresultStatus en une constante de type chaîne décrivant le code d'état. L'appelant ne devrait pas libérer le résultat.

char *PQresStatus(ExecStatusType status);
        

Renvoie le message d'erreur associé avec la commande ou une chaîne vide s'il n'y a pas eu d'erreurs.

char *PQresultErrorMessage(const PGresult *res);
        

S'il y a eu une erreur, la chaîne renvoyée incluera un retour chariot en fin. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand le pointeur PGresult associé sera passé à PQclear.

Immédiatement après un appel à PQexec ou PQgetResult, PQerrorMessage (sur la connexion) renverra la même chaîne que PQresultErrorMessage (sur le résultat). Néanmoins, un PGresult conservera son message d'erreur jusqu'à destruction, alors que le message d'erreur de la connexion changera avec les opérations suivantes. Utilisez PQresultErrorMessage quand vous voulez connaître le statut associé avec un PGresult particulier ; utilisez PQerrorMessage lorsque vous souhaitez connaître le statut à partir de la dernière opération sur la connexion.

Renvoie une version reformatée du message d'erreur associé avec un objet PGresult.

char *PQresultVerboseErrorMessage(const PGresult *res,
                                  PGVerbosity verbosity,
                                  PGContextVisibility show_context);
        

Dans certaines situations, un client pourrait vouloir une version plus détaillée d'une erreur déjà rapportée. PQresultVerboseErrorMessage couvre ce besoin en traitant le message tel qu'il aurait été produit par PQresultErrorMessage si la configuration souhaitée de la verbosité était activée pour la connexion au moment où l'objet PGresult indiqué a été généré. Si le PGresult ne correspond pas une erreur, « PGresult is not an error result » est renvoyé à la place. La chaîne renvoyée inclut un retour à la ligne en fin de chaîne.

Contrairement à la plupart des autres fonctions d'extraction de données à partir d'un objet PGresult, le résultat de cette fonction est une chaîne tout juste allouée. L'appelant doit la libérer en utilisant PQfreemem() quand la chaîne n'est plus nécessaire.

Un NULL en retour est possible s'il n'y a pas suffisamment de mémoire.

Renvoie un champ individuel d'un rapport d'erreur.

char *PQresultErrorField(const PGresult *res, int fieldcode);
        

fieldcode est un identifiant de champ d'erreur ; voir les symboles listés ci-dessous. NULL est renvoyé si PGresult n'est pas un résultat d'erreur ou d'avertissement, ou n'inclut pas le champ spécifié. Les valeurs de champ n'incluront normalement pas un retour chariot en fin. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand le pointeur PGresult associé sera passé à PQclear.

Les codes de champs suivants sont disponibles :

Le client est responsable du formatage des informations affichées suivant ses besoins ; en particulier, il doit supprimer les longues lignes si nécessaires. Les caractères de retour chariot apparaissant dans les champs de message d'erreur devraient être traités comme des changements de paragraphes, pas comme des changements de lignes.

Les erreurs générées en interne par libpq auront une sévérité et un message principal mais aucun autre champ.

Notez que les champs d'erreurs sont seulement disponibles pour les objets PGresult, et non pas pour les objets PGconn ; il n'existe pas de fonction PQerrorField.

Libère le stockage associé avec un PGresult. Chaque résultat de commande devrait être libéré via PQclear lorsqu'il n'est plus nécessaire.

void PQclear(PGresult *res);
        

Si l'argument est un pointeur NULL, aucune opération n'est réalisée.

Vous pouvez conserver un objet PGresult aussi longtemps que vous en avez besoin ; il ne part pas lorsque vous lancez une nouvelle commande, même pas si vous fermez la connexion. Pour vous en débarrasser, vous devez appeler PQclear. En cas d'oubli, le résultat sera une fuite de mémoire dans votre application.

Renvoie le nombre de lignes (enregistrements, ou tuples) du résultat de la requête. (Notez que les objets PGresult sont limités à au plus INT_MAX lignes, donc un résultat de type int est suffisant.)

int PQntuples(const PGresult *res);
       

Renvoie le nombre de colonnes (champs) de chaque ligne du résultat de la requête.

int PQnfields(const PGresult *res);
       

Renvoie le nom de la colonne associé avec le numéro de colonne donnée. Les numéros de colonnes commencent à zéro. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand le pointeur PGresult associée est passée à PQclear.

char *PQfname(const PGresult *res,
                      int column_number);
       

NULL est renvoyé si le numéro de colonne est en dehors de la plage.

Renvoie le numéro de colonne associé au nom de la colonne donné.

int PQfnumber(const PGresult *res,
                     const char *column_name);
       

-1 est renvoyé si le nom donné ne correspond à aucune colonne.

Le nom donné est traité comme un identifiant dans une commande SQL, c'est-à-dire qu'il est mis en minuscule sauf s'il est entre des guillemets doubles. Par exemple, pour le résultat de la requête suivante :

SELECT 1 AS FOO, 2 AS "BAR";
       

nous devons obtenir les résultats suivants :

PQfname(res, 0)              foo
      PQfname(res, 1)              BAR
      PQfnumber(res, "FOO")        0
      PQfnumber(res, "foo")        0
      PQfnumber(res, "BAR")        -1
      PQfnumber(res, "\"BAR\"")    1
       

Renvoie l'OID de la table à partir de laquelle la colonne donnée a été récupérée. Les numéros de colonnes commencent à 0.

Oid PQftable(const PGresult *res,
                    int column_number);
       

InvalidOid est renvoyé si le numéro de colonne est en dehors de la plage, ou si la colonne spécifiée n'est pas une simple référence à une colonne de table. Vous pouvez requêter la table système pg_class pour déterminer exactement quelle table est référencée.

Le type Oid et la constante InvalidOid seront définis lorsque vous incluerez le fichier d'en-tête libpq. Ils auront le même type entier.

Renvoie le numéro de colonne (dans sa table) de la colonne correspondant à la colonne spécifiée de résultat de la requête. Les numéros de colonne du résultat commencent à 0, mais les colonnes de table ont des numéros supérieurs à zéro.

int PQftablecol(const PGresult *res,
                      int column_number);
       

Zéro est renvoyé si le numéro de colonne est en dehors de la plage, ou si la colonne spécifiée n'est pas une simple référence à une colonne de table, ou lors de l'utilisation d'un protocole antérieur à la version 3.0.

Renvoie le code de format indiquant le format de la colonne donné. Les numéros de colonnes commencent à zéro.

int PQfformat(const PGresult *res,
                     int column_number);
       

Le code de format zéro indique une représentation textuelle des données, alors qu'un code un indique une représentation binaire (les autres codes sont réservés pour des définitions futures).

Renvoie le type de données associé avec le numéro de colonne donné. L'entier renvoyé est le numéro OID interne du type. Les numéros de colonnes commencent à zéro.

Oid PQftype(const PGresult *res,
                   int column_number);
       

Vous pouvez lancer des requêtes sur la table système pg_type pour obtenir les noms et propriétés des différents types de données. Les OID des types de données intégrés sont définis dans le fichier catalog/pg_type_d.h du répertoire include de l'installation de PostgreSQL.

Renvoie le modificateur de type de la colonne associée avec le numéro de colonne donné. Les numéros de colonnes commencent à zéro.

int PQfmod(const PGresult *res,
                  int column_number);
       

L'interprétation des valeurs du modificateur est spécifique au type ; typiquement elles indiquent la précision ou les limites de taille. La valeur -1 est utilisée pour indiquer « aucune information disponible ». La plupart des types de données n'utilisent pas les modificateurs, auquel cas la valeur est toujours -1.

Renvoie la taille en octets de la colonne associée au numéro de colonne donné. Les numéros de colonnes commencent à 0.

int PQfsize(const PGresult *res,
                   int column_number);
       

PQfsize renvoie l'espace alloué pour cette colonne dans une ligne de la base de données, en d'autres termes la taille de la représentation interne du serveur du type de données (en conséquence ce n'est pas réellement utile pour les clients). Une valeur négative indique que les types de données ont une longueur variable.

Renvoie 1 si PGresult contient des données binaires et 0 s'il contient des données texte.

int PQbinaryTuples(const PGresult *res);
       

Cette fonction est obsolète (sauf dans le cas d'une utilisation en relation avec COPY) car un seul PGresult peut contenir du texte dans certaines colonnes et des données binaires dans d'autres. PQfformat est à préférer. PQbinaryTuples renvoie 1 seulement si toutes les colonnes du résultat sont dans un format binaire (format 1).

Renvoie la valeur d'un seul champ d'une seule ligne d'un PGresult. Les numéros de lignes et de colonnes commencent à zéro. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand le pointeur PGresult associé sera passé à PQclear.

char* PQgetvalue(const PGresult *res,
                        int row_number,
                        int column_number);
       

Pour les données au format texte, la valeur renvoyée par PQgetvalue est une représentation au format chaîne de caractères terminée par un octet nul de la valeur du champ. Pour les données au format binaire, la valeur dans la représentation binaire est déterminée par le type de la donnée, fonctions typsend et typreceive. (La valeur est en fait suivie d'un octet zéro dans ce cas aussi, mais ce n'est pas réellement utile car la valeur a des chances de contenir d'autres valeurs NULL embarquées).

Une chaîne vide est renvoyée si la valeur du champ est NULL. Voir PQgetisnull pour distinguer les valeurs NULL des chaînes vides.

Le pointeur renvoyé par PQgetvalue pointe vers le stockage qui fait partie de la structure PGresult. Personne ne devrait modifier les données vers lesquelles il pointe, et tout le monde devrait copier les données dans un autre stockage explicitement si elles doivent être utilisées après la durée de vie de la structure PGresult.

Teste un champ pour savoir s'il est NULL. Les numéros de lignes et de colonnes commencent à 0.

int PQgetisnull(const PGresult *res,
                       int row_number,
                       int column_number);
       

Cette fonction renvoie 1 si le champ est nul et 0 s'il contient une valeur non NULL (notez que PQgetvalue renverra une chaîne vide, et non pas un pointeur NULL, pour un champ NULL).

Renvoie la longueur réelle de la valeur d'un champ en octet. Les numéros de lignes et de colonnes commencent à 0.

int PQgetlength(const PGresult *res,
                      int row_number,
                      int column_number);
       

C'est la longueur réelle des données pour cette donnée en particulier, c'est-à-dire la taille de l'objet pointé par PQgetvalue. Pour le format textuel, c'est identique à strlen(). Pour le format binaire, c'est une information essentielle. Notez que l'on ne devrait pas se fier à PQfsize pour obtenir la taille réelle des données.

Renvoie le nombre de paramètres d'une instruction préparée.

       int PQnparams(const PGresult *res);
       

Cette fonction est utile seulement pour inspecter le résultat de PQdescribePrepared. Pour les autres types de résultats, elle renverra zéro.

Renvoie le type de donnée du paramètre indiqué dans l'instruction. Les numéros des paramètres commencent à 0.

       Oid PQparamtype(const PGresult *res, int param_number);
       

Cette fonction est utile seulement pour inspecter le résultat de PQdescribePrepared. Pour les autres types de résultats, elle renverra zéro.

Affiche toutes les lignes et, optionnellement, les noms des colonnes dans le flux de sortie spécifié.

void PQprint(FILE* fout,      /* flux de sortie */
                   const PGresult *res,
                   const PQprintOpt *po);

        typedef struct
        {
            pqbool  header;      /* affiche les en-têtes des champs et le nombre de
                                    lignes */
            pqbool  align;       /* aligne les champs */
            pqbool  standard;    /* vieux format (mort) */
            pqbool  html3;       /* affiche les tables en HTML */
            pqbool  expanded;    /* étend les tables */
            pqbool  pager;       /* utilise le paginateur pour la sortie si nécessaire
                                    */
            char    *fieldSep;   /* séparateur de champ */
            char    *tableOpt;   /* attributs des éléments de table HTML */
            char    *caption;    /* titre de la table HTML */
            char    **fieldName; /* Tableau terminé par un NULL des noms de remplacement
                                    des champs */
        } PQprintOpt;
       

Cette fonction était auparavant utilisée par psql pour afficher les résultats des requêtes mais ce n'est plus le cas. Notez qu'elle assume que les données sont dans un format textuel.

Renvoie l'état de la commande de l'instruction SQL qui a généré le PGresult.

char * PQcmdStatus(PGresult *res);
       

D'habitude, c'est juste le nom de la commande mais elle peut inclure des données supplémentaires comme le nombre de lignes traitées. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand le pointeur PGresult associée sera passé à PQclear.

Renvoie le nombre de lignes affectées par la commande SQL.

char * PQcmdTuples(PGresult *res);
       

Cette fonction renvoie une chaîne contenant le nombre de lignes affectées par l'instruction SQL qui a généré PGresult. Cette fonction ne peut être utilisée qu'après l'exécution d'une instruction SELECT, CREATE TABLE AS, INSERT, UPDATE, DELETE, MERGE, MOVE, FETCH ou COPY, ou un EXECUTE d'une instruction préparée contenant une instruction INSERT, UPDATE, DELETE ou MERGE. Si la commande qui a généré PGresult était autre chose, PQcmdTuples renverrait directement une chaîne vide. L'appelant ne devrait pas libérer la valeur de retour directement. Elle sera libérée quand le pointeur PGresult associée sera passé à PQclear.

Renvoie l'OID de la ligne insérée, si la commande SQL était un INSERT qui a inséré exactement une ligne dans une table comprenant des OID, ou un EXECUTE d'une requête préparée contenant une instruction INSERT convenable. Sinon cette fonction renvoie InvalidOid. Cette fonction renverra aussi InvalidOid si la table touchée par l'instruction INSERT ne contient pas d'OID.

Oid PQoidValue(const PGresult *res);
       

Cette fonction est obsolète. Utilisez plutôt PQoidValue. De plus, elle n'est pas compatible avec les threads. Elle renvoie une chaîne contenant l'OID de la ligne insérée alors que PQoidValue renvoie la valeur de l'OID.

char * PQoidStatus(const PGresult *res);
       

        char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);
       

PQescapeLiteral échappe une chaîne pour l'utiliser dans une commande SQL. C'est utile pour insérer des données comme des constantes dans des commandes SQL. Certains caractères, comme les guillemets et les antislashs, doivent être traités avec des caractères d'échappement pour éviter qu'ils ne soient traités d'après leur signification spéciale par l'analyseur SQL. PQescapeLiteral réalise cette opération.

PQescapeLiteral renvoie une version échappée du paramètre str dans une mémoire allouée avec malloc(). Cette mémoire devra être libérée en utilisant PQfreemem() quand le résultat ne sera plus utile. Un octet zéro final n'est pas requis et ne doit pas être compté dans length. (Si un octet zéro est découvert avant le traitement de length octets, PQescapeLiteral s'arrête au zéro ; ce comportement est celui de strncpy.) Les caractères spéciaux de la chaîne en retour ont été remplacés pour qu'ils puissent être traités correctement par l'analyseur de chaînes de PostgreSQL. Un octet zéro final est aussi ajouté. Les guillemets simples qui doivent entourer les chaînes littérales avec PostgreSQL sont inclus dans la chaîne résultante.

En cas d'erreur, PQescapeLiteral renvoit NULL et un message adéquat est stocké dans l'objet conn.

Notez qu'il n'est pas nécessaire ni correct de faire un échappement quand une valeur est passée en tant que paramètre séparé dans PQexecParams ou ses routines sœurs.

        char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);
       

PQescapeIdentifier échappe une chaîne pour qu'elle puisse être utilisé en tant qu'identifiant SQL, par exemple pour le nom d'une table, d'une colonne ou d'une fonction. C'est utile quand un identifiant fourni par un utilisateur pourrait contenir des caractères spéciaux, qui sinon ne seraient pas interprétés comme faisant partie de l'identifiant par l'analyseur SQL, ou lorsque l'identifiant pourrait contenir des caractères en majuscule, dont la casse doit être préservée.

PQescapeIdentifier renvoit une version du paramètre str échappée comme doit l'être un identifiant SQL, dans une mémoire allouée avec malloc(). Cette mémoire doit être libérée en utilisant PQfreemem() quand le résultat n'est plus nécessaire. Un octet zéro final n'est pas nécessaire et ne doit pas être comptabilisé dans length. (Si un octet zéro est trouvé avant le traitement de length octets, PQescapeIdentifier s'arrête au zéro ; ce comportement est celui de strncpy.) Les caractères spéciaux de la chaîne en retour ont été remplacés pour que ce dernier soit traité proprement comme un identifiant SQL. Un octet zéro final est aussi ajouté. La chaîne de retour sera aussi entourée de guillemets doubles.

En cas d'erreur, PQescapeIdentifier renvoit NULL et un message d'erreur adéquat est stocké dans l'objet conn.

        size_t PQescapeStringConn (PGconn *conn,
                                   char *to, const char *from, size_t length,
                                   int *error);
       

PQescapeStringConn > échappe les chaînes littérales de la même façon que PQescapeLiteral . Contrairement à PQescapeLiteral , l'appelant doit fournir un tampon d'une taille appropriée. De plus, PQescapeStringConn > n'ajoute pas de guillemets simples autour des chaînes littérales de PostgreSQL ; elles doivent être ajoutées dans la commande SQL où ce résultat sera inséré. Le paramètre from pointe vers le premier caractère de la chaîne à échapper, et le paramètre length précise le nombre d'octets contenus dans cette chaîne. Un octet zéro final n'est pas nécessaire et ne doit pas être comptabilisé dans length. (Si un octet zéro est trouvé avant le traitement de length octets, PQescapeStringConn s'arrête au zéro ; ce comportement est celui de strncpy.) to doit pointer vers un tampon qui peut contenir au moins un octet de plus que deux fois la valeur de length, sinon le comportement de la fonction est indéfini. Le comportement est indéfini si les chaînes to et from se recouvrent.

Si le paramètre error est différent de NULL, alors *error est configuré à zéro en cas de succès, et est différent de zéro en cas d'erreur. Actuellement, les seules conditions permettant une erreur impliquent des encodages multi-octets dans la chaîne source. La chaîne en sortie est toujours générée en cas d'erreur mais on peut s'attendre à ce que le serveur la rejette comme une chaîne malformée. En cas d'erreur, un message adéquat est stocké dans l'objet conn, que error soit NULL ou non.

PQescapeStringConn renvoit le nombre d'octets écrits dans to, sans inclure l'octet zéro final.

PQescapeString est une version ancienne et obsolète de PQescapeStringConn .

        size_t PQescapeString (char *to, const char *from, size_t length);
       

La seule différence avec PQescapeStringConn tient dans le fait que PQescapeString n'a pas de paramètres conn et error. À cause de cela, elle ne peut ajuster son comportement en fonction des propriétés de la connexion (comme l'encodage des cnécssairearactères) et du coup, elle pourrait fournir des résultats erronés. De plus, elle ne peut pas renvoyer de conditions d'erreur.

PQescapeString peut être utilisé en toute sécurité avec des programmes client utilisant une seule connexion PostgreSQL à la fois (dans ce cas, il peut trouver ce qui l'intéresse « en arrière-plan »). Dans d'autres contextes, c'est un risque en terme de sécurité. Cette fonction devrait être évitée et remplacée par PQescapeStringConn .

Échappe des données binaires à utiliser à l'intérieur d'une commande SQL avec le type bytea. Comme avec PQescapeStringConn , c'est seulement utilisé pour insérer des données directement dans une chaîne de commande SQL.

unsigned char *PQescapeByteaConn(PGconn *conn,
                                const unsigned char *from,
                                size_t from_length,
                                size_t *to_length);

Certaines valeurs d'octets doivent être échappées lorsqu'elles font partie d'un littéral bytea dans une instruction SQL. PQescapeByteaConn échappe les octets en utilisant soit un codage hexadécimal soit un échappement avec des antislashs. Voir Section 8.4 pour plus d'informations.

Le paramètre from pointe sur le premier octet de la chaîne à échapper et le paramètre from_length donne le nombre d'octets de cette chaîne binaire (un octet zéro final n'est ni nécessaire ni compté). Le paramètre to_length pointe vers une variable qui contiendra la longueur de la chaîne échappée résultante. Cette longueur inclut l'octet zéro de terminaison.

PQescapeByteaConn renvoie une version échappée du paramètre from dans la mémoire allouée avec malloc(). Cette mémoire doit être libérée avec PQfreemem lorsque le résultat n'est plus nécessaire. Tous les caractères spéciaux de la chaîne de retour sont remplacés de façon à ce qu'ils puissent être traités proprement par l'analyseur de chaînes littérales de PostgreSQL et par la fonction d'entrée bytea. Un octet zéro final est aussi ajouté. Les guillemets simples qui encadrent les chaînes littérales de PostgreSQL ne font pas partie de la chaîne résultante.

En cas d'erreur, un pointeur NULL est renvoyé et un message d'erreur adéquat est stocké dans l'objet conn. Actuellement, la seule erreur possible est une mémoire insuffisante pour stocker la chaîne résultante.

PQescapeBytea est une version ancienne et obsolète de PQescapeByteaConn.

        unsigned char *PQescapeBytea(const unsigned char *from,
                                     size_t from_length,
                                     size_t *to_length);
       

La seule différence avec PQescapeByteaConn est que PQescapeBytea ne prend pas de paramètre PGconn. De ce fait, PQescapeBytea ne peut être utilisé en toute sécurité que dans des programmes qui n'utilisent qu'une seule connexion PostgreSQL à la fois (dans ce cas, il peut trouver ce dont il a besoin « en arrière-plan »). Elle pourrait donner des résultats erronés si elle est utilisé dans des programmes qui utilisent plusieurs connexions de bases de données (dans ce cas, utilisez PQescapeByteaConn).

Convertit une représentation de la chaîne en donnés binaires -- l'inverse de PQescapeBytea. Ceci est nécessaire lors de la récupération de données bytea en format texte, mais pas lors de sa récupération au format binaire.

unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
       

Le paramètre from pointe vers une chaîne de telle qu'elle pourrait provenir de PQgetvalue lorsque la colonne est de type bytea. PQunescapeBytea convertit cette représentation de la chaîne en sa représentation binaire. Elle renvoie un pointeur vers le tampon alloué avec malloc(), ou NULL en cas d'erreur, et place la taille du tampon dans to_length. Le résultat doit être libéré en utilisant PQfreemem lorsqu'il n'est plus nécessaire.

Cette conversion n'est pas l'inverse exacte de PQescapeBytea car la chaîne n'est pas supposée être "échappée" tel qu'elle est renvoyée par PQgetvalue. Cela veut dire, notamment, qu'il n'y a pas besoin de réfléchir à la mise entre guillemets de la chaîne, et donc pas besoin d'un paramètre PGconn.