PostgreSQLLa base de données la plus sophistiquée au monde.

Version anglaise

33.11. Fonctions diverses

Comme toujours, certains 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û à l'allocation de la mémoire dans une DLL et la relâcher dans l'application fonctionne seulement 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 supplé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 envoyées 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 en clair en une forme chiffrée avant de l'envoyer. Les arguments sont le mot de passe en clair et le nom SQL de l'utilisateur. La valeur renvoyée est une chaîne allouée par malloc ou NULL s'il ne reste plus de mémoire. L'appelant assume que la chaîne ne contient aucun caractère spécial qui nécessiterait un échappement. Utilisez PQfreemem pour libérer le résultat une fois terminé.

Les arguments passwd et user sont des mots de passe en clair, et le nom SQL de l'utilisateur à qui ils correspondent. 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 anciennes versions de serveur). Veuillez noter que le support de scram-sha-256 a été introduit dans la version 10 de PostgreSQL™, et ne fonctionnera pas corrrectement avec des versions de serveur plus ancienne. Si algorithm est NULL, cette fonction demandera au serveur pour 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 dépréciée et PQencryptPasswordConn. La différence est que PQencryptPassword ne nécessite pas d'objet de connexion, et que md5 est toujours utilisé comme algorithme de chiffrement.

PQmakeEmptyPGresult

Construit un objet PGresult vide avec la 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 eux-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 actuel 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 33.13, « Système d'événements ») pour chaque procédure d'événement enregistré dans l'objet PGresult. Renvoit autre chose que zéro en cas de succès, zéro si la procédure 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'utiliseront 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 dans que 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 dans la source. (Néanmoins, il copie la chaîne de statut de commande.) L'argument flags détermine le reste à copier. 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 au 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 est libérée quand res est effacée. 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.

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 devrait 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]

Note

Cette fonction apparaît en version 9.1 de PostgreSQL™, 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.