PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 14.11 » Interfaces client » libpq -- Bibliothèque C » Fonctions diverses

34.12. Fonctions diverses

Comme toujours, certaines fonctions ne sont pas catégorisables.

PQfreemem

Libère la mémoire allouée par libpq.

       void PQfreemem(void *ptr);
      

Libère la mémoire allouée par libpq, particulièrement PQescapeByteaConn, PQescapeBytea, PQunescapeBytea, et PQnotifies. Il est particulièrement important que cette fonction, plutôt que free(), soit utilisée sur Microsoft Windows. Ceci est dû au fait qu'allouer de la mémoire dans une DLL et la relâcher dans l'application ne marche que si les drapeaux multi-thread/mon-thread, release/debug et static/dynamic sont les mêmes pour la DLL et l'application. Sur les plateformes autres que Microsoft Windows, cette fonction est identique à la fonction free() de la bibliothèque standard.

PQconninfoFree

Libère les structures de données allouées par PQconndefaults ou PQconninfoParse.

       void PQconninfoFree(PQconninfoOption *connOptions);
      

Un simple appel à PQfreemem ne suffira pas car le tableau contient des références à des chaînes complémentaires.

PQencryptPasswordConn

Prépare la forme chiffrée du mot de passe PostgreSQL.

      char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);
      

Cette fonction est utilisée par les applications clientes qui souhaitent envoyer des commandes comme ALTER USER joe PASSWORD 'passe'. Une bonne pratique est de ne pas envoyer le mot de passe en clair dans une telle commande car le mot de passe serait exposé dans les journaux, les affichages d'activité et ainsi de suite. À la place, utilisez cette fonction pour convertir le mot de passe sous forme chiffrée avant de l'envoyer.

Les arguments passwd et user sont le mot de passe en clair et le nom SQL de l'utilisateur correspondant. algorithm spécifie l'algorithme de chiffrement à utiliser pour chiffrer le mot de passe. Pour le moment, les algorithmes supportés sont md5 et scram-sha-256 (on et off sont également acceptés comme des alias pour md5, pour compatibilité avec les versions des anciens serveurs). Veuillez noter que le support de scram-sha-256 a été introduit dans la version 10 de PostgreSQL, et ne fonctionnera pas correctement avec des versions de serveur plus ancienne. Si algorithm est NULL, cette fonction demandera au serveur la valeur actuelle du réglage password_encryption. Cela peut être bloquant, et échouera si la transaction courante est annulée ou si la connexion est occupée à effectuer une autre requête. Si vous souhaitez utiliser l'algorithme par défaut du serveur mais que vous voulez éviter un blocage, vérifiez vous-même password_encryption avant d'appeler PQencryptPasswordConn, et fournissez cette valeur pour algorithm.

La valeur retournée est une chaîne allouée par malloc. L'appelant peut partir du principe que la chaîne ne contient pas de caractères spéciaux qui nécessiteraient un échappement. Utilisez PQfreemem pour libérer le résultat quand vous avez fini de l'utiliser. En cas d'erreur, NULL est retourné, et un message d'erreur adéquat est stocké dans l'objet de connexion.

PQencryptPassword

Prépare la version chiffrée en md5 du mot de passe PostgreSQL.

char *PQencryptPassword(const char *passwd, const char *user);
      

PQencryptPassword est une version ancienne et obsolète de PQencryptPasswordConn. La différence est que PQencryptPassword ne nécessite pas d'objet de connexion, et que l'algorithme de chiffrement utilisé est toujours md5.

PQmakeEmptyPGresult

Construit un objet PGresult vide avec le statut indiqué.

       PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
      

C'est une fonction interne de la libpq pour allouer et initialiser un objet PGresult vide. Cette fonction renvoit NULL si la mémoire n'a pas pu être allouée. Elle est exportée car certaines applications trouveront utiles de générer elles-mêmes des objets de résultat (tout particulièrement ceux avec des statuts d'erreur). Si conn n'est pas NULL et que status indique une erreur, le message d'erreur courant de la connexion indiquée est copié dans PGresult. De plus, si conn n'est pas NULL, toute procédure d'événement enregistrée dans la connexion est copiée dans le PGresult. (Elles n'obtiennent pas d'appels PGEVT_RESULTCREATE, mais jetez un œil à PQfireResultCreateEvents.) Notez que PQclear devra être appelé sur l'objet, comme pour un PGresult renvoyé par libpq lui-même.

PQfireResultCreateEvents

Déclenche un événement PGEVT_RESULTCREATE (voir Section 34.14) pour chaque procédure d'événement enregistrée dans l'objet PGresult. Renvoit autre chose que zéro en cas de succès, zéro si une des procédures d'événement échoue.

       int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
      

L'argument conn est passé aux procédures d'événement mais n'est pas utilisé directement. Il peut être NULL si les procédures de l'événement ne l'utilisent pas.

Les procédures d'événements qui ont déjà reçu un événement PGEVT_RESULTCREATE ou PGEVT_RESULTCOPY pour cet objet ne sont pas déclenchées de nouveau.

La raison principale pour séparer cette fonction de PQmakeEmptyPGresult est qu'il est souvent approprié de créer un PGresult et de le remplir avec des données avant d'appeler les procédures d'événement.

PQcopyResult

Fait une copie de l'objet PGresult. La copie n'est liée en aucune façon au résultat source et PQclear doit être appelée quand la copie n'est plus nécessaire. Si la fonction échoue, NULL est renvoyé.

       PGresult *PQcopyResult(const PGresult *src, int flags);
      

Cela n'a pas pour but de faire une copie exacte. Le résultat renvoyé a toujours le statut PGRES_TUPLES_OK, et ne copie aucun message d'erreur de la source. (Néanmoins, elle copie la chaîne de statut de commande.) L'argument flags détermine ce qui est copié. C'est un OR bit à bit de plusieurs drapeaux. PG_COPYRES_ATTRS indique la copie des attributs du résultat source (définition des colonnes). PG_COPYRES_TUPLES indique la copie des lignes du résultat source. (Cela implique de copier aussi les attributs.) PG_COPYRES_NOTICEHOOKS indique la copie des gestionnaires de notification du résultat source. PG_COPYRES_EVENTS indique la copie des événements du résultat source. (Mais toute instance de données associée avec la source n'est pas copiée.)

PQsetResultAttrs

Initialise les attributs d'un objet PGresult.

       int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
      

Les attDescs fournis sont copiés dans le résultat. Si le pointeur attDescs est NULL ou si numAttributes est inférieur à 1, la requête est ignorée et la fonction réussit. Si res contient déjà les attributs, la fonction échouera. Si la fonction échoue, la valeur de retour est zéro. Si la fonction réussit, la valeur de retour est différente de zéro.

PQsetvalue

Initialise la valeur d'un champ d'une ligne d'un objet PGresult.

       int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
      

La fonction fera automatiquement grossir le tableau de lignes internes des résultats, si nécessaire. Néanmoins, l'argument tup_num doit être inférieur ou égal à PQntuples, ceci signifiant que la fonction peut seulement faire grossir le tableau des lignes une ligne à la fois. Mais tout champ d'une ligne existante peut être modifié dans n'importe quel ordre. Si une valeur à field_num existe déjà, elle sera écrasée. Si len vaut 1 ou si value est NULL, la valeur du champ sera configurée à la valeur SQL NULL. value est copié dans le stockage privé du résultat, donc n'est plus nécessaire après le retour de la fonction. Si la fonction échoue, la valeur de retour est zéro. Dans le cas contraire, elle a une valeur différente de zéro.

PQresultAlloc

Alloue un stockage supplémentaire pour un objet PGresult.

       void *PQresultAlloc(PGresult *res, size_t nBytes);
      

Toute mémoire allouée avec cette fonction sera libérée quand res sera effacé. Si la fonction échoue, la valeur de retour vaut NULL. Le résultat est garanti d'être correctement aligné pour tout type de données, comme pour un malloc.

PQresultMemorySize

Renvoie le nombre d'octets alloués pour un objet PGresult.

size_t PQresultMemorySize(const PGresult *res);
      

La valeur est la somme de tous les appels malloc associés avec l'objet PGresult, c'est-à-dire tout l'espace qui peut être libéré par PQclear. Cette information est utile pour gérer la consommation mémoire.

PQlibVersion

Renvoie la version de libpq en cours d'utilisation.

      int PQlibVersion(void);
      

Le résultat de cette fonction peut être utilisé pour déterminer, à l'exécution, si certaines fonctionnalités spécifiques sont disponibles dans la version chargée de libpq. Par exemple, cette fonction peut être utilisée pour déterminer les options de connexions disponibles pour PQconnectdb.

Le résultat est obtenu en multipliant le numéro de version majeure de la bibliothèque par 10000 et en ajoutant le numéro de version mineure. Par exemple, la version 10.1 renverra 100001, et la version 11.0 renverra 110000.

Avant la version majeure 10, PostgreSQL utilisait des numéros de version en trois parties, pour lesquelles les deux premières parties représentaient la version majeure. Pour ces versions, PQlibVersion utilise deux chiffres pour chaque partie. Par exemple, la version 9.1.5 renverra 90105, et la version 9.2.0 renverra 90200.

De ce fait, pour déterminer la compatibilité de certaines fonctionnalités, les applications devraient diviser le résultat de PQlibVersion par 100, et non pas par 10000, pour déterminer le numéro de version majeure logique. Dans toutes les versions, seuls les deux derniers chiffres diffèrent entre des versions mineures (versions correctives).

Note

Cette fonction apparaît dans PostgreSQL 9.1, donc elle ne peut pas être utilisée pour détecter des fonctionnalités des versions précédentes car l'appeler créera une dépendance sur la version 9.1 et les versions ultérieures.