libpq.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

 <chapter id="libpq">
  <title><application>libpq</application> - Bibliothèque C</title>

  <indexterm zone="libpq">
   <primary>libpq</primary>
  </indexterm>

  <indexterm zone="libpq">
   <primary>C</primary>
  </indexterm>

  <para>
   <application>libpq</application> est l'interface de programmation pour les
   applications <acronym>C</acronym> avec <productname>PostgreSQL</productname>.
   <application>libpq</application> est un ensemble de fonctions permettant aux
   programmes clients d'envoyer des requêtes au serveur
   <productname>PostgreSQL</productname> et de recevoir les résultats de ces
   requêtes.
  </para>

  <para>
   <application>libpq</application> est aussi le
   moteur sous-jacent de plusieurs autres interfaces de programmation de
   <productname>PostgreSQL</productname>, comme ceux écrits pour C++, Perl,
   Python, Tcl et <application>ECPG</application>. Donc, certains aspects du comportement
   de <application>libpq</application> seront importants pour vous si vous utilisez un de
   ces paquetages. En particulier, la <xref linkend="libpq-envars"/>, la
   <xref linkend="libpq-pgpass"/> et la <xref linkend="libpq-ssl"/> décrivent le
   comportement que verra l'utilisateur de toute application utilisant
   <application>libpq</application>.
  </para>

  <para>
   Quelques petits programmes sont inclus à la fin de ce chapitre (<xref
   linkend="libpq-example"/>) pour montrer comment écrire des programmes
   utilisant <application>libpq</application>. Il existe aussi quelques exemples
   complets d'applications <application>libpq</application> dans le répertoire
   <filename>src/test/examples</filename> venant avec la distribution des
   sources.
  </para>

  <para>
   Les programmes clients utilisant <application>libpq</application> doivent
   inclure le fichier d'en-tête
   <filename>libpq-fe.h</filename><indexterm><primary>libpq-fe.h</primary></indexterm> et
   doivent être lié avec la bibliothèque <application>libpq</application>.
  </para>

 <sect1 id="libpq-connect">
  <title>Fonctions de contrôle de connexion à la base de données</title>

  <para>
   Les fonctions suivantes concernent la réalisation d'une connexion avec un
   serveur <productname>PostgreSQL</productname>. Un programme peut avoir
   plusieurs connexions ouvertes sur des serveurs à un même moment (une raison
   de la faire est d'accéder à plusieurs bases de données). Chaque connexion
   est représentée par un objet
   <structname>PGconn</structname><indexterm><primary>PGconn</primary></indexterm>, obtenu avec la
   fonction <function>PQconnectdb</function>,
   <function>PQconnectdbParams</function>, ou <function>PQsetdbLogin</function>. Notez que
   ces fonctions renverront toujours un pointeur d'objet non nul, sauf peut-être
   dans un cas de manque de mémoire pour l'allocation de l'objet
   <structname>PGconn</structname>. La fonction <function>PQstatus</function>
   doit être appelée pour vérifier le code retour pour une connexion réussie
   avant de lancer des requêtes via l'objet de connexion.

   <warning>
    <para>
     Sur Unix, la création d'un processus via l'appel système fork() avec des
     connexions libpq ouvertes peut amener à des résultats imprévisibles car
     les processus parent et enfants partagent les même sockets et les mêmes
     ressources du système d'exploitation. Pour cette raison, un tel usage n'est
     pas recommandé, alors qu'exécuter un <function>exec</function> à partir
     du processus enfant pour charger un nouvel exécutable est sûr.
    </para>
   </warning>

   <note>
    <para>
     Sur Windows, il existe un moyen pour améliorer les performances si une
     connexion seule à la base de données est ouverte puis fermée de façon
     répétée. En interne, libpq appelle <function>WSAStartup()</function> et
     <function>WSACleanup()</function> respectivement pour le début et la fin
     de la transaction. <function>WSAStartup()</function> incrémente un
     compteur de référence interne à la bibliothèque Windows.
     Ce compteur est décrémenté par <function>WSACleanup()</function>. Quand le compteur arrive à
     un, appeler <function>WSACleanup()</function> libère toutes les ressources et toutes les DLL
     associées. C'est une opération coûteuse. Pour éviter cela, une application
     peut appeler manuellement <function>WSAStartup()</function> afin que les ressources ne soient
     pas libérées quand la dernière connexion est fermée.
    </para>
   </note>

   <variablelist>
    <varlistentry id="libpq-pqconnectdbparams">
     <term><function>PQconnectdbParams</function><indexterm><primary>PQconnectdbParams</primary></indexterm></term>
     <listitem>
      <para>
       Établit une nouvelle connexion au serveur de base de données.

       <synopsis>
PGconn *PQconnectdbParams(const char * const *keywords,
                          const char * const *values,
                          int expand_dbname);
       </synopsis>
      </para>

      <para>
       Cette fonction ouvre une nouvelle connexion à la base de données en
       utilisant les paramètres à partir des deux tableaux terminés par un
       <symbol>NULL</symbol>. Le premier, <literal>keywords</literal>, est
       défini comme un tableau de chaînes, chacune étant un mot-clé. Le second,
       <literal>values</literal>, donne la valeur pour chaque mot-clé.
       Contrairement à <function>PQsetdbLogin</function> ci-dessous, l'ensemble
       des paramètres peut être étendu sans changer la signature de la fonction
       donc son utilisation (ou ses versions non bloquantes, à savoir
       <function>PQconnectStartParams</function> et
       <function>PQconnectPoll</function>) est recommendée pour les nouvelles
       applications.
      </para>

      <para>
       Les mots clés actuellement reconnus sont listés dans
       <xref linkend="libpq-paramkeywords"/>.
      </para>

      <para>
       Quand <literal>expand_dbname</literal> est différent de zéro, la valeur
       du mot-clé <parameter>dbname</parameter> peut être reconnue comme une
       chaîne de connexion. Les formats possibles sont disponibles dans
       <xref linkend="libpq-connstring"/> avec de nombreux détails.
      </para>

      <para>
       Les tableaux fournis peuvent être vides pour utiliser tous les
       paramètres par défaut ou peuvent contenir un ou plusieurs paramètres.
       Ils doivent avoir la même longueur. Le traitement stoppera au premier
       élément <symbol>NULL</symbol> découvert dans le tableau
       <literal>keywords</literal>.
      </para>

   <para>
   Si un paramètre manque, alors la variable d'environnement correspondante
   est vérifiée (voir la <xref linkend="libpq-envars"/>). Si elle n'est pas
   disponible, alors la valeur par défaut indiquée est utilisée.
   </para>

      <para>
        En général, les mots-clés sont traités à partir du début de ces
        tableaux dans l'ordre de l'index. L'effet qui en découle est que,
        quand les mots-clés sont répétés, la valeur correspondant au dernier
        traitement est conservée. Du coup, via un placement attentionné du
        mot-clé <parameter>dbname</parameter>, il est possible de déterminer
        ce qui pourrait être surchargé par une chaîne
        <parameter>conninfo</parameter> et ce qui ne le sera pas.
      </para>

     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqconnectdb">
     <term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</primary></indexterm></term>
     <listitem>
      <para>
       Établit une nouvelle connexion à un serveur de bases de données.

       <synopsis>
        PGconn *PQconnectdb(const char *conninfo);
       </synopsis>
      </para>

      <para>
       Cette fonction ouvre une nouvelle connexion à la base de données en
       utilisant les paramètres pris à partir de la chaîne
       <literal>conninfo</literal>.
      </para>

      <para>
       La chaîne passée peut être vide pour utiliser tous les paramètres par
       défaut ou elle peut contenir un ou plusieurs paramètres, séparés par
       des espaces blancs. Elle peut aussi contenir une <acronym>URI</acronym>.
       Voir <xref linkend="libpq-connstring"/> pour les détails.
      </para>

      </listitem>
 </varlistentry>

 <varlistentry id="libpq-pqsetdblogin">
  <term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</primary></indexterm></term>
  <listitem>
   <para>
       Crée une nouvelle connexion sur le serveur de bases de données.
<synopsis>PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);
</synopsis>
</para>

<para>
   C'est le prédécesseur de <function>PQconnectdb</function> avec un ensemble
   fixe de paramètres. Cette fonction a les mêmes fonctionnalités sauf que les
   paramètres manquants seront toujours initialisés avec leur valeurs par
   défaut. Écrire <symbol>NULL</symbol> ou une chaîne vide pour un de ces
   paramètres fixes dont vous souhaitez utiliser la valeur par défaut.
   </para>

      <para>
        Si <parameter>dbName</parameter> contient un signe <symbol>=</symbol> ou
        a un préfixe <acronym>URI</acronym> de connexion valide,
	il est pris pour une chaîne <parameter>conninfo</parameter> exactement
	de la même façon que si elle était passée à
	<function>PQconnectdb</function>, et le reste des paramètres est
	ensuite appliqué as specified for <function>PQconnectdbParams</function>.
      </para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pqsetdb">
  <term><function>PQsetdb</function><indexterm><primary>PQsetdb</primary></indexterm></term>
  <listitem>
   <para>
   Crée une nouvelle connexion sur le serveur de bases de données.
<synopsis>PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);
</synopsis>
</para>

<para>
   C'est une macro faisant appel à <function>PQsetdbLogin</function> avec des
   pointeurs nuls pour les paramètres <parameter>login</parameter> et <parameter>pwd</parameter>.
   Elle est fournie pour une compatibilité ascendante des très vieux programmes.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pqconnectstartparams">
  <term><function>PQconnectStartParams</function><indexterm><primary>PQconnectStartParams</primary></indexterm></term>
  <term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</primary></indexterm></term>
  <term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</primary></indexterm></term>
  <listitem>
  <para>
   <indexterm><primary>connexion non bloquante</primary></indexterm>
   Crée une connexion au serveur de bases de données d'une façon non bloquante.
<synopsis>PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *values,
                              int expand_dbname);

PGconn *PQconnectStart(const char *conninfo);

PostgresPollingStatusType PQconnectPoll(PGconn *conn);
</synopsis>
</para>
<para>
   Ces trois fonctions sont utilisées pour ouvrir une connexion au serveur de 
   bases de données d'une façon telle que le thread de votre application n'est
   pas bloqué sur les entrées/sorties distantes en demandant la connexion. Le
   but de cette approche est que l'attente de la fin des entrées/sorties peut se
   faire dans la boucle principale de l'application plutôt qu'à l'intérieur de
   <function>PQconnectdbParams</function> ou <function>PQconnectdb</function>, et donc l'application peut gérer des opérations en
   parallèle à d'autres activités.
  </para>
      <para>
       Avec <function>PQconnectStartParams</function>, la connexion à la base
       de données est faite en utilisant les paramètres à partir des tableaux
       <literal>keywords</literal> et <literal>values</literal>, et contrôlée
       par <literal>expand_dbname</literal>, comme décrit dans
       <xref linkend="libpq-paramkeywords"/>.
      </para>

      <para>
       Avec <function>PQconnectStart</function>, la connexion à la base de
       données est faite en utilisant les paramètres provenant de la chaîne
       <literal>conninfo</literal> comme décrit ci-dessus pour
       <function>PQconnectdb</function>.
      </para>

      <para>
  <para>
   Ni <function>PQconnectStartParams</function> ni
   <function>PQconnectStart</function> ni <function>PQconnectPoll</function>
   ne bloqueront, aussi longtemps qu'un certain nombre de restrictions est
   respecté&nbsp;:
   <itemizedlist>
    <listitem>
     <para>
      Les paramètres <literal>hostaddr</literal> et <literal>host</literal> sont utilisés de
      façon appropriée pour vous assurer que la requête de nom et la requête
      inverse ne soient pas lancées. Voir la documentation de ces paramètres avec
      <function>PQconnectdbParams</function> ci-dessus pour les détails.
     </para>
    </listitem>

    <listitem>
     <para>
      Si vous appelez <function>PQtrace</function>, assurez-vous que l'objet de
      flux dans lequel vous enregistrez les traces ne bloquera pas.
     </para>
    </listitem>

    <listitem>
     <para>
      Assurez-vous que le socket soit dans l'état approprié avant d'appeler
      <function>PQconnectPoll</function>, comme décrit ci-dessous.
     </para>
    </listitem>
   </itemizedlist>
  </para>

      <para>
       Note&nbsp;: l'utilisation de <function>PQconnectStartParams</function>
       est analogue à <function>PQconnectStart</function> affichée ci-dessous.
      </para>

  <para>
   Pour commencer une demande de connexion non bloquante, appelez <literal>conn
   = PQconnectStart("<replaceable>connection_info_string</replaceable>")</literal>.
   Si <varname>conn</varname> est nul, alors <application>libpq</application> a été
   incapable d'allouer une nouvelle structure <structname>PGconn</structname>. Sinon, un
   pointeur valide vers une structure <structname>PGconn</structname> est renvoyé (bien
   qu'il ne représente pas encore une connexion valide vers la base de
   données). Au retour de <function>PQconnectStart</function>, appelez
   <literal>status = PQstatus(conn)</literal>. Si <varname>status</varname> vaut
   <symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> a
   échoué.
  </para>
  <para>
   Si <function>PQconnectStart</function> réussit, la prochaine étape est d'appeler
   souvent <application>libpq</application> de façon à ce qu'il continue la séquence de
   connexion. Utilisez <function>PQsocket(conn)</function> pour obtenir le
   descripteur de socket sous la connexion à la base de données. Du coup, une
   boucle&nbsp;: si le dernier retour de
   <function>PQconnectPoll(conn)</function> est
   <symbol>PGRES_POLLING_READING</symbol>, attendez que la socket soit prête
   pour lire (comme indiqué par <function>select()</function>, <function>poll()</function> ou
   une fonction système similaire). Puis, appelez de nouveau
   <function>PQconnectPoll(conn)</function>. En revanche, si le dernier retour de
   <function>PQconnectPoll(conn)</function> est
   <symbol>PGRES_POLLING_WRITING</symbol>, attendez que la socket soit prête
   pour écrire, puis appelez de nouveau
   <function>PQconnectPoll(conn)</function>. Si vous devez encore appeler
   <function>PQconnectPoll</function>, c'est-à-dire juste après l'appel de
   <function>PQconnectStart</function>, continuez comme s'il avait renvoyé
   <symbol>PGRES_POLLING_WRITING</symbol>. Continuez cette boucle jusqu'à ce que
   <function>PQconnectPoll(conn)</function> renvoie
   <symbol>PGRES_POLLING_FAILED</symbol>, indiquant que la procédure de
   connexion a échoué ou <symbol>PGRES_POLLING_OK</symbol>, indiquant le
   succès de la procédure de connexion.
  </para>

  <para>
    À tout moment pendant la connexion, le statut de cette connexion pourrait 
    être vérifié en appelant <function>PQstatus</function>. Si le résultat est
    <symbol>CONNECTION_BAD</symbol>, alors la procédure de connexion a échoué&nbsp;;
    si, au contraire, elle renvoie <function>CONNECTION_OK</function>, alors la
    connexion est prête. Ces deux états sont détectables à partir de la valeur
    de retour de <function>PQconnectPoll</function>, décrite ci-dessus. D'autres états
    pourraient survenir lors (et seulement dans ce cas) d'une procédure de
    connexion asynchrone. Ils indiquent l'état actuel de la procédure de
    connexion et pourraient être utile pour fournir un retour à l'utilisateur.
    Ces statuts sont&nbsp;:
  </para>

    <variablelist>
     <varlistentry id="libpq-connection-started">
      <term><symbol>CONNECTION_STARTED</symbol></term>
      <listitem>
       <para>
        Attente de la connexion à réaliser.
       </para>
      </listitem>
     </varlistentry> 

     <varlistentry id="libpq-connection-made">
      <term><symbol>CONNECTION_MADE</symbol></term>
      <listitem>
       <para>
        Connexion OK&nbsp;; attente d'un envoi.
       </para>
      </listitem>
     </varlistentry>  

     <varlistentry id="libpq-connection-awaiting-response">
      <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
      <listitem>
       <para>
        Attente d'une réponse du serveur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="libpq-connection-auth-ok">
      <term><symbol>CONNECTION_AUTH_OK</symbol></term>
      <listitem>
       <para>
        Authentification reçue&nbsp;; attente de la fin du lancement du moteur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="libpq-connection-ssl-startup">
      <term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
      <listitem>
       <para>
        Négociation du cryptage SSL.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="libpq-connection-setenv">
      <term><symbol>CONNECTION_SETENV</symbol></term>
      <listitem>
       <para>
        Négociation des paramétrages de l'environnement.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>

  <para>
    Notez que, bien que ces constantes resteront (pour maintenir une
    compatibilité), une application ne devrait jamais se baser sur un ordre
    pour celles-ci ou sur tout ou sur le fait que le statut fait partie de ces
    valeurs documentés. Une application pourrait faire quelque chose comme
    ça&nbsp;:
<programlisting>switch(PQstatus(conn))
{
    case CONNECTION_STARTED:
        feedback = "Connexion en cours...";
        break;

    case CONNECTION_MADE:
        feedback = "Connecté au serveur...";
        break;
.
.
.
    default:
        feedback = "Connexion...";
}
</programlisting>
  </para>

  <para>
   Le paramètre de connexion <literal>connect_timeout</literal> est ignoré lors
   de l'utilisation <function>PQconnectPoll</function>&nbsp;; c'est de la
   responsabilité de l'application de décider quand une période de temps
   excessive s'est écoulée. Sinon, <function>PQconnectStart</function> suivi par
   une boucle <function>PQconnectPoll</function> est équivalent à
   <function>PQconnectdb</function>.
  </para>

  <para>
   Notez que si <function>PQconnectStart</function> renvoie un pointeur non
   nul, vous devez appeler <function>PQfinish</function> lorsque vous en avez
   terminé avec lui, pour supprimer la structure et tous les blocs mémoires qui
   lui sont associés. Ceci doit être fait même si la tentative de connexion
   échoue ou est abandonnée.
  </para>
  </para>
 </listitem>
 </varlistentry>

 <varlistentry id="libpq-pqconndefaults">
  <term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</primary></indexterm></term>
  <listitem>
   <para>
   Renvoie les options de connexion par défaut.
<synopsis>PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* Mot clé de l'option */
    char   *envvar;    /* Nom de la variable d'environnement équivalente */
    char   *compiled;  /* Valeur par défaut interne */
    char   *val;       /* Valeur actuelle de l'option ou NULL */
    char   *label;     /* Label du champ pour le dialogue de connexion */
    char   *dispchar;  /* Indique comment afficher ce champ
                          dans un dialogue de connexion. Les valeurs sont :
                          ""        Affiche la valeur entrée sans modification
                          "*"       Champ de mot de passe - cache la valeur
                          "D"       Option de débogage - non affiché par défaut
                       */
    int     dispsize;  /* Taille du champ en caractère pour le dialogue */
} PQconninfoOption;
</synopsis>
</para>

<para>
   Renvoie un tableau d'options de connexion. Ceci pourrait être utilisé pour
   déterminer toutes les options possibles de <function>PQconnectdb</function>
   et leur valeurs par défaut. La valeur de retour pointe vers un tableau de
   structures <structname>PQconninfoOption</structname> qui se termine avec une
   entrée utilisant un pointeur nul pour <structfield>keyword</structfield>. Le pointeur
   null est renvoyé si la mémoire n'a pas pu être allouée. Notez que les
   valeurs par défaut actuelles (champs <structfield>val</structfield>)
   dépendront des variables d'environnement et d'autres contextes. Les
   demandeurs doivent traiter les données des options de connexion en lecture
   seule.
   </para>

   <para>
    Après le traitement du tableau d'options, libérez-le en le passant à la
    fonction <function>PQconninfoFree</function>. Si cela n'est pas fait, un
    petit groupe de mémoire est perdu à chaque appel de
    <function>PQconndefaults</function>.
   </para>

  </listitem>
 </varlistentry>

    <varlistentry id="libpq-pqconninfo">
     <term><function>PQconninfo</function><indexterm><primary>PQconninfo</primary></indexterm></term>
     <listitem>
      <para>
       Returns the connection options used by a live connection.
<synopsis>
PQconninfoOption *PQconninfo(PGconn *conn);
</synopsis>
      </para>

      <para>
       Returns a connection options array.  This can be used to determine
       all possible <function>PQconnectdb</function> options and the
       values that were used to connect to the server. The return
       value points to an array of <structname>PQconninfoOption</structname>
       structures, which ends with an entry having a null <structfield>keyword</structfield>
       pointer. All notes above for <function>PQconndefaults</function> also
       apply to the result of <function>PQconninfo</function>.
      </para>

     </listitem>
    </varlistentry>


    <varlistentry id="libpq-pqconninfoparse">
     <term><function>PQconninfoParse</function><indexterm><primary>PQconninfoParse</primary></indexterm></term>
     <listitem>
      <para>
       Renvoit les options de connexions analysées d'après la chaîne de
       connexion fournie.

<synopsis>
PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
</synopsis>
      </para>

      <para>
       Analyse une chaîne de connexion et renvoie les options résultantes
       dans un tableau&nbsp;; renvoit <symbol>NULL</symbol> si un problème a été détecté avec
       la chaîne de connexion. Ceci peut être utilisé pour déterminer les
       options de <function>PQconnectdb</function> dans la chaîne de connexion
       fournie. La valeur de retour pointe vers un tableau de structures
       <structname>PQconninfoOption</structname> et termine avec une entrée
       ayant un pointeur <structfield>keyword</structfield> nul.
      </para>

      <para>
       Toutes les options légales seront présentes dans le tableau en résultat
       mais le <literal>PQconninfoOption</literal> pour toute option absente
       de la chaîne de connexion aura sa valeur (<literal>val</literal>)
       configurée à <literal>NULL</literal>&nbsp;; les valeurs par défaut ne
       sont pas utilisées.
      </para>

      <para>
       Si <literal>errmsg</literal> n'est pas <symbol>NULL</symbol>, alors
       <literal>*errmsg</literal> est configuré à <symbol>NULL</symbol> en cas de succès et sinon
       à un message d'erreur (alloué via un appel à <function>malloc</function>) expliquant le
       problèm. (Il est aussi possible pour <literal>*errmsg</literal> d'être
       configuré à <symbol>NULL</symbol> et la fonction de renvoyer <symbol>NULL</symbol>&nbsp;; cela indique un
       cas de mémoire épuisée.)
      </para>

      <para>
       Après avoir traité le tableau des options, libérez-le en le passant à
       <function>PQconninfoFree</function>. Si ce n'est pas fait, de la mémoire
       sera perdu à chaque appel à <function>PQconninfoParse</function>.
       Réciproquement, si une erreur survient et que <literal>errmsg</literal>
       n'est pas <symbol>NULL</symbol>, assurez-vous de libérer la chaîne d'erreur en utilisant
       <function>PQfreemem</function>.
      </para>

   </listitem>
    </varlistentry>

 <varlistentry id="libpq-pqfinish">
  <term><function>PQfinish</function><indexterm><primary>PQfinish</primary></indexterm></term>
  <listitem>
   <para>
   Ferme la connexion au serveur. Libère aussi la mémoire utilisée par l'objet
   <structname>PGconn</structname>.
<synopsis>void PQfinish(PGconn *conn);
</synopsis>
</para>

<para>
   Notez que même si la connexion au serveur a échoué (d'après l'indication 
   de <function>PQstatus</function>), l'application devrait appeler
   <function>PQfinish</function> pour libérer la mémoire utilisée par l'objet
   <structname>PGconn</structname>. Le pointeur <structname>PGconn</structname> ne doit
   pas être encore utilisé après l'appel à <function>PQfinish</function>.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pqreset">
  <term><function>PQreset</function><indexterm><primary>PQreset</primary></indexterm></term>
  <listitem>
   <para>
   Réinitialise le canal de communication avec le serveur.
<synopsis>void PQreset(PGconn *conn);
</synopsis>
</para>

<para>
   Cette fonction fermera la connexion au serveur et tentera le rétablissement
   d'une nouvelle connexion au même serveur en utilisant tous les paramètres
   utilisés précédemment. Ceci pourrait être utile en cas de récupération après
   une perte de connexion.
   </para>
  </listitem>
 </varlistentry>

    <varlistentry id="libpq-pqresetstart">
     <term><function>PQresetStart</function><indexterm><primary>PQresetStart</primary></indexterm></term>
     <term><function>PQresetPoll</function><indexterm><primary>PQresetPoll</primary></indexterm></term>
     <listitem>
      <para>
       Réinitialise le canal de communication avec le serveur d'une façon non
       bloquante.

<synopsis>
int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);
</synopsis>
      </para>

      <para>
       Ces fonctions fermeront la connexion au serveur et tenteront de rétablir
       une nouvelle connexion sur le même serveur, en utilisant tous les paramètres
       précédemment utilisés. Ceci peut être utile pour revenir à un état normal
       après une erreur si une connexion est perdue. Ces fonctions diffèrent de
       <function>PQreset</function> (ci-dessus) dans le fait qu'elles agissent
       d'une façon non bloquante. Ces fonctions souffrent des mêmes restrictions
       que <function>PQconnectStartParams</function>, <function>PQconnectStart</function>
       et <function>PQconnectPoll</function>.
      </para>

      <para>
       Pour lancer une réinitialisation de la connexion, exécutez
       <function>PQresetStart</function>. Si cette fonction 0, la réinitialisation
       a échoué. Si elle renvoie 1, récupérez le résultat de la réinitialisation
       en utilisant <function>PQresetPoll</function> exactement de la même
       façon que vous auriez créé la connexion en utilisant
       <function>PQconnectPoll</function>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqpingparams">
     <term><function>PQpingParams</function><indexterm><primary>PQpingParams</primary></indexterm></term>
     <listitem>
      <para>
       <function>PQpingParams</function> renvoie le statut du serveur. Elle
       accepte les mêmes paramètres de connexion que ceux de la fonction
       <function>PQconnectdbParams</function>, décrite ci-dessus. Néanmoins,
       il n'est pas nécessaire de fournir les bons nom d'utilisateur, mot de
       passe, ou nom de base de données pour obtenir le statut du serveur.
       however, if incorrect values
       are provided, the server will log a failed connection attempt.

<synopsis>
PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);
</synopsis>

       La fonction renvoie une des valeurs suivantes&nbsp;:

       <variablelist>
        <varlistentry id="libpq-pqpingparams-pqping-ok">
         <term><literal>PQPING_OK</literal></term>
         <listitem>
          <para>
           Le serveur est en cours d'exécution et semble accepter les
           connexions.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-pqpingparams-pqping-reject">
         <term><literal>PQPING_REJECT</literal></term>
         <listitem>
          <para>
           Le serveur est en cours d'exécution mais est dans un état qui
           interdit les connexions (démarrage, arrêt, restauration après
           crash).
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-pqpingparams-pqping-no-response">
         <term><literal>PQPING_NO_RESPONSE</literal></term>
         <listitem>
          <para>
           Le serveur n'a pas pu être contacté. Cela pourrait indiquer que
           le serveur n'est pas en cours d'exécution ou qu'il y a un problème
           avec les paramètres de connexion donnés (par exemple un mauvais
           numéro de port). Cela peut aussi indiquer un problème de connexion
           réseau (par exemple un pare-feu qui bloque la demande de connexion).
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-pqpingparams-pqping-no-attempt">
         <term><literal>PQPING_NO_ATTEMPT</literal></term>
         <listitem>
          <para>
           Aucune tentative n'a été faite pour contacter le serveur à cause des
           paramètres fournis erronnés ou à cause d'un problème au niveau client
           (par exemple un manque mémoire).
          </para>
         </listitem>
        </varlistentry>
       </variablelist>

      </para>

     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqping">
     <term><function>PQping</function><indexterm><primary>PQping</primary></indexterm></term>
     <listitem>
      <para>
       <function>PQping</function> renvoie l'état du serveur.  Elle
       accepte les mêmes paramètres de connexion que ceux de la fonction
       <function>PQconnectdb</function>, décrite ci-dessus. Néanmoins,
       il n'est pas nécessaire de fournir les bons nom d'utilisateur, mot de
       passe, ou nom de base de données pour obtenir le statut du serveur; however, if incorrect values
       are provided, the server will log a failed connection attempt.

<synopsis>
PGPing PQping(const char *conninfo);
</synopsis>
      </para>

      <para>
       Les valeurs de retour sont les mêmes que pour <function>PQpingParams</function>.
      </para>

     </listitem>
    </varlistentry>

   </variablelist>
  </para>

  <sect2 id="libpq-connstring">
   <title>Chaînes de connexion</title>

   <indexterm zone="libpq-connstring">
    <primary><literal>conninfo</literal></primary>
   </indexterm>

   <indexterm zone="libpq-connstring">
    <primary><literal>URI</literal></primary>
   </indexterm>

   <para>
    Plusieurs fonctions de la bibliothèque <application>libpq</application>
    analysent une chaîne donnée par l'utilisateur pour obtenir les paramètres
    de connexion. Deux formats sont acceptés pour ces chaînes&nbsp;:
    le format régulier <literal>keyword = value</literal> et le format des
    URI <ulink url="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</ulink>.
   </para>

   <sect3>
    <title>Chaînes de connexion clé/valeur</title>

   <para>
    Dans le premier format, chaque configuration de paramètre se présente sous
    la forme <literal>clé = valeur</literal>. Les espaces autour du signe égal
    sont optionnels. Pour écrire une valeur vide ou une valeur contenant des
    espaces, il est nécessaires de l'entourer de guillemets simples, par
    exemple <literal>clé = 'une valeur'</literal>. Les guillemets simples et
    les antislashs compris dans une valeur doivent être échappés par un
    antislash, comme ceci <literal>\'</literal> et ceci <literal>\\</literal>.
   </para>

   <para>
    Example:
<programlisting>
host=localhost port=5432 dbname=mabase connect_timeout=10
</programlisting>
   </para>

   <para>
    Les mots clés reconnus pour les paramètres sont listés dans <xref
    linkend="libpq-paramkeywords"/>.
   </para>
   </sect3>

   <sect3>
    <title>URI de connexion</title>

   <para>
   La forme générale pour une <acronym>URI</acronym> de connexion est&nbsp;:
<synopsis>
postgresql://[utilisateur[:mot_de_passe]@][alias_ou_ip][:port][/nom_base][?param1=valeur1&amp;...]
</synopsis>
   </para>

   <para>
    Le désignateur d<acronym>URI</acronym> peut être soit
    <literal>postgresql://</literal> soit <literal>postgres://</literal>.
    Chacune des parties de l'<acronym>URI</acronym> est optionnelle. Les
    exemples suivants montrent des syntaxes valides pour
    l'<acronym>URI</acronym>&nbsp;:
<programlisting>
postgresql://
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/ma_base
postgresql://utilisateur@localhost
postgresql://utilisateur:secret@localhost
postgresql://autre@localhost/autre_base?connect_timeout=10&amp;application_name=mon_appli
</programlisting>
    Les composants de la partie hiérarchique de l'<acronym>URI</acronym> peuvent
    aussi être donnés comme paramètres. Par exemple&nbsp;:
<programlisting>
postgresql:///ma_base?host=localhost&amp;port=5433
</programlisting>
   </para>

   <para>
    L'encodage du signe pourcent peut être utilisé pour inclure des symboles
    dotés d'une signification spéciale dans toutes les parties de
    l'<acronym>URI</acronym>.
   </para>

   <para>
    Tout paramètre de connexion ne correspondant pas aux mots clés listés dans
    <xref linkend="libpq-paramkeywords"/> est ignoré et un message d'avertissement
    les concernant est envoyé sur la sortie des erreurs (<filename>stderr</filename>).
   </para>

   <para>
    Pour améliorer la compatibilité avec les <acronym>URI</acronym> des
    connexions, les instances du paramètre <literal>ssl=true</literal> sont
    traduites en <literal>sslmode=require</literal>.
   </para>

   <para>
    La partie host peut être soit un nom d'hôte soit une adresse IP. Pour
    indiquer une adresse IPv6, il est nécessaire de l'englober dans des
    crochets&nbsp;:
<synopsis>
postgresql://[2001:db8::1234]/database
</synopsis>
   </para>

   <para>
    Le composant host est interprété de la façon décrite pour le paramètre
    <xref linkend="libpq-connect-host"/>. En particulier, une connexion par
    socket de domaine Unix est choisi si la partie host est vide ou commence
    par un slash. Dans tous les autres cas, une connexion TCP/IP est
    démarrée. Cependant, notez que le slash est un caractère réservé dans la
    partie hiérarchique de l'URI. Donc, pour indiquer un répertoire non standard
    pour la socket de domaine Unix, il faut soit omettre d'indiquer le paramètre
    host dans l'URI, soit l'indiquer en tant que paramètre, soit encoder le
    chemin dans le composant host de l'URI&nbsp;:
<programlisting>
postgresql:///dbname?host=/var/lib/postgresql
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
</programlisting>
   </para>
   </sect3>
  </sect2>

  <sect2 id="libpq-paramkeywords">
   <title>Mots clés de la chaîne de connexion</title>

   <para>
   Les mots clés actuellement reconnus sont&nbsp;:

   <variablelist>
    <varlistentry id="libpq-connect-host" xreflabel="host">
     <term><literal>host</literal></term>
     <listitem>
     <para>
      Nom de l'hôte sur lequel se connecter.<indexterm><primary>host name</primary></indexterm>
      S'il commence avec un slash, il spécifie une communication par domaine
      Unix plutôt qu'une communication TCP/IP&nbsp;; la valeur est le nom du
      répertoire où le fichier socket est stocké. Par défaut, quand
      <literal>host</literal> n'est pas spécifié, il s'agit d'une communication par
      socket de domaine Unix<indexterm><primary>socket de domaine Unix</primary></indexterm>
      dans <filename>/tmp</filename> (ou tout autre répertoire de socket spécifié
      lors de la construction de <productname>PostgreSQL</productname>). Sur les machines
      sans sockets de domaine Unix, la valeur par défaut est de se connecter
      à <literal>localhost</literal>.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-connect-hostaddr" xreflabel="hostaddr">
     <term><literal>hostaddr</literal></term>
     <listitem>
     <para>
      Adresse IP numérique de l'hôte de connexion. Elle devrait être au format
      d'adresse standard IPv4, c'est-à-dire <literal>172.28.40.9</literal>. Si votre
      machine supporte IPv6, vous pouvez aussi utiliser ces adresses. La
      communication TCP/IP est toujours utilisée lorsqu'une chaîne non vide est
      spécifiée pour ce paramètre.
     </para>
     <para>
      Utiliser <literal>hostaddr</literal> au lieu de <literal>host</literal>
      permet à l'application d'éviter une recherche de nom d'hôte, qui
      pourrait être importante pour les applications ayant des
      contraintes de temps. Un nom d'hôte est requis pour les méthodes
      d'authentification Kerberos, GSSAPI ou SSPI, ainsi que pour la
      vérification de certificat SSL en <literal>verify-full</literal>.
      Les règles suivantes sont observées&nbsp;:
           <itemizedlist>
            <listitem>
             <para>
              Si <literal>host</literal> est indiqué sans
              <literal>hostaddr</literal>, une recherche du nom de l'hôte
              est lancée.
             </para>
            </listitem>
            <listitem>
             <para>
              Si <literal>hostaddr</literal> est indiqué sans
              <literal>host</literal>, la valeur de
              <literal>hostaddr</literal> donne l'adresse réseau de
              l'hôte. La tentative de connexion échouera si la méthode
              d'authentification nécessite un nom d'hôte.
             </para>
            </listitem>
            <listitem>
             <para>
              Si <literal>host</literal> et <literal>hostaddr</literal>
              sont indiqués, la valeur de <literal>hostaddr</literal>
              donne l'adresse réseau de l'hôte. La valeur de
              <literal>host</literal> est ignorée sauf si la méthode
              d'authentification la réclame, auquel cas elle sera
              utilisée comme nom d'hôte.
             </para>
            </listitem>
           </itemizedlist>
      Notez que l'authentification a de grandes chances d'échouer si
      <literal>host</literal> n'est pas identique au nom du serveur
      pour l'adresse réseau <literal>hostaddr</literal>.
      De même, <literal>host</literal> plutôt
      que <literal>hostaddr</literal> est utilisé pour identifier la connexion
      dans <filename>~/.pgpass</filename> (voir la <xref
      linkend="libpq-pgpass"/>).
     </para>
     <para>
      Sans un nom ou une adresse d'hôte, <application>libpq</application> se
      connectera en utilisant un socket local de domaine Unix. Sur des machines
      sans sockets de domaine Unix, il tentera une connexion sur
      <literal>localhost</literal>.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-connect-port" xreflabel="port">
     <term><literal>port</literal></term>
     <listitem>
     <para>
      Numéro de port pour la connexion au serveur ou extension du nom de
      fichier pour des connexions de domaine Unix.<indexterm><primary>port</primary></indexterm>
     </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-connect-dbname" xreflabel="dbname">
     <term><literal>dbname</literal></term>
     <listitem>
     <para>
      Nom de la base de données. Par défaut, la même que le nom utilisateur.
      Dans certains contextes, la valeur est vérifiée pour les formats
      étendues&nbsp;; voir <xref linkend="libpq-connstring"/> pour plus
      d'informations.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-connect-user" xreflabel="user">
     <term><literal>user</literal></term> 
     <listitem>
     <para>
      Nom de l'utilisateur <productname>PostgreSQL</productname> qui se
      connecte.
      Par défaut, il s'agit du nom de l'utilisateur ayant lancé l'application.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-connect-password" xreflabel="password">
     <term><literal>password</literal></term>
     <listitem>
     <para>
      Mot de passe à utiliser si le serveur demande une authentification par
      mot de passe.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-connect-connect-timeout" xreflabel="connect_timeout">
     <term><literal>connect_timeout</literal></term>
     <listitem>
     <para>
      Attente maximum pour une connexion, en secondes (saisie comme une
      chaîne d'entier décimaux). Zéro ou non spécifié signifie une attente
      indéfinie. Utiliser un décompte de moins de deux secondes n'est pas
      recommandé.
     </para>
     </listitem>
    </varlistentry>

        <varlistentry id="libpq-connect-client-encoding" xreflabel="client_encoding">
         <term><literal>client_encoding</literal></term>
         <listitem>
         <para>
          Ceci configure le paramètre <varname>client_encoding</varname>
          pour cette connexion. En plus des valeurs acceptées par
          l'option serveur correspondante, vous pouvez utiliser
          <literal>auto</literal> pour déterminer le bon encodage à
          partir de la locale courante du client (variable
          d'environnement <envar>LC_CTYPE</envar> sur les systèmes Unix).
         </para>
         </listitem>
        </varlistentry>

    <varlistentry id="libpq-connect-options" xreflabel="options">
     <term><literal>options</literal></term>
     <listitem>
      <para>
           Ajout d'options en ligne de commande à envoyer au serveur à
     l'exécution. Par exemple, en le configurant à <literal>-c
     geqo=off</literal>, cela configure la valeur de la session
     pour le paramètre <varname>geqo</varname> à
           <literal>off</literal>. Pour une discussion détaillée des options
           disponibles, voir <xref linkend="runtime-config"/>.
      </para>
     </listitem>
    </varlistentry>

        <varlistentry id="libpq-connect-application-name" xreflabel="application_name">
         <term><literal>application_name</literal></term>
         <listitem>
          <para>
           Précise une valeur pour le paramètre de configuration <xref
           linkend="guc-application-name"/>.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-connect-fallback-application-name" xreflabel="fallback_application_name">
         <term><literal>fallback_application_name</literal></term>
         <listitem>
          <para>
           Indique une valeur de secours pour le paramètre de configuration
           <xref linkend="guc-application-name"/>. Cette valeur sera utilisée
           si aucune valeur n'est donnée à <literal>application_name</literal>
           via un paramètre de connexion ou la variable d'environnement.
           L'indication d'un nom de secours est utile pour les programmes
           outils génériques qui souhaitent configurer un nom d'application
           par défaut mais permettrait sa surcharge par l'utilisateur.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-keepalives" xreflabel="keepalives">
         <term><literal>keepalives</literal></term>
         <listitem>
          <para>
           Contrôle si les paramètres TCP keepalives côté client sont utilisés.
           La valeur par défaut est de 1, signifiant ainsi qu'ils sont
           utilisés. Vous pouvez le configurer à 0, ce qui aura pour effet de
           les désactiver si vous n'en voulez pas. Ce paramètre est ignoré
           pour les connexions réalisées via un socket de domaine Unix.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-keepalives-idle" xreflabel="keepalives_idle">
         <term><literal>keepalives_idle</literal></term>
         <listitem>
          <para>
           Contrôle le nombre de secondes d'inactivité après lequel TCP doit
           envoyer un message keepalive au server. Une valeur de zéro utilise
           la valeur par défaut du système. Ce paramètre est ignoré pour les
           connexions réalisées via un socket de domaine Unix ou si les
           paramètres keepalives sont désactivés. Ce paramètre est uniquement
           supporté sur les systèmes où les options
           <symbol>TCP_KEEPIDLE</symbol> ou <symbol>TCP_KEEPALIVE</symbol>
           sont disponibles et sur Windows&nbsp;; pour les autres systèmes,
           ce paramètre n'a pas d'effet.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-keepalives-interval" xreflabel="keepalives_interval">
         <term><literal>keepalives_interval</literal></term>
         <listitem>
          <para>
           Contrôle le nombre de secondes après lequel un message TCP
           keepalive doit être retransmis si le serveur ne l'a pas acquitté.
           Une valeur de zéro utilise la valeur par défaut du système. Ce
           paramètre est uniquement supporté sur les systèmes où l'option
           <symbol>TCP_KEEPINTVL</symbol> est disponible et sur Windows&nbsp;;
           pour les autres systèmes, ce paramètre n'a pas d'effet.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-keepalives-count" xreflabel="keepalives_count">
         <term><literal>keepalives_count</literal></term>
         <listitem>
          <para>
           Contrôle le nombre de messages TCP keepalives pouvant être perdus
           avant que la connexion du client au serveur ne soit considérée
           comme perdue. Une valeur de zéro utilise la valeur par défaut du
           système. Ce paramètre est uniquement supporté sur les systèmes où
           l'option <symbol>TCP_KEEPCNT</symbol> est disponible et sur
           Windows&nbsp;; pour les autres systèmes, ce paramètre n'a pas
           d'effet.
          </para>
         </listitem>
        </varlistentry>

    <varlistentry id="libpq-connect-tty" xreflabel="tty">
     <term><literal>tty</literal></term>
     <listitem>
     <para>
      Ignoré (auparavant, ceci indiquait où envoyer les traces de débogage du
      serveur).
     </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-connect-sslmode" xreflabel="sslmode">
     <term><literal>sslmode</literal></term>
     <listitem>
      <para>
       Cette option détermine si ou avec quelle priorité une connexion
       TCP/IP <acronym>SSL</acronym> sécurisée sera négociée avec le serveur.
       Il existe six modes&nbsp;:
       <variablelist>
        <varlistentry>
         <term><literal>disable</literal></term>
         <listitem>
          <para>
           essaie seulement une connexion non <acronym>SSL</acronym>
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>allow</literal></term>
         <listitem>
          <para>
           essaie en premier lieu une connexion non
         <acronym>SSL</acronym>&nbsp;; si cette tentative échoue, essaie
               une connexion <acronym>SSL</acronym>
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>prefer</literal> (default)</term>
         <listitem>
          <para>
           essaie en premier lieu une connexion
         <acronym>SSL</acronym>&nbsp;; si cette tentative échoue, essaie
               une connexion non <acronym>SSL</acronym>
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>require</literal></term>
         <listitem>
          <para>
           essaie seulement une connexion <acronym>SSL</acronym>.
           Si un certificat racine d'autorité est présent, vérifie
           le certificat de la même façon que si
           <literal>verify-ca</literal> était spécifié
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>verify-ca</literal></term>
         <listitem>
          <para>
           essaie seulement une connexion <acronym>SSL</acronym> et
         vérifie que le certificat client est créé par une autorité de
           certificats (<acronym>CA</acronym>) de confiance
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>verify-full</literal></term>
         <listitem>
          <para>
           essaie seulement une connexion <acronym>SSL</acronym>,
        vérifie que le certificat client est créé par un
        <acronym>CA</acronym> de confiance et que le nom du serveur
        correspond bien à celui du certificat
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>

          <para>
           Voir <xref linkend="libpq-ssl"/> pour une description détaillée de
     comment ces options fonctionnent.
          </para>

          <para>
           <literal>sslmode</literal> est ignoré pour la communication par
     socket de domaine Unix.
           Si <productname>PostgreSQL</productname> est compilé sans le support
     de SSL, l'utilisation des options <literal>require</literal>,
       <literal>verify-ca</literal> et
           <literal>verify-full</literal> causera
     une erreur alors que les options <literal>allow</literal> et
     <literal>prefer</literal> seront acceptées mais
     <application>libpq</application> ne sera pas capable de négocier une
     connexion <acronym>SSL</acronym>.
     <indexterm>
      <primary>SSL</primary>
      <secondary sortas="libpq">avec libpq</secondary>
     </indexterm>
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-connect-requiressl" xreflabel="requiressl">
     <listitem>
      <para>
       Cette option est obsolète et remplacée par l'option <literal>sslmode</literal>.
      </para>

      <para>
       Si initialisée à 1, une connexion <acronym>SSL</acronym> au serveur est
       requise (ce qui est équivalent à un <literal>sslmode</literal>
       <literal>require</literal>). <application>libpq</application> refusera alors de se
       connecter si le serveur n'accepte pas une connexion
       <acronym>SSL</acronym>. Si initialisée à 0 (la valeur par défaut),
       <application>libpq</application> négociera le type de connexion avec le serveur
       (équivalent à un <literal>sslmode</literal> <literal>prefer</literal>). Cette option
       est seulement disponible si <productname>PostgreSQL</productname> est compilé avec
       le support SSL.
      </para>
     </listitem>
    </varlistentry>

     <varlistentry id="libpq-connect-sslcompression" xreflabel="sslcompression">
      <term><literal>sslcompression</literal></term>
      <listitem>
       <para>
        Si initialisé à 1 (la valeur par défaut), les données envoyées sur une
        connexion SSL seront compressées (ceci nécessite
        <productname>OpenSSL</productname> version 0.9.8 ou ultérieur).
        Si initialisé à 0, la compression sera désactivée (ceci requiert
        <productname>OpenSSL</productname> 1.0.0 ou ultérieur).
        Ce paramètre est ignoré si un connexion est tentée sans SSL ou si
        la version d'<productname>OpenSSL</productname> en vigueur ne le
        supporte pas.
       </para>
       <para>
        La compression utilise du temps processeur mais peut améliorer la
        bande-passante si le réseau est le goulet d'étranglement.
        Désactiver la compression peut améliorer les temps de réponse et
        la bande passante si les performances des processeurs sont le
        facteur limitant.
       </para>
      </listitem>
     </varlistentry>

        <varlistentry id="libpq-connect-sslcert" xreflabel="sslcert">
         <term><literal>sslcert</literal></term>
         <listitem>
          <para>
           Ce paramètre indique le nom du fichier du certificat SSL client,
           remplaçant le fichier par défaut,
           <filename>~/.postgresql/postgresql.crt</filename>. Ce paramètre
           est ignoré si la connexion n'utilise pas SSL.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-connect-sslkey" xreflabel="sslkey">
         <term><literal>sslkey</literal></term>
         <listitem>
          <para>
           Ce paramètre indique l'emplacement de la clé secrète utilisée pour
     le certificat client. Il peut soit indiquer un nom de fichier qui
     sera utilisé à la place du fichier
           <filename>~/.postgresql/postgresql.key</filename> par défaut, soit
     indiquer un clé obtenue par un moteur externe (les moteurs sont des modules chargeables
     d'<productname>OpenSSL</productname>). La spécification d'un moteur
     externe devrait consister en un nom de moteur et un identifiant de
     clé spécifique au moteur, les deux séparés par une virgule. Ce paramètre
           est ignoré si la connexion n'utilise pas SSL.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-connect-sslrootcert" xreflabel="sslrootcert">
         <term><literal>sslrootcert</literal></term>
         <listitem>
          <para>
           Ce paramètre indique le nom d'un fichier contenant le ou les
           certificats de l'autorité de certificats SSL
           (<acronym>CA</acronym>). Si le fichier existe, le certificat du
           serveur sera vérifié. La signature devra appartenir à une de ces
           autorités. La valeur par défaut de ce paramètre est
           <filename>~/.postgresql/root.crt</filename>.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-connect-sslcrl" xreflabel="sslcrl">
         <term><literal>sslcrl</literal></term>
         <listitem>
          <para>
           Ce paramètre indique le nom du fichier de la liste de révocation
           du certificat SSL. Les certificats listés dans ce fichier, s'il
           existe bien, seront rejetés lors d'une tentative d'authentification
           avec le certificat du serveur. La valeur par défaut de ce paramètre
           est <filename>~/.postgresql/root.crl</filename>.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-connect-requirepeer" xreflabel="requirepeer">
         <term><literal>requirepeer</literal></term>
         <listitem>
          <para>
           Ce paramètre indique le nom d'utilisateur du serveur au
           niveau du système d'exploitation, par exemple
           <literal>requirepeer=postgres</literal>. Lors d'une connexion
           par socket de domaine Unix, si ce paramètre est configuré, le
           client vérifie au début de la connexion si le processus
           serveur est exécuté par le nom d'utilisateur indiqué&nbsp;;
           dans le cas contraire, la connexion est annulée avec une
           erreur. Ce paramètre peut être utilisé pour fournir une
           authentification serveur similaire à celle disponible pour les
           certificats SSL avec les connexions TCP/IP. (Notez que, si
           la socket de domaine Unix est dans <filename>/tmp</filename>
           ou tout espace autorisé en écriture pour tout le monde,
           n'importe quel utilisateur peut mettre un serveur en écoute à
           cet emplacement. Utilisez ce paramètre pour vous assurer que
           le serveur est exécuté par un utilisateur de confiance.) Cette
           option est seulement supportée par les plateformes sur
           lesquelles la méthode d'authentification <literal>peer</literal>
           est disponible&nbsp;; voir <xref linkend="auth-peer"/>.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-connect-krbsrvname" xreflabel="krbsrvname">
     <term><literal>krbsrvname</literal></term>
     <listitem>
      <para>
       Nom du service Kerberos à utiliser lors de l'authentification avec
       Kerberos 5 et GSSAPI. Il doit correspondre avec le nom du service spécifié dans
       la configuration du serveur pour que l'authentification Kerberos puisse
       réussir (voir aussi la <xref linkend="kerberos-auth"/> et <xref linkend="gssapi-auth"/>.)
          </para>
         </listitem>
        </varlistentry>

        <varlistentry id="libpq-connect-gsslib" xreflabel="gsslib">
         <term><literal>gsslib</literal></term>
         <listitem>
          <para>
           Bibliothèque GSS à utiliser pour l'authentification GSSAPI. Utilisée
     seulement sur Windows.
           Configurer à <literal>gssapi</literal> pour forcer libpq à utiliser
     la bibliothèque GSSAPI pour l'authentification au lieu de SSPI par
     défaut.
          </para>
         </listitem>
        </varlistentry>

    <varlistentry id="libpq-connect-service" xreflabel="service">
     <term><literal>service</literal></term>
     <listitem>
     <para>
      Nom du service à utiliser pour des paramètres supplémentaires. Il spécifie
      un nom de service dans <filename>pg_service.conf</filename> contenant
      des paramètres de connexion supplémentaires. Ceci permet aux
      applications de spécifier uniquement un nom de service, donc les
      paramètres de connexion peuvent être maintenus de façon centrale. Voir
      <xref linkend="libpq-pgservice"/>.
     </para>
     </listitem>
    </varlistentry>
   </variablelist>

   </para>
  </sect2>

</sect1>

<sect1 id="libpq-status">
<title>Fonctions de statut de connexion</title>

  <para>
   Ces fonctions sont utilisées pour interroger le statut d'un objet de
   connexion existant.
  </para>

<tip>
<para>
<indexterm><primary>libpq-fe.h</primary></indexterm>
<indexterm><primary>libpq-int.h</primary></indexterm>
Les développeurs d'application <application>libpq</application> devraient être
attentif au maintien de leur abstraction <structname>PGconn</structname>.
Utilisez les fonctions d'accès décrites ci-dessous pour obtenir le
contenu de <structname>PGconn</structname>.
Référence les champs internes de <structname>PGconn</structname> en utilisant
<filename>libpq-int.h</filename> n'est pas recommandé parce qu'ils sont sujets
à modification dans le futur.
</para>
</tip>

<para>
Les fonctions suivantes renvoient les valeurs des paramètres utilisés
pour la connexion. Ces valeurs sont fixes pour la durée de vie de l'objet
<structname>PGconn</structname>.

<variablelist>
<varlistentry id="libpq-pqdb">
<term><function>PQdb</function><indexterm><primary>PQdb</primary></indexterm></term>
<listitem>
<para>
         Renvoie le nom de la base de données de la connexion.
<synopsis>char *PQdb(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pquser">
<term><function>PQuser</function><indexterm><primary>PQuser</primary></indexterm></term>
<listitem>
<para>
         Renvoie le nom d'utilisateur utilisé pour la connexion.
<synopsis>char *PQuser(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqpass">
<term><function>PQpass</function><indexterm><primary>PQpass</primary></indexterm></term>
<listitem>
<para>
         Renvoie le mot de passe utilisé pour la connexion.
<synopsis>char *PQpass(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqhost">
<term><function>PQhost</function><indexterm><primary>PQhost</primary></indexterm></term>
<listitem>
<para>
         Renvoie le nom d'hôte du serveur utilisé pour la connexion.
<synopsis>char *PQhost(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqport">
<term><function>PQport</function><indexterm><primary>PQport</primary></indexterm></term>
<listitem>
<para>
         Renvoie le numéro de port utilisé pour la connexion.
<synopsis>char *PQport(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqtty">
<term><function>PQtty</function><indexterm><primary>PQtty</primary></indexterm></term>
<listitem>
<para>
         Renvoie le <acronym>TTY</acronym> de débogage pour la connexion
         (ceci est obsolète car le serveur ne fait plus attention au
         paramétrage du <acronym>TTY</acronym> mais les fonctions restent pour
         des raisons de compatibilité ascendante).
<synopsis>char *PQtty(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqoptions">
<term><function>PQoptions</function><indexterm><primary>PQoptions</primary></indexterm></term>
<listitem>
<para>
       Renvoie les options en ligne de commande passées lors de la demande de
       connexion.
<synopsis>char *PQoptions(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
Les fonctions suivantes renvoient le statut car il peut changer suite à
 l'exécution d'opérations sur l'objet <structname>PGconn</structname>.

<variablelist>
<varlistentry id="libpq-pqstatus">
<term><function>PQstatus</function><indexterm><primary>PQstatus</primary></indexterm></term>
<listitem>
<para>
         Renvoie l'état de la connexion. 
<synopsis>ConnStatusType PQstatus(const PGconn *conn);
</synopsis>
</para>

      <para>
       Le statut peut faire partie d'un certain nombre de valeurs. Néanmoins,
       seules deux ne concernent pas les procédures de connexion
       asynchrone&nbsp;: <literal>CONNECTION_OK</literal> et
       <literal>CONNECTION_BAD</literal>. Une bonne connexion de la base de
       données a l'état <literal>CONNECTION_OK</literal>. Une tentative échouée
       de connexion est signalée par le statut
       <literal>CONNECTION_BAD</literal>. D'habitude, un état OK restera ainsi
       jusqu'à <function>PQfinish</function> mais un échec de communications
       pourrait résulter en un statut changeant prématurément
       <literal>CONNECTION_BAD</literal>. Dans ce cas, l'application pourrait
       essayer de récupérer en appelant <function>PQreset</function>.
      </para>

      <para>
       Voir l'entrée de <function>PQconnectStartParams</function>, <function>PQconnectStart</function> et de
       <function>PQconnectPoll</function> en regard aux autres codes de statut, qui
       pourraient être renvoyés.
      </para>
     </listitem>
    </varlistentry>

<varlistentry id="libpq-pqtransactionstatus">
<term><function>PQtransactionStatus</function><indexterm><primary>PQtransactionStatus</primary></indexterm></term>
<listitem>
<para>
         Renvoie l'état actuel de la transaction du serveur.
<synopsis>PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
</synopsis>

Le statut peut être <literal>PQTRANS_IDLE</literal> (actuellement inactif),
<literal>PQTRANS_ACTIVE</literal> (une commande est en cours),
<literal>PQTRANS_INTRANS</literal> (inactif, dans un bloc valide de
transaction) ou <literal>PQTRANS_INERROR</literal> (inactif, dans un bloc de
transaction échoué). <literal>PQTRANS_UNKNOWN</literal> est reporté si la
connexion est mauvaise. <literal>PQTRANS_ACTIVE</literal> est reporté seulement
quand une requête a été envoyée au serveur mais qu'elle n'est pas terminée.
</para>
<caution>
<para>
<function>PQtransactionStatus</function> donnera des résultats incorrects lors de
l'utilisation d'un serveur <productname>PostgreSQL</productname> 7.3 qui a désactivé le
paramètre <literal>autocommit</literal>. La fonctionnalité autocommit, côté serveur,
est obsolète et n'existe pas dans les versions serveur ultérieures.
</para>
</caution>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqparameterstatus">
<term><function>PQparameterStatus</function><indexterm><primary>PQparameterStatus</primary></indexterm></term>
<listitem>
<para>
         Recherche un paramétrage actuel du serveur.
<synopsis>const char *PQparameterStatus(const PGconn *conn, const char *paramName);
</synopsis>

Certaines valeurs de paramètres sont reportées par le serveur automatiquement ou
lorsque leur valeurs changent. <function>PQparameterStatus</function> peut être utilisé
pour interroger ces paramétrages. Il renvoie la valeur actuelle d'un
paramètre s'il est connu et <symbol>NULL</symbol> si le paramètre est inconnu.
</para>

<para>
Les paramètres reportés pour la version actuelle incluent
<varname>server_version</varname>,
<varname>server_encoding</varname>,
<varname>client_encoding</varname>,
<varname>application_name</varname>,
<varname>is_superuser</varname>,
<varname>session_authorization</varname>,
<varname>datestyle</varname>,
       <varname>IntervalStyle</varname>,
<varname>TimeZone</varname>,
<varname>integer_datetimes</varname> et
<varname>standard_conforming_strings</varname>.
(<varname>server_encoding</varname>, <varname>TimeZone</varname> et
<varname>integer_datetimes</varname> n'étaient pas rapportés dans les versions
antérieures à la 8.0&nbsp;;
<varname>standard_conforming_strings</varname> n'était pas rapporté dans les versions
antérieures à la 8.1; <varname>IntervalStyle</varname> n'était pas rapporté dans les versions
antérieures à la 8.4;
       <varname>application_name</varname>  n'était pas rapporté dans les versions
antérieures à la 9.0).
Notez que
<varname>server_version</varname>,
<varname>server_encoding</varname> et
<varname>integer_datetimes</varname>
ne peuvent pas changer après le lancement du
serveur.
</para>

<para>
Les serveurs utilisant un protocole antérieur à la 3.0 ne reportent pas la
configuration des paramètres mais <application>libpq</application> inclut la logique pour
obtenir des valeurs pour <varname>server_version</varname> et
<varname>client_encoding</varname>. Les applications sont encouragées à utiliser
<function>PQparameterStatus</function> plutôt qu'un code
<foreignphrase>ad-hoc</foreignphrase> modifiant ces valeurs
(néanmoins, attention, les connexions pré-3.0, changeant
<varname>client_encoding</varname> via <command>SET</command> après le lancement de la
connexion, ne seront pas reflétées par <function>PQparameterStatus</function>). Pour
<varname>server_version</varname>, voir aussi <function>PQserverVersion</function>, qui renvoie
l'information dans un format numérique qui est plus facile à comparer.
</para>

<para>
Si aucune valeur n'est indiquée pour <varname>standard_conforming_strings</varname>,
les applications pourraient supposer qu'elle vaut <literal>off</literal>,
c'est-à-dire que les antislashs sont traités comme des échappements dans les
chaînes littérales. De plus, la présence de ce paramètre pourrait être pris
comme une indication que la syntaxe d'échappement d'une chaîne
(<literal>E'...'</literal>) est acceptée.
</para>

<para>
Bien que le pointeur renvoyé est déclaré <literal>const</literal>, il pointe en fait
vers un stockage mutable associé avec la structure <literal>PGconn</literal>. Il est
déconseillé de supposer que le pointeur restera valide pour toutes les
requêtes.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqprotocolversion">
<term><function>PQprotocolVersion</function><indexterm><primary>PQprotocolVersion</primary></indexterm></term>
<listitem>
<para>
         Interroge le protocole interface/moteur lors de son utilisation.
<synopsis>int PQprotocolVersion(const PGconn *conn);
</synopsis>
Les applications souhaitent utiliser ceci pour déterminer si certaines
fonctionnalités sont supportées. Actuellement, les seules valeurs possible sont
2 (protocole 2.0), 3 (protocole 3.0) ou zéro (mauvaise connexion). La version du
protocole ne
changera pas après la fin du lancement de la connexion mais cela pourrait être
changé théoriquement avec une réinitialisation de la connexion. Le protocole
3.0 sera normalement utilisé lors de la communication avec les serveurs
<productname>PostgreSQL</productname> 7.4 ou ultérieures&nbsp;; les serveurs
antérieurs à la 7.4 supportent uniquement le protocole 2.0 (le protocole 1.0
est obsolète et non supporté par <application>libpq</application>).
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqserverversion">
  <term><function>PQserverVersion</function><indexterm><primary>PQserverVersion</primary></indexterm></term>
<listitem>
  <para>
    Renvoie un entier représentant la version du moteur.
    <synopsis>int PQserverVersion(const PGconn *conn);</synopsis>
    Les applications pourraient utiliser ceci pour déterminer la version du
    serveur de la base de données auquel ils sont connectés. Le numéro est formé
    en convertissant les nombres majeur, mineur et de révision en un nombre à
    deux chiffres décimaux et en leur assemblant. Par exemple, la version 8.1.5
    sera renvoyée en tant que 80105 et la version 8.2 sera renvoyée en tant que
    80200 (les zéros au début ne sont pas affichés). Zéro est renvoyée si la
    connexion est mauvaise.
  </para>
</listitem>
</varlistentry>

    <varlistentry id="libpq-pqerrormessage">
     <term><function>PQerrorMessage</function><indexterm><primary>PQerrorMessage</primary></indexterm></term>
     <listitem>
      <para>
       <indexterm><primary>error message</primary></indexterm>
       Renvoie le dernier message d'erreur généré par une opération sur la
       connexion.
<synopsis>char *PQerrorMessage(const PGconn* conn);
</synopsis>
      </para>

      <para>
       Pratiquement toutes les fonctions <application>libpq</application> initialiseront
       un message pour <function>PQerrorMessage</function> en cas d'échec.
       Notez que, par la convention <application>libpq</application>, un résultat
       non vide de <function>PQerrorMessage</function> peut être sur plusieurs lignes
       et contiendra un retour
       chariot à la fin. L'appelant ne devrait pas libérer directement le
       résultat. Il sera libéré quand la poignée <structname>PGconn</structname> associée
       est passée à <function>PQfinish</function>. Vous ne devriez pas supposer
       que la chaîne résultante reste identique suite à toutes les opérations
       sur la structure <literal>PGconn</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqsocket">
     <term><function>PQsocket</function><indexterm><primary>PQsocket</primary></indexterm></term>
     <listitem>
      <para>
       Obtient le descripteur de fichier du socket de la connexion au serveur.
       Un descripteur valide sera plus grand ou égal à 0&nbsp;; un résultat de
       -1 indique qu'aucune connexion au serveur n'est actuellement ouverte
       (ceci ne changera pas lors de l'opération normale mais pourra changer
       lors d'une configuration de l'initialisation ou lors d'une
       réinitialisation).
<synopsis>int PQsocket(const PGconn *conn);
</synopsis>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqbackendpid">
     <term><function>PQbackendPID</function><indexterm><primary>PQbackendPID</primary></indexterm></term>
     <listitem>
      <para>
       Renvoie l'identifiant du processus
       (<acronym>PID</acronym>)<indexterm><primary>PID</primary><secondary>déterminer
       le PID du processus du serveur</secondary><tertiary>dans libpq</tertiary></indexterm> du serveur
       gérant cette connexion.
<synopsis>int PQbackendPID(const PGconn *conn);
</synopsis>
</para>

<para>
       Le <acronym>PID</acronym> du moteur est utile pour des raisons de
       débogage et pour la comparaison avec les messages
       <command>NOTIFY</command> (qui incluent le <acronym>PID</acronym> du
       processus serveur lançant la notification). Notez que le
       <acronym>PID</acronym> appartient à un processus exécuté sur l'hôte du
       serveur de bases de données et non pas sur l'hôte local&nbsp;!
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqconnectionneedspassword">
     <term><function>PQconnectionNeedsPassword</function><indexterm><primary>PQconnectionNeedsPassword</primary></indexterm></term>
     <listitem>
      <para>
       Renvoie true (1) si la méthode d'authentification de la connexion
       nécessite un mot de passe, mais qu'aucun n'est disponible.
       Renvoie false (0) sinon.

       <synopsis>
        int PQconnectionNeedsPassword(const PGconn *conn);
       </synopsis>

      </para>

      <para>
       Cette fonction peut être utilisée après une tentative échouée de
       connexion pour décider de la demande d'un utilisateur pour un mot de
       passe.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqconnectionusedpassword">
     <term><function>PQconnectionUsedPassword</function><indexterm><primary>PQconnectionUsedPassword</primary></indexterm></term>
     <listitem>
      <para>
       Renvoie true (1) si la méthode d'authentification de la connexion a
       utilisé un mot de passe. Renvoie false (0) sinon.

       <synopsis>
        int PQconnectionUsedPassword(const PGconn *conn);
       </synopsis>

      </para>

      <para>
       Cette fonction peut être utilisée après une connexion, réussie ou en
       échec, pour détecter si le serveur demande un mot de passe.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqgetssl">
     <term><function>PQgetssl</function><indexterm><primary>PQgetssl</primary></indexterm></term>
     <listitem>
      <para>
       <indexterm><primary>SSL</primary><secondary sortas="libpq">dans
       libpq</secondary></indexterm>
       Retourne la structure SSL utilisée dans la connexion ou NULL si SSL
       n'est pas utilisé.
<synopsis>void *PQgetssl(const PGconn *conn);
</synopsis>
</para>

<para>
       Cette structure peut être utilisée pour vérifier les niveaux de cryptage,
       pour vérifier les certificats du serveur, et plus. Référez-vous à la
       documentation d'<productname>OpenSSL</productname> pour plus d'informations sur
       cette structure.
      </para>
      <para>
       The actual return value is of type <type>SSL *</type>,
       where <type>SSL</type> is a type defined by
       the <productname>OpenSSL</productname> library, but it is not declared
       this way to avoid requiring the <productname>OpenSSL</productname>
       header files.  To use this function, code along the following lines
       could be used:
<programlisting><![CDATA[
#include <libpq-fe.h>
#include <openssl/ssl.h>

...

    SSL *ssl;

    dbconn = PQconnectdb(...);
    ...

    ssl = PQgetssl(dbconn);
    if (ssl)
    {
        /* use OpenSSL functions to access ssl */
    }
]]></programlisting>
      </para>
     </listitem>
    </varlistentry>

</variablelist>
</para>

</sect1>

<sect1 id="libpq-exec">
<title>Fonctions de commandes d'exécution</title>

<para>
Une fois la connexion au serveur de la base de données établie avec
succès, les fonctions décrites ici sont utilisées pour exécuter les requêtes
SQL et les commandes.
</para>

<sect2 id="libpq-exec-main">
  <title>Fonctions principales</title>

<para>
<variablelist>
<varlistentry id="libpq-pqexec">
<term><function>PQexec</function><indexterm><primary>PQexec</primary></indexterm></term>
<listitem>
<para>
          Soumet une commande au serveur et attend le résultat.
<synopsis>PGresult *PQexec(PGconn *conn, const char *command);
</synopsis>
</para>

<para>
  Renvoie un pointeur <structname>PGresult</structname> 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 <function>PQresultStatus</function> devrait être appelée pour
  vérifier le code retour  pour toute erreur (incluant la valeur d'un
  pointeur nul, auquel cas il renverra <symbol>PGRES_FATAL_ERROR</symbol>).
  Utilisez <function>PQerrorMessage</function> pour obtenir plus
  d'informations sur l'erreur.
</para>
</listitem>
</varlistentry>
</variablelist>

La chaîne de la commande peut inclure plusieurs commandes SQL (séparées par des points
virgules). Les requêtes multiples envoyées
dans un simple appel à <function>PQexec</function> sont exécutées dans une seule
transaction sauf si des commandes explicites
<command>BEGIN</command>/<command>COMMIT</command> sont incluses dans la chaîne
de requête pour la diviser dans de nombreuses transactions. Néanmoins, notez
que la structure <structname>PGresult</structname> renvoyée décrit seulement
le résultat de la dernière commande exécutée à partir de la chaîne. Si une des
commandes doit échouer, l'exécution de la chaîne s'arrête et le
<structname>PGresult</structname> renvoyé décrit la condition d'erreur.
</para>

<para>
<variablelist>
<varlistentry id="libpq-pqexecparams">
<term><function>PQexecParams</function><indexterm><primary>PQexecParams</primary></indexterm></term>
<listitem>
<para>
          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.
<synopsis>PGresult *PQexecParams(PGconn *conn,
                       const char *command,
                       int nParams,
                       const Oid *paramTypes,
                       const char * const *paramValues,
                       const int *paramLengths,
                       const int *paramFormats,
                       int resultFormat);
</synopsis>
</para>

<para>
<function>PQexecParams</function> est identique à <function>PQexec</function> mais offre des
fonctionnalités supplémentaires&nbsp;: 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.
<function>PQexecParams</function> est supporté seulement dans les connexions avec le
protocole 3.0 et ses versions ultérieures&nbsp;; elle échouera lors de
l'utilisation du protocole 2.0.
</para>

<para>
Voici les arguments de la fonction&nbsp;:

<variablelist>
  <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
      <para>
       L'objet connexion où envoyer la commande.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><parameter>command</parameter></term>
    <listitem>
      <para>
       La chaîne SQL à exécuter. Si les paramètres sont utilisés, ils sont
       référencés dans la chaîne avec <literal>$1</literal>,
       <literal>$2</literal>, etc.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><parameter>nParams</parameter></term>
    <listitem>
      <para>
       Le nombre de paramètres fournis&nbsp;; il s'agit de la longueur des
       tableaux <parameter>paramTypes[]</parameter>,
       <parameter>paramValues[]</parameter>,
       <parameter>paramLengths[]</parameter> et
       <parameter>paramFormats[]</parameter>. (Les pointeurs de tableau peuvent
       être <symbol>NULL</symbol> quand <parameter>nParams</parameter> vaut
       zéro.)
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><parameter>paramTypes[]</parameter></term>
    <listitem>
      <para>
       Spécifie, par OID, les types de données à affecter aux symboles de
       paramètres. Si <parameter>paramTypes</parameter> est <symbol>NULL</symbol>
       ou si tout élément spécifique du tableau est zéro, le serveur infère un
       type de donnée pour le symbole de paramètre de la même façon qu'il le
       ferait pour une chaîne litérale sans type.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><parameter>paramValues[]</parameter></term>
    <listitem>
      <para>
       Spécifie les vraies valeurs des paramètres. Un pointeur nul dans ce
       tableau signifie que le paramètre correspondant est NULL&nbsp;; sinon,
       le pointeur pointe vers une chaîne texte terminée par un octet nul
       (pour le format texte) ou vers des données binaires dans le format
       attendu par le serveur (pour le format binaire).
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><parameter>paramLengths[]</parameter></term>
    <listitem>
      <para>
       Spécifie les longueurs des données réelles des paramètres du format
       binaire. Il est ignoré pour les paramètres NULL et les paramètres de
       format texte. Le pointeur du tableau peut être NULL quand il n'y a pas
       de paramètres binaires.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><parameter>paramFormats[]</parameter></term>
    <listitem>
      <para>
       Spécifie si les paramètres sont du texte (placez un zéro dans la ligne du
       tableau pour le paramètre correspondant) ou binaire (placez un un dans la
       ligne du tableau pour le paramètre correspondant). Si le pointeur du
       tableau est nul, alors tous les paramètres sont présumés être des chaînes
       de texte.
      </para>
      <para>
       Les valeurs passées dans le format binaire nécessitent de connaître la
       représentation interne attendue par le moteur. Par exemple, les entiers
       doivent être passés dans l'ordre réseau pour les octets. Passer des
       valeurs <type>numeric</type> requiert de connaître le format de stockage
       du serveur, comme implémenté dans
       <filename>src/backend/utils/adt/numeric.c::numeric_send()</filename> et
       <filename>src/backend/utils/adt/numeric.c::numeric_recv()</filename>.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><parameter>resultFormat</parameter></term>
    <listitem>
      <para>
       Indiquez zéro pour obtenir les résultats dans un format texte et un pour
       les obtenir dans un format binaire. (Il n'est actuellement pas possible
       d'obtenir des formats différents pour des colonnes de résultats
       différentes bien que le protocole le permette.)
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
Le principal avantage de <function>PQexecParams</function> sur <function>PQexec</function> est
que les valeurs de paramètres pourraient être séparés à partir de la chaîne de
commande, évitant ainsi le besoin de guillemets et d'échappements.
</para>

<para>
Contrairement à <function>PQexec</function>, <function>PQexecParams</function> autorise au plus
une commande SQL dans une chaîne donnée (il peut y avoir des points-virgules
mais pas plus d'une commande non vide). C'est une limitation du protocole
sous-jacent mais cela a quelque utilité comme défense supplémentaire contre les
attaques par injection de SQL.
</para>

<tip>
<para>
Spécifier les types de paramètres via des OID est difficile, tout
particulièrement si vous préférez ne pas coder en dur les valeurs OID
particulières dans vos programmes. Néanmoins, vous pouvez éviter de le faire
même dans des cas où le serveur lui-même ne peut pas déterminer le type du
paramètre ou choisit un type différent de celui que vous voulez. Dans le texte
de commande SQL, attachez une conversion explicite au symbole de paramètre pour
montrer le type de données que vous enverrez. Par exemple&nbsp;:
<programlisting>SELECT * FROM ma_table WHERE x = $1::bigint;
</programlisting>
Ceci impose le traitement du paramètre <literal>$1</literal> en tant que <type>bigint</type>
alors que, par défaut, il se serait vu affecté le même type que <literal>x</literal>.
Forcer la décision du type de paramètre, soit de cette façon soit en spécifiant
l'OID du type numérique, est fortement recommandé lors de l'envoi des valeurs
des paramètres au format binaire car le format binaire a moins de redondance que
le format texte et, du coup, il y a moins de chance que le serveur détecte une
erreur de correspondance de type pour vous.
</para>
</tip>

<para>
  <variablelist>
    <varlistentry id="libpq-pqprepare">
      <term><function>PQprepare</function>
      <indexterm><primary>PQprepare</primary></indexterm></term>
  <listitem>
    <para>
      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.
      <synopsis>PGresult *PQprepare(PGconn *conn,
        const char *stmtName,
        const char *query,
        int nParams,
        const Oid *paramTypes);</synopsis>
    </para>

    <para>
      <function>PQprepare</function> crée une instruction préparée pour une exécution
      ultérieure avec <function>PQexecPrepared</function>. Cette fonction autorise les
      commandes utilisées de façon répété à être analysées et
      planifiées qu'une seule fois, plutôt qu'à chaque exécution.
      <function>PQprepare</function> est uniquement supporté par les connexions
      utilisant le protocole 3.0 et ses versions ultérieures&nbsp;; elle
      échouera avec le protocole 2.0.
    </para>

    <para>
      La fonction crée une instruction préparée nommée <parameter>stmtName</parameter>
      à partir de la chaîne <parameter>query</parameter>, devant contenir une seule
      commande SQL. <parameter>stmtName</parameter> pourrait être une chaîne vide 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.
      Une erreur sera rapporté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 <literal>$1</literal>, <literal>$2</literal>, etc.
      <parameter>nParams</parameter> est le nombre de paramètres pour lesquels des types
      sont prédéfinis dans le tableau <parameter>paramTypes[]</parameter> (le pointeur
      du tableau pourrait être <symbol>NULL</symbol> quand
      <parameter>nParams</parameter> vaut zéro). <parameter>paramTypes[]</parameter> spécifie
      les types de données à affecter aux symboles de paramètres par leur OID.
      Si <parameter>paramTypes</parameter> est <symbol>NULL</symbol> 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 pourrait utiliser des symboles
      de paramètre avec des nombres plus importants que 
      <parameter>nParams</parameter>&nbsp;; les types de données seront aussi inférés
      pour ces symboles. (Voir <function>PQdescribePrepared</function> comme un
      moyen de trouver les types de données inférés.)
    </para>

    <para>
      Comme avec <function>PQexec</function>, le résultat est normalement un objet
      <structname>PGresult</structname> 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 
      <function>PQerrorMessage</function> pour obtenir plus d'informations sur
      de telles erreurs.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

Les instructions préparées avec <function>PQexecPrepared</function> peuvent aussi être
créées en exécutant les instructions SQL <xref linkend="sql-prepare"/>. De plus,
bien qu'il n'y ait aucune fonction <application>libpq</application> pour supprimer une
instruction préparée, l'instruction SQL <xref linkend="sql-deallocate"/> peut
être utilisée dans ce but.
</para>

<para>
<variablelist>
<varlistentry id="libpq-pqexecprepared">
<term><function>PQexecPrepared</function><indexterm><primary>PQexecPrepared</primary></indexterm></term>
<listitem>
<para>
          Envoie une requête pour exécuter une instruction séparée avec les
          paramètres donnés, et attend le résultat.
<synopsis>PGresult *PQexecPrepared(PGconn *conn,
                         const char *stmtName,
                         int nParams,
                         const char * const *paramValues,
                         const int *paramLengths,
                         const int *paramFormats,
                         int resultFormat);
</synopsis>
</para>

<para>
<function>PQexecPrepared</function> est identique à <function>PQexecParams</function> 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.
<function>PQexecPrepared</function> est supporté seulement dans les connexions 
du protocole 3.0 et ses versions ultérieures&nbsp;; il échouera lors de
l'utilisation du protocole 2.0.
</para>

<para>
Les paramètres sont identiques à <function>PQexecParams</function>, sauf que le nom
d'une instruction préparée est donné au lieu d'une chaîne de requête et le
paramètre <parameter>paramTypes[]</parameter> n'est pas présente (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).
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqdescribeprepared">
<term><function>PQdescribePrepared</function><indexterm><primary>PQdescribePrepared</primary></indexterm></term>
<listitem>
<para>
          Soumet une requête pour obtenir des informations sur l'instruction
          préparée indiquée et attend le retour de la requête.
<synopsis>
PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
</synopsis>
</para>

<para>
<function>PQdescribePrepared</function> permet à une application d'obtenir des
informations si une instruction préparée précédemment.
<function>PQdescribePrepared</function> est seulement supporté avec des
connexions utilisant le protocole 3.0 et ultérieures&nbsp;; il échouera lors
de l'utilisation du protocole 2.0.
</para>

<para>
<parameter>stmtName</parameter> peut être <literal>""</literal> ou  <symbol>NULL</symbol> 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 <structname>PGresult</structname> est
renvoyé avec le code retour <literal>PGRES_COMMAND_OK</literal>. Les fonctions
<function>PQnparams</function> et <function>PQparamtype</function> peuvent
utiliser ce <structname>PGresult</structname> pour obtenir des
informations sur les paramètres d'une instruction préparée, et les fonctions
<function>PQnfields</function>, <function>PQfname</function>,
<function>PQftype</function>, etc fournissent des informations sur les colonnes
résultantes (au cas où) de l'instruction.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqdescribeportal">
<term><function>PQdescribePortal</function><indexterm><primary>PQdescribePortal</primary></indexterm></term>
<listitem>
<para>
          Soumet une requête pour obtenir des informations sur le portail
          indiqué et attend le retour de la requête.
<synopsis>
PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
</synopsis>
</para>

<para>
<function>PQdescribePortal</function> permet à une application d'obtenir des
informations sur un portail précédemment créé. (<application>libpq</application>
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 <command>DECLARE CURSOR</command>.)
<function>PQdescribePortal</function> est seulement supporté dans les connexions
via le protocole 3.0 et ultérieurs&nbsp;; il échouera lors de l'utilisation du
protocole 2.0.
</para>

<para>
<parameter>portalName</parameter> peut être <literal>""</literal> ou <symbol>NULL</symbol> pour
référencer un portail sans nom. Sinon, il doit correspondre au nom d'un portail
existant. En cas de succès, un <structname>PGresult</structname> est renvoyé
avec le code de retour <literal>PGRES_COMMAND_OK</literal>. Les fonctions
<function>PQnfields</function>, <function>PQfname</function>,
<function>PQftype</function>, etc peuvent utiliser ce
<structname>PGresult</structname> pour obtenir des informations sur les colonnes
résultats (au cas où) du portail.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
La structure
<structname>PGresult</structname><indexterm><primary>PGresult</primary></indexterm>
encapsule le résultat renvoyé par le serveur. Les développeurs d'applications
<application>libpq</application> devraient faire attention au maintien de
l'abstraction de <structname>PGresult</structname>. Utilisez les fonctions
d'accès ci-dessous pour obtenir le contenu de <structname>PGresult</structname>.
Évitez la référence aux champs de la structure <structname>PGresult</structname>
car ils sont sujets à des changements dans le futur.

<variablelist>
<varlistentry id="libpq-pqresultstatus">
<term><function>PQresultStatus</function><indexterm><primary>PQresultStatus</primary></indexterm></term>
<listitem>
<para>
          Renvoie l'état du résultat d'une commande.
<synopsis>ExecStatusType PQresultStatus(const PGresult *res);
</synopsis>
</para>

<para>
<function>PQresultStatus</function> peut renvoyer une des valeurs
suivantes&nbsp;:

<variablelist>
 <varlistentry id="libpq-pgres-empty-query">
  <term><literal>PGRES_EMPTY_QUERY</literal></term>
  <listitem>
   <para>La chaîne envoyée au serveur était vide.</para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pgres-command-ok">
  <term><literal>PGRES_COMMAND_OK</literal></term>
  <listitem>
   <para>Fin avec succès d'une commande ne renvoyant aucune donnée.</para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pgres-tuples-ok">
  <term><literal>PGRES_TUPLES_OK</literal></term>
  <listitem>
   <para>Fin avec succès d'une commande renvoyant des données (telle que
   <command>SELECT</command> ou <command>SHOW</command>).</para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pgres-copy-out">
  <term><literal>PGRES_COPY_OUT</literal></term>
  <listitem>
   <para>Début de l'envoi (à partir du serveur) d'un flux de données.</para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pgres-copy-in">
  <term><literal>PGRES_COPY_IN</literal></term>
  <listitem>
   <para>Début de la réception (sur le serveur) d'un flux de
    données.</para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pgres-bad-response">
  <term><literal>PGRES_BAD_RESPONSE</literal></term>
  <listitem>
   <para>La réponse du serveur n'a pas été comprise.</para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pgres-nonfatal-error">
  <term><literal>PGRES_NONFATAL_ERROR</literal></term>
  <listitem>
   <para>Une erreur non fatale (une note ou un avertissement) est
    survenue.</para>
  </listitem>
 </varlistentry>

 <varlistentry id="libpq-pgres-fatal-error">
  <term><literal>PGRES_FATAL_ERROR</literal></term>
  <listitem>
   <para>Une erreur fatale est survenue.</para>
  </listitem>
 </varlistentry>

         <varlistentry id="libpq-pgres-copy-both">
          <term><literal>PGRES_COPY_BOTH</literal></term>
          <listitem>
           <para>
            Lancement du transfert de données Copy In/Out (vers et à
            partir du serveur). Cette fonctionnalité est seulement
            utilisée par la réplication en flux,
            so this status should not occur in ordinary applications.
           </para>
          </listitem>
         </varlistentry>

         <varlistentry id="libpq-pgres-single-tuple">
          <term><literal>PGRES_SINGLE_TUPLE</literal></term>
          <listitem>
           <para>
            La structure <structname>PGresult</structname> contient une seule
            ligne de résultat provenant de la commande courante. Ce statut
            n'intervient que lorsque le mode simple ligne a été sélectionné
            pour cette requête (voir <xref linkend="libpq-single-row-mode"/>).
           </para>
          </listitem>
         </varlistentry>
</variablelist>

Si le statut du résultat est <literal>PGRES_TUPLES_OK</literal> ou <literal>PGRES_SINGLE_TUPLE</literal>, 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 <command>SELECT</command> qui
arrive à récupérer aucune ligne affichera toujours
<literal>PGRES_TUPLES_OK</literal>. <literal>PGRES_COMMAND_OK</literal> est
pour les commandes qui ne peuvent jamais renvoyer de lignes
(<command>INSERT</command> ou <command>UPDATE</command> without a <literal>RETURNING</literal> clause, etc.). Une réponse
<literal>PGRES_EMPTY_QUERY</literal> pourrait indiquer un bogue dans le
logiciel client.
</para>

<para>
Un résultat de statut <symbol>PGRES_NONFATAL_ERROR</symbol> ne sera jamais
renvoyé directement par <function>PQexec</function> ou d'autres fonctions
d'exécution de requêtes&nbsp;; les résultats de ce type sont passés à
l'exécuteur de notifications (voir la <xref linkend="libpq-notice-processing"/>).
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqresstatus">
<term><function>PQresStatus</function><indexterm><primary>PQresStatus</primary></indexterm></term>
<listitem>
<para>
        Convertit le type énuméré renvoyé par <function>PQresultStatus</function> en
        une constante de type chaîne décrivant le code d'état. L'appelant ne
	devrait pas libérer le résultat.
<synopsis>char *PQresStatus(ExecStatusType status);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqresulterrormessage">
<term><function>PQresultErrorMessage</function><indexterm><primary>PQresultErrorMessage</primary></indexterm></term>
<listitem>
<para>
Renvoie le message d'erreur associé avec la commande ou une chaîne vide s'il
n'y a pas eu d'erreurs.
<synopsis>char *PQresultErrorMessage(const PGresult *res);
</synopsis>
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
la poignée <structname>PGresult</structname> associée est passée à
<function>PQclear</function>.
</para>

<para>
Suivant immédiatement un appel à <function>PQexec</function> ou
<function>PQgetResult</function>, <function>PQerrorMessage</function> (sur la
connexion) renverra la même chaîne que <function>PQresultErrorMessage</function>
(sur le résultat). Néanmoins, un <structname>PGresult</structname> conservera
son message d'erreur jusqu'à destruction alors que le message d'erreur de la 
connexion changera lorsque des opérations suivantes seront réalisées. Utiliser
<function>PQresultErrorMessage</function> quand vous voulez connaître le statut
associé avec un <structname>PGresult</structname> particulier&nbsp;; utilisez
<function>PQerrorMessage</function> lorsque vous souhaitez connaître le statut
à partir de la dernière opération sur la connexion.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqresulterrorfield">
<term><function>PQresultErrorField</function><indexterm><primary>PQresultErrorField</primary></indexterm></term>
<listitem>
<para>
Renvoie un champ individuel d'un rapport d'erreur.
<synopsis>char *PQresultErrorField(const PGresult *res, int fieldcode);
</synopsis>
<parameter>fieldcode</parameter> est un identifiant de champ d'erreur&nbsp;; voir les
symboles listés ci-dessous. <symbol>NULL</symbol> est renvoyé si
<structname>PGresult</structname> 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 la poignée
<structname>PGresult</structname> associée est passée à
<function>PQclear</function>.
</para>

<para>
Les codes de champs suivants sont disponibles&nbsp;:
<variablelist>

<varlistentry id="libpq-pg-diag-severity">
<term><symbol>PG_DIAG_SEVERITY</symbol></term>
<listitem>
<para>
La sévérité&nbsp;; le contenu du champ peut être <literal>ERROR</literal>,
<literal>FATAL</literal> ou <literal>PANIC</literal> dans un message d'erreur, ou
<literal>WARNING</literal>, <literal>NOTICE</literal>, <literal>DEBUG</literal>,
<literal>INFO</literal> ou <literal>LOG</literal> dans un message de notification, ou une
traduction localisée de ceux-ci. Toujours présent.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-sqlstate">
<term><symbol>PG_DIAG_SQLSTATE</symbol>
</term>
<listitem>
<indexterm>
<primary>error codes</primary>
<secondary>libpq</secondary>
</indexterm>
<para>
Le code SQLSTATE de l'erreur. Ce code identifie le type d'erreur qui est
survenu&nbsp;; il peut être utilisé par des interfaces qui réalisent les
opérations spécifiques (telles que la gestion des erreurs) en réponse à une
erreur particulière de la base de données. Pour une liste des codes SQLSTATE
possibles, voir l'<xref linkend="errcodes-appendix"/>. Ce champ n'est pas
localisable et est toujours présent.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-message-primary">
<term><symbol>PG_DIAG_MESSAGE_PRIMARY</symbol></term>
<listitem>
<para>
Le principal message d'erreur, compréhensible par un humain (typiquement sur
une ligne). Toujours présent.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-message-detail">
<term><symbol>PG_DIAG_MESSAGE_DETAIL</symbol></term>
<listitem>
<para>
Détail&nbsp;: un message d'erreur secondaire et optionnel proposant plus
d'informations sur le problème. Pourrait être composé de plusieurs lignes.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-message-hint">
<term><symbol>PG_DIAG_MESSAGE_HINT</symbol></term>
<listitem>
<para>
Astuce&nbsp;: une suggestion supplémentaire sur ce qu'il faut faire suite à
ce problème. Elle a pour but de différer du détail car elle
offre un conseil (potentiellement inapproprié) plutôt que des faits établis.
Pourrait être composé de plusieurs lignes.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-statement-position">
<term><symbol>PG_DIAG_STATEMENT_POSITION</symbol></term>
<listitem>
<para>
Une chaîne contenant un entier décimal indiquant le position du curseur d'erreur
comme index dans la chaîne d'instruction originale. Le premier caractère se
trouve à l'index 1 et les positions sont mesurées en caractères, et non pas en
octets.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-internal-position">
<term><symbol>PG_DIAG_INTERNAL_POSITION</symbol></term>
<listitem>
<para>
Ceci est défini de la même façon que le champ <symbol>PG_DIAG_STATEMENT_POSITION</symbol>
mais c'est utilisé quand la position du curseur fait référence à une commande
générée en interne plutôt qu'une soumise par le client. Le champ
<symbol>PG_DIAG_INTERNAL_QUERY</symbol> apparaîtra toujours quand ce champ apparaît.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-internal-query">
<term><symbol>PG_DIAG_INTERNAL_QUERY</symbol></term>
<listitem>
<para>
Le texte d'une commande échouée, générée en interne. Ceci pourrait être, par
exemple, une requête SQL lancée par une fonction PL/pgSQL.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-context">
<term><symbol>PG_DIAG_CONTEXT</symbol></term>
<listitem>
<para>
Une indication du contexte dans lequel l'erreur est apparue. Actuellement, cela
inclut une trace de la pile d'appels des fonctions actives de langages de
procédures et de requêtes générées en interne. La trace a une
entrée par ligne, la plus récente se trouvant au début.
</para>
</listitem>
</varlistentry>

         <varlistentry id="libpq-pg-diag-schema-name">
          <term><symbol>PG_DIAG_SCHEMA_NAME</symbol></term>
          <listitem>
           <para>
            If the error was associated with a specific database object,
            the name of the schema containing that object, if any.
           </para>
          </listitem>
         </varlistentry>

         <varlistentry id="libpq-pg-diag-table-name">
          <term><symbol>PG_DIAG_TABLE_NAME</symbol></term>
          <listitem>
           <para>
            If the error was associated with a specific table, the name of
            the table.  (When this field is present, the schema name field
            provides the name of the table's schema.)
           </para>
          </listitem>
         </varlistentry>

         <varlistentry id="libpq-pg-diag-column-name">
          <term><symbol>PG_DIAG_COLUMN_NAME</symbol></term>
          <listitem>
           <para>
            If the error was associated with a specific table column, the
            name of the column.  (When this field is present, the schema
            and table name fields identify the table.)
           </para>
          </listitem>
         </varlistentry>

         <varlistentry id="libpq-pg-diag-datatype-name">
          <term><symbol>PG_DIAG_DATATYPE_NAME</symbol></term>
          <listitem>
           <para>
            If the error was associated with a specific datatype, the name
            of the datatype.  (When this field is present, the schema name
            field provides the name of the datatype's schema.)
           </para>
          </listitem>
         </varlistentry>

         <varlistentry id="libpq-pg-diag-constraint-name">
          <term><symbol>PG_DIAG_CONSTRAINT_NAME</symbol></term>
          <listitem>
           <para>
            If the error was associated with a specific constraint,
            the name of the constraint.  The table or domain that the
            constraint belongs to is reported using the fields listed
            above.  (For this purpose, indexes are treated as constraints,
            even if they weren't created with constraint syntax.)
           </para>
          </listitem>
         </varlistentry>

<varlistentry id="libpq-pg-diag-source-file">
<term><symbol>PG_DIAG_SOURCE_FILE</symbol></term>
<listitem>
<para>
Le nom du fichier contenant le code source où l'erreur a été rapportée.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-source-line">
<term><symbol>PG_DIAG_SOURCE_LINE</symbol></term>
<listitem>
<para>
Le numéro de ligne dans le code source où l'erreur a été rapportée.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pg-diag-source-function">
<term><symbol>PG_DIAG_SOURCE_FUNCTION</symbol></term>
<listitem>
<para>
Le nom de la fonction dans le code source où l'erreur a été rapportée.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

       <note>
        <para>
         The fields for schema name, table name, column name, datatype
         name, and constraint name are supplied only for a limited number
         of error types; see <xref linkend="errcodes-appendix"/>.
        </para>
       </note>

<para>
Le client est responsable du formatage des informations affichées suivant
à ses besoins&nbsp;; 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.
</para>

<para>
Les erreurs générées en interne par <application>libpq</application> auront une
sévérité et un message principal mais aucun autre champ. Les erreurs renvoyées
par un serveur utilisant un protocole antérieure à la 3.0 inclueront la
sévérité, le message principal et, quelques fois, un message détaillé mais
aucun autre champ.
</para>

<para>
Notez que les champs d'erreurs sont seulement disponibles pour les objets
<structname>PGresult</structname>, et non pas pour les objets
<structname>PGconn</structname>&nbsp;; il n'existe pas de fonction
<function>PQerrorField</function>.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqclear">
<term><function>PQclear</function><indexterm><primary>PQclear</primary></indexterm></term>
<listitem>
<para>
          Libère le stockage associé avec un <structname>PGresult</structname>.
          Chaque résultat de commande devrait être libéré via
          <function>PQclear</function> lorsqu'il n'est plus nécessaire.
<synopsis>void PQclear(PGresult *res);
</synopsis>
</para>

<para>
          Vous pouvez conserver un objet <structname>PGresult</structname>
          aussi longtemps que vous en avez besoin&nbsp;; 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
          <function>PQclear</function>. En cas d'oubli, ceci résultera en des
          pertes mémoires pour votre application.
</para>
</listitem>
</varlistentry>

</variablelist>
</para>
</sect2>

<sect2 id="libpq-exec-select-info">
  <title>Récupérer l'information provenant des résultats des requêtes</title>

<para>
Ces fonctions sont utilisées pour extraire des informations provenant d'un objet
<structname>PGresult</structname> représentant un résultat valide pour une
requête (statut <literal>PGRES_TUPLES_OK</literal> ou <literal>PGRES_SINGLE_TUPLE</literal>). Ils peuvent aussi être
utilisés pour extraire des informations à partir d'une opération Describe
réussie&nbsp;: le résultat d'un Describe a les mêmes informations de colonnes
qu'une exécution réelle de la requête aurait fournie, mais elle ne renvoie pas
de lignes. Pour les objets
ayant d'autres valeurs de statut, ces fonctions agiront comme si le résultat n'avait
aucune ligne et aucune colonne.
</para>

<variablelist>
<varlistentry id="libpq-pqntuples">
<term><function>PQntuples</function><indexterm><primary>PQntuples</primary></indexterm></term>
<listitem>
<para>
          Renvoie le nombre de lignes (tuples) du résultat de la requête. Comme
	  elle envoie un entier, les gros ensembles de résultat pourraient
	  dépasser la limite des valeurs renvoyées sur les systèmes
	  d'exploitation 32 bits.
<synopsis>int PQntuples(const PGresult *res);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqnfields">
<term><function>PQnfields</function><indexterm><primary>PQnfields</primary></indexterm></term>
<listitem>
<para>
          Renvoie le nombre de colonnes (champs) de chaque ligne du résultat de
          la requête.
<synopsis>int PQnfields(const PGresult *res);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqfname">
<term><function>PQfname</function><indexterm><primary>PQfname</primary></indexterm></term>
<listitem>
<para>
          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 numéro. Il sera libéré quand la poignée
	  <structname>PGresult</structname> associée est passée à <function>PQclear</function>.
<synopsis>char *PQfname(const PGresult *res,
              int column_number);
</synopsis>
</para>

<para>
<symbol>NULL</symbol> est renvoyé si le numéro de colonne est en dehors de la
plage.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqfnumber">
<term><function>PQfnumber</function><indexterm><primary>PQfnumber</primary></indexterm></term>
<listitem>
<para>
          Renvoie le numéro de colonne associé au nom de la colonne donné.
<synopsis>int PQfnumber(const PGresult *res,
              const char *column_name);
</synopsis>
</para>

<para>
        -1 est renvoyé si le nom donné ne correspond à aucune colonne.
</para>

<para>
        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
<programlisting>SELECT 1 AS FOO, 2 AS "BAR";
</programlisting>
        nous devons obtenir les résultats suivants&nbsp;:
<programlisting>PQfname(res, 0)              <lineannotation>foo</lineannotation>
PQfname(res, 1)              <lineannotation>BAR</lineannotation>
PQfnumber(res, "FOO")        <lineannotation>0</lineannotation>
PQfnumber(res, "foo")        <lineannotation>0</lineannotation>
PQfnumber(res, "BAR")        <lineannotation>-1</lineannotation>
PQfnumber(res, "\"BAR\"")    <lineannotation>1</lineannotation>
</programlisting>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqftable">
<term><function>PQftable</function><indexterm><primary>PQftable</primary></indexterm></term>
<listitem>
<para>
 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 à zéro mais les colonnes des
 tables ont des numéros différents de zéro.
<synopsis>Oid PQftable(const PGresult *res,
             int column_number);
</synopsis>
</para>

<para>
<literal>InvalidOid</literal> 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. Vous
pouvez lancer des requêtes vers la table système <literal>pg_class</literal>
pour déterminer exactement quelle table est référencée.
</para>

<para>
          Le type <type>Oid</type> et la constante
          <literal>InvalidOid</literal> sera définie lorsque vous incluerez le
          fichier d'en-tête <application>libpq</application>. Ils auront le même
          type entier.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqftablecol">
<term><function>PQftablecol</function><indexterm><primary>PQftablecol</primary></indexterm></term>
<listitem>
<para>
 Renvoie le numéro de colonne (à l'intérieur de la table) de la colonne
 correspondant à la colonne spécifiée de résultat de la requête. Les numéros de
 la colonne résultante commencent à 0.
<synopsis>int PQftablecol(const PGresult *res,
                int column_number);
</synopsis>
</para>

<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqfformat">
<term><function>PQfformat</function><indexterm><primary>PQfformat</primary></indexterm></term>
<listitem>
<para>
 Renvoie le code de format indiquant le format de la colonne donné. Les numéros
 de colonnes commencent à zéro.
<synopsis>int PQfformat(const PGresult *res,
              int column_number);
</synopsis>
</para>

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

<varlistentry id="libpq-pqftype">
<term><function>PQftype</function><indexterm><primary>PQftype</primary></indexterm></term>
<listitem>
<para>
          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.
<synopsis>Oid PQftype(const PGresult *res,
            int column_number);
</synopsis>
</para>

<para>
Vous pouvez lancer des requêtes sur la table système <literal>pg_type</literal>
pour obtenir les noms et propriétés des différents types de données.
Les <acronym>OID</acronym> des types de données intégrés sont définis dans le
fichier <filename>src/include/catalog/pg_type.h</filename> de la distribution
des sources.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqfmod">
<term><function>PQfmod</function><indexterm><primary>PQfmod</primary></indexterm></term>
<listitem>
<para>
          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.
<synopsis>int PQfmod(const PGresult *res,
           int column_number);
</synopsis>
</para>

<para>
L'interprétation des valeurs du modificateur est spécifique au type&nbsp;;
elles indiquent la précision ou les limites de taille. La valeur -1 est
utilisée pour indiquer qu'<quote>aucune information n'est disponible</quote>. La
plupart des types de données n'utilisent pas les modificateurs, auquel cas la
valeur est toujours -1.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqfsize">
<term><function>PQfsize</function><indexterm><primary>PQfsize</primary></indexterm></term>
<listitem>
<para>
          Renvoie la taille en octets de la colonne associée au numéro de
          colonne donné. Les numéros de colonnes commencent à zéro.
<synopsis>int PQfsize(const PGresult *res,
            int column_number);
</synopsis>
</para>

<para>
<function>PQfsize</function> 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 (de façon cohérente, 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.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqbinarytuples">
<term><function>PQbinaryTuples</function><indexterm><primary>PQbinaryTuples</primary></indexterm></term>
<listitem>
<para>
Renvoie 1 si <structname>PGresult</structname> contient des données binaires et 0 s'il
contient des données texte.
<synopsis>int PQbinaryTuples(const PGresult *res);
</synopsis>
</para>

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

<varlistentry id="libpq-pqgetvalue">
<term><function>PQgetvalue</function><indexterm><primary>PQgetvalue</primary></indexterm></term>
<listitem>
<para>
            Renvoie la valeur d'un seul champ d'une seule ligne d'un
            <structname>PGresult</structname>. 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 la poignée
	    <structname>PGresult</structname> associée est passée à
            <function>PQclear</function>.
<synopsis>char* PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);
</synopsis>
</para>

<para>
Pour les données au format texte, la valeur renvoyée par
<function>PQgetvalue</function> 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 <function>typsend</function> et
<function>typreceive</function> (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).
</para>

<para>
Une chaîne vide est renvoyée si la valeur du champ est NULL. Voir
<function>PQgetisnull</function> pour distinguer les valeurs NULL des valeurs de
chaîne vide.
</para>

<para>
Le pointeur renvoyé par <function>PQgetvalue</function> pointe vers le stockage
qui fait partie de la structure <structname>PGresult</structname>. Personne ne
devrait modifier les données vers lesquelles il pointe et tout le monde
devrait copier explicitement les données dans un autre stockage s'il n'est
pas utilisé après la durée de vie de la struture
<structname>PGresult</structname>.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqgetisnull">
<term><function>PQgetisnull</function><indexterm><primary>PQgetisnull</primary></indexterm></term>
<listitem>
<indexterm><primary>valeur NULL</primary><secondary sortas="libpq">dans
libpq</secondary></indexterm>
<para>
           Teste un champ pour savoir s'il est nul. Les numéros de lignes et de
           colonnes commencent à zéro.
<synopsis>int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);
</synopsis>
</para>

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

<varlistentry id="libpq-pqgetlength">
<term><function>PQgetlength</function><indexterm><primary>PQgetlength</primary></indexterm></term>
<listitem>
<para>
          Renvoie la longueur réelle de la valeur d'un champ en octet. Les
          numéros de lignes et de colonnes commencent à zéro.
<synopsis>int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);
</synopsis>
</para>

<para>
C'est la longueur réelle des données pour la valeur particulière des données,
c'est-à-dire la taille de l'objet pointé par <function>PQgetvalue</function>.
Pour le format textuel, c'est identique à <function>strlen()</function>. Pour le format
binaire, c'est une information essentielle. Notez que <emphasis>personne</emphasis> ne
devrait se fier à <function>PQfsize</function> pour obtenir la taille réelle
des données.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqnparams">
<term><function>PQnparams</function><indexterm><primary>PQnparams</primary></indexterm></term>
<listitem>
<para>
          Renvoie le nombre de paramètres d'une instruction préparée.
<synopsis>
int PQnparams(const PGresult *res);
</synopsis>
</para>

<para>
Cette fonction est seulement utile pour inspecter le résultat de
<function>PQdescribePrepared</function>. Pour les autres types de requêtes, il
renverra zéro.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqparamtype">
<term><function>PQparamtype</function><indexterm><primary>PQparamtype</primary></indexterm></term>
<listitem>
<para>
          Renvoie le type de donnée du paramètre indiqué de l'instruction.
          Le numérotage des paramètres commence à 0.
<synopsis>
Oid PQparamtype(const PGresult *res, int param_number);
</synopsis>
</para>

<para>
Cette fonction est seulement utile pour inspecyer le résultat de
<function>PQdescribePrepared</function>. Pour les autres types de requêtes, il
renverra zéro.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqprint">
<term><function>PQprint</function><indexterm><primary>PQprint</primary></indexterm></term>
<listitem>
<para>
          Affiche toutes les lignes et, optionnellement, les noms des colonnes
          dans le flux de sortie spécifié.
<synopsis>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;
</synopsis>
</para>

<para>
Cette fonction était auparavant utilisée par <application>psql</application>
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.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="libpq-exec-nonselect">
  <title>Récupérer d'autres informations de résultats</title>

<para>
Ces fonctions sont utilisées pour extraire d'autres informations des objets
<structname>PGresult</structname>.
</para>

<variablelist>
<varlistentry id="libpq-pqcmdstatus">
<term><function>PQcmdStatus</function><indexterm><primary>PQcmdStatus</primary></indexterm></term>
<listitem>
<para>
          Renvoie l'état de la commande depuis l'instruction SQL qui a généré le
	  <structname>PGresult</structname>. L'appelant ne devrait pas libérer
	  directement le résultat. Il sera libéré quand la poignée
	  <structname>PGresult</structname> associée est passée à
          <function>PQclear</function>.
<synopsis>char * PQcmdStatus(PGresult *res);
</synopsis>
</para>
<para>
D'habitude, c'est juste le nom de la commande mais elle pourrait inclure des
données supplémentaires comme le nombre de lignes traitées.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqcmdtuples">
<term><function>PQcmdTuples</function><indexterm><primary>PQcmdTuples</primary></indexterm></term>
<listitem>
<para>
          Renvoie le nombre de lignes affectées par la commande SQL.
<synopsis>char * PQcmdTuples(PGresult *res);
</synopsis>
</para>

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

<varlistentry id="libpq-pqoidvalue">
<term><function>PQoidValue</function><indexterm><primary>PQoidValue</primary></indexterm></term>
<listitem>
<para>
          Renvoie l'OID<indexterm><primary>OID</primary><secondary>dans
          libpq</secondary></indexterm> de la ligne insérée, si la commande
          <acronym>SQL</acronym> était une instruction
          <command>INSERT</command> qui a inséré exactement une ligne dans une
	  table comprenant des OID ou un <command>EXECUTE</command> d'une requête
	  préparée contenant une instruction <command>INSERT</command> convenable.
	  Sinon, cette fonction renvoie <literal>InvalidOid</literal>. Cette
	  fonction renverra aussi <literal>InvalidOid</literal> si la table
	  touchée par l'instruction <command>INSERT</command> ne contient pas d'OID.
<synopsis>Oid PQoidValue(const PGresult *res);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqoidstatus">
<term><function>PQoidStatus</function><indexterm><primary>PQoidStatus</primary></indexterm></term>
<listitem>
<para>
       Cette fonction est obsolète. Utilisez plutôt
       <function>PQoidValue</function>. 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 <function>PQoidValue</function> renvoie
       la valeur de l'OID.
<synopsis>char * PQoidStatus(const PGresult *res);
</synopsis>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="libpq-exec-escape-string">
  <title>Chaîne d'échappement à inclure dans les commandes SQL</title>

   <indexterm zone="libpq-exec-escape-string">
    <primary>chaînes d'échappement</primary>
    <secondary>dans libpq</secondary>
   </indexterm>

  <variablelist>
    <varlistentry id="libpq-pqescapeliteral">
     <term>
      <function>PQescapeLiteral</function>
      <indexterm>
       <primary>PQescapeLiteral</primary>
      </indexterm>
     </term>

     <listitem>
     <para>
      <synopsis>
       char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);
      </synopsis>
     </para>

     <para>
      <function>PQescapeLiteral</function> é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 soient traités d'après leur
      signification spéciale par l'analyseur SQL.
      <function>PQescapeLiteral</function> réalise cette opération.
     </para>

     <para>
      <function>PQescapeLiteral</function> renvoie une version échappée du
      paramètre <parameter>str</parameter> dans une mémoire allouée avec
      <function>malloc()</function>. Cette mémoire devra être libérée en
      utilisant <function>PQfreemem()</function> quand le résultat ne sera
      plus utile. Un octet zéro de fin n'est pas requis et ne doit pas être
      compté dans <parameter>length</parameter>. (Si un octet zéro de fin est
      découvert avant la fin du traitement des <parameter>length</parameter>
      octets, <function>PQescapeLiteral</function> s'arrête au zéro&nbsp;; ce
      comportement est identique à celui de <function>strncpy</function>.) 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
      <productname>PostgreSQL</productname>. Un octet zéro final est aussi
      ajouté. Les guillemets simples qui doivent entourer les chaînes litérales
      avec <productname>PostgreSQL</productname> sont inclus dans la chaîne
      résultante.
     </para>

     <para>
      En cas d'erreur, <function>PQescapeLiteral</function> renvoit
      <symbol>NULL</symbol> et
      un message convenable est stocké dans l'objet
      <parameter>conn</parameter>.
     </para>

     <tip>
      <para>
       Il est particulièrement important de faire un échappement propre lors
       de l'utilisation de chaînes provenant d'une source qui n'est pas
       forcément de confiance. Sinon, il existe un risque de sécurité&nbsp;:
       vous vous exposez à une attaque de type <quote>injection SQL</quote>
       avec des commandes SQL non voulues injectées dans votre base de
       données.
      </para>
     </tip>

     <para>
      Notez qu'il n'est pas nécessaire ni correct de faire un échappement quand
      une valeur est passé en tant que paramètre séparé dans
      <function>PQexecParams</function> ou ce type de routine.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqescapeidentifier">
     <term>
      <function>PQescapeIdentifier</function>
      <indexterm>
       <primary>PQescapeIdentifier</primary>
      </indexterm>
     </term>

     <listitem>
     <para>
      <synopsis>
       char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);
      </synopsis>
     </para>

     <para>
      <function>PQescapeIdentifier</function> é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 pourraient autrement ne pas être interprétés comme faisant
      parti de l'identifiant par l'analyseur SQL ou lorsque l'identifiant
      pourrait contenir des caractères en majuscule, auquel cas le casse doit
      être préservée.
     </para>

     <para>
      <function>PQescapeIdentifier</function> renvoit une version du paramètre
      <parameter>str</parameter> échappée comme doit l'être un identifiant SQL,
      dans une mémoire allouée avec <function>malloc()</function>. Cette
      mémoire doit être libérée en utilisant <function>PQfreemem()</function>
      quand le résultat n'est plus nécessaire. Un octet zéro de fin n'est pas
      nécessaire et ne doit pas être comptabilisé dans
      <parameter>length</parameter>. (Si un octet zéro de fin est trouvé avant
      le traitement des <parameter>length</parameter> octets,
      <function>PQescapeIdentifier</function> s'arrête au zéro&nbsp;; ce
      comportement est identique à celui de <function>strncpy</function>.) 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 de fin est aussi ajouté. La chaîne de retour sera aussi entourée de
      guillemets doubles.
     </para>

     <para>
      En cas d'erreur, <function>PQescapeIdentifier</function> renvoit
      <symbol>NULL</symbol> et
      un message d'erreur convenable est stockée dans l'objet 
      <parameter>conn</parameter>.
     </para>

     <tip>
      <para>
       Comme avec les chaînes litérales, pour empêcher les attaques d'injection
       SQL, les identifiants SQL doivent être échappés lorsqu'elles proviennent
       de source non sûre.
      </para>
     </tip>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqescapestringconn">
     <term>
      <function>PQescapeStringConn</function>
      <indexterm>
       <primary>PQescapeStringConn</primary>
      </indexterm>
     </term>

     <listitem>
     <para>
      <synopsis>
       size_t PQescapeStringConn (PGconn *conn,
                                  char *to, const char *from, size_t length,
                                  int *error);
      </synopsis>
     </para>

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

     <para>
      Si le paramètre <parameter>error</parameter> est différent de <symbol>NULL</symbol>,
      alors <literal>*error</literal> est configuré à zéro en cas de succès
      et est différent de zéro en cas d'erreur. Actuellement, les seuls
      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 il est possible que le serveur la rejettera comme une
      chaîne malformée. En cas d'erreur, un message convenable est stocké dans
      l'objet <parameter>conn</parameter>, que <parameter>error</parameter>
      soit <symbol>NULL</symbol> ou non.
     </para>

     <para>
      <function>PQescapeStringConn</function> renvoit le nombre d'octets écrits
      dans <parameter>to</parameter>, sans inclure l'octet zéro de fin.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqescapestring">
     <term>
      <function>PQescapeString</function>
      <indexterm>
       <primary>PQescapeString</primary>
      </indexterm>
     </term>

     <listitem>
     <para>
      <function>PQescapeString</function> est une ancienne version de
      <function>PQescapeStringConn</function>.
      <synopsis>
       size_t PQescapeString (char *to, const char *from, size_t length);
      </synopsis>
     </para>

     <para>
      La seule différence avec <function>PQescapeStringConn</function> tient
      dans le fait que <function>PQescapeString</function> n'a pas de
      paramètres <parameter>conn</parameter> et <parameter>error</parameter>.
      À cause de cela, elle ne peut ajuster son
      comportement avec les propriétés de la connexion (comme l'encodage des
      caractères) et du coup, <emphasis>elle pourrait founir de mauvais
      résultats</emphasis>. De plus, elle ne peut pas renvoyer de conditions
      d'erreur.
     </para>

     <para>
      <function>PQescapeString</function> peut être utilisé proprement avec
      des programmes utilisant une seule connexion
      <productname>PostgreSQL</productname> à la fois (dans ce cas,
      il peut trouver ce qui l'intéresse <quote>en arrière-plan</quote>).
      Dans d'autres contextes, c'est un risque en terme de sécurité. Cette
      fonction devrait être évitée et remplacée autant que possible par la
      fonction <function>PQescapeStringConn</function>.
     </para>
     </listitem>
    </varlistentry>

  <varlistentry id="libpq-pqescapebyteaconn">
  <term><function>PQescapeByteaConn</function><indexterm><primary>PQescapeBytea</primary></indexterm></term>
  <listitem>
  <para>
   Échappe des données binaires à utiliser à l'intérieur d'une commande SQL avec
   le type <type>bytea</type>. Comme avec <function>PQescapeStringConn</function>,
   c'est seulement utilisé pour insérer des données directement dans une chaîne
   de commande SQL.
<synopsis>unsigned char *PQescapeByteaConn(PGconn *conn,
                                 const unsigned char *from,
                                 size_t from_length,
                                 size_t *to_length);</synopsis>
</para>

<para>
   Certaines valeurs d'octets <emphasis>doivent</emphasis> être échappées
   lorsqu'elles font partie d'un littéral <type>bytea</type> dans une
   instruction <acronym>SQL</acronym>. <function>PQescapeByteaConn</function>
   échappe les octets en utilisant soit un codage hexadécimal soit un
   échappement avec des antislashs. Voir <xref linkend="datatype-binary"/> pour
   plus d'informations.
  </para>

  <para>
   Le paramètre <parameter>from</parameter> pointe sur le premier octet de la
   chaîne à échapper et le paramètre <parameter>from_length</parameter> donne le
   nombre d'octets de cette chaîne binaire (un octet zéro de terminaison n'est
   ni nécessaire ni compté). Le paramètre <parameter>to_length</parameter>
   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.
  </para>

  <para>
   <function>PQescapeByteaConn</function> renvoie une version échappée du paramètre
   <parameter>from</parameter> dans la mémoire allouée avec
   <function>malloc()</function>. Cette mémoire doit être libérée avec
   <function>PQfreemem</function> 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 <productname>PostgreSQL</productname> et par l'entrée
   <type>bytea</type> de la fonction. Un octet zéro de terminaison est aussi
   ajouté. Les guillemets simples qui englobent les chaînes littérales de
   <productname>PostgreSQL</productname> ne font pas partie de la chaîne
   résultante.
  </para>
  <para>
   En cas d'erreur, un pointeur NULL est renvoyé et un message d'erreur adéquat
   est stocké dans l'objet <parameter>conn</parameter>. Actuellement, la seule erreur
   possible est une mémoire insuffisante pour stocker la chaîne résultante.
  </para>
  </listitem>
  </varlistentry>

  <varlistentry id="libpq-pqescapebytea">
  <term><function>PQescapeBytea</function><indexterm><primary>PQescapeBytea</primary></indexterm></term>
  <listitem>
  <para>
   <function>PQescapeBytea</function> est une version obsolète de
   <function>PQescapeByteaConn</function>.
<synopsis>
unsigned char *PQescapeBytea(const unsigned char *from,
                             size_t from_length,
                             size_t *to_length);
</synopsis>
</para>

  <para>
   La seule différence avec <function>PQescapeByteaConn</function> est que
   <function>PQescapeBytea</function> ne prend pas de paramètre
   <structname>PGconn</structname>. De ce fait, <function>PQescapeBytea</function>
   peut seulement être utilisé correctement dans des programmes qui n'utilisent
   qu'une seule connexion <productname>PostgreSQL</productname> à la fois (dans
   ce cas, il peut trouver ce dont il a besoin <quote>en arrière-plan</quote>).
   Il <emphasis>pourrait donner de mauvais résultats</emphasis> s'il était
   utilisé dans des programmes qui utilisent plusieurs connexions de bases de
   données (dans ce cas, utilisez plutôt <function>PQescapeByteaConn</function>).
  </para>
  </listitem>
  </varlistentry>

  <varlistentry id="libpq-pqunescapebytea">
  <term><function>PQunescapeBytea</function><indexterm><primary>PQunescapeBytea</primary></indexterm></term>
  <listitem>
  <para>
   Convertit une représentation de la chaîne en donnés binaires --
   l'inverse de <function>PQescapeBytea</function>. Ceci est nécessaire lors de
   la récupération de données <type>bytea</type> en format texte, mais pas lors
   de sa récupération au format binaire.

<synopsis>unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
</synopsis>
</para>

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

  <para>
   Cette conversion n'est pas l'inverse exacte de <function>PQescapeBytea</function>
   car la chaîne n'est pas échappée avec <function>PQgetvalue</function>. Cela
   signifie en particulier 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 <structname>PGconn</structname>.
  </para>
  </listitem>
  </varlistentry>
  </variablelist>
   
 </sect2>
</sect1>

<sect1 id="libpq-async">
<title>Traitement des commandes asynchrones</title>

  <indexterm zone="libpq-async"><primary>connexion non bloquante</primary></indexterm>

<para>
La fonction <function>PQexec</function> est adéquate pour soumettre des
commandes aux applications standards, synchrones. Néanmoins, il a quelques
déficiences pouvant être d'importance à certains utilisateurs&nbsp;:

<itemizedlist>
<listitem>
<para>
<function>PQexec</function> attend que la commande se termine. L'application
pourrait avoir d'autres travaux à réaliser (comme le rafraichissement de
l'interface utilisateur), auquel cas il ne voudra pas être bloqué en attente
de la réponse.
</para>
</listitem>
<listitem>
<para>
Comme l'exécution de l'application cliente est suspendue en attendant le
résultat, il est difficile pour l'application de décider qu'elle voudrait
annuler la commande en cours (c'est possible avec un gestionnaire de signaux
mais pas autrement).
</para>
</listitem>
<listitem>
<para>
<function>PQexec</function> ne peut renvoyer qu'une structure
<structname>PGresult</structname>. Si la chaîne de commande soumise contient
plusieurs commandes <acronym>SQL</acronym>, toutes les structures
<structname>PGresult</structname> sont annulées par
<function>PQexec</function>, sauf la dernière.
</para>
</listitem>

    <listitem>
     <para>
      <function>PQexec</function> récupère toujours le résultat entier de la
      commande, le mettant en cache dans une seule structure
      <structname>PGresult</structname>. Bien que cela simplifie la logique
      de la gestion des erreurs pour l'application, cela peut ne pas se
      révéler pratique pour les résultats contenant de nombreuses lignes.
     </para>
    </listitem>
</itemizedlist>
</para>

<para>
Les applications qui n'apprécient pas ces limitations peuvent utiliser à la
place les fonctions sous-jacentes à partir desquelles
<function>PQexec</function> est construit&nbsp;:
<function>PQsendQuery</function> et <function>PQgetResult</function>. Il existe
aussi <function>PQsendQueryParams</function>, <function>PQsendPrepare</function>,
<function>PQsendQueryPrepared</function>, <function>PQsendDescribePrepared</function>
et <function>PQsendDescribePortal</function>, pouvant être utilisées avec
<function>PQgetResult</function> pour dupliquer les fonctionnalités de
respectivement <function>PQexecParams</function>, <function>PQprepare</function>,
<function>PQexecPrepared</function>, <function>PQdescribePrepared</function> et
<function>PQdescribePortal</function>.

<variablelist>
<varlistentry id="libpq-pqsendquery">
<term><function>PQsendQuery</function><indexterm><primary>PQsendQuery</primary></indexterm></term>
<listitem>
<para>
          Soumet une commande au serveur sans attendre le(s) résultat(s). 1 est
          renvoyé si la commande a été correctement envoyée et 0 dans le cas
	  contraire (auquel cas, utilisez la fonction <function>PQerrorMessage</function>
	  pour obtenir plus d'informations sur l'échec).
<synopsis>int PQsendQuery(PGconn *conn, const char *command);</synopsis>

          Après un appel réussi à <function>PQsendQuery</function>, appelez
          <function>PQgetResult</function> une ou plusieurs fois pour obtenir
          les résultats. <function>PQsendQuery</function>  ne peut pas être appelé
          de nouveau (sur la même connexion) tant que
          <function>PQgetResult</function> ne renvoie pas de pointeur nul,
          indiquant que la commande a terminé.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqsendqueryparams">
<term><function>PQsendQueryParams</function><indexterm><primary>PQsendQueryParams</primary></indexterm></term>
<listitem>
<para>
          Soumet une commande et des paramètres séparés au serveur sans
          attendre le(s) résultat(s).
<synopsis>int PQsendQueryParams(PGconn *conn,
                      const char *command,
                      int nParams,
                      const Oid *paramTypes,
                      const char * const *paramValues,
                      const int *paramLengths,
                      const int *paramFormats,
                      int resultFormat);
</synopsis>

        Ceci est équivalent à <function>PQsendQuery</function> sauf que les
        paramètres de requêtes peuvent être spécifiés à partir de la chaîne de
        requête. Les paramètres de la fonction sont gérés de façon identique à
        <function>PQexecParams</function>. Comme
        <function>PQexecParams</function>, cela ne fonctionnera pas 
        pour les connexions utilisant le protocole 2.0 et cela ne permettra
        qu'une seule commande dans la chaîne de requête.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqsendprepare">
  <term><function>PQsendPrepare</function><indexterm><primary>PQsendPrepare</primary></indexterm></term>
<listitem>
  <para>
    Envoie une requête pour créer une instruction préparée avec les paramètres
    donnés et redonne la main sans attendre la fin de son exécution.
    <synopsis>      int PQsendPrepare(PGconn *conn,
      const char *stmtName,
      const char *query,
      int nParams,
      const Oid *paramTypes);
    </synopsis>
    
  Ceci est la version asynchrone de <function>PQprepare</function>&nbsp;: elle
  renvoie 1 si elle a été capable d'envoyer la requête, 0 sinon. Après un
  appel terminé avec succès, appelez <function>PQgetResult</function> pour
  déterminer si le serveur a créé avec succès l'instruction préparée. Les
  paramètres de la fonction sont gérés de façon identique à
  <function>PQprepare</function>. Comme <function>PQprepare</function>, cela ne
  fonctionnera pas sur les connexions utilisant le protocole 2.0.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqsendqueryprepared">
<term><function>PQsendQueryPrepared</function><indexterm><primary>PQsendQueryPrepared</primary></indexterm></term>
<listitem>
<para>
          Envoie une requête pour exécuter une instruction préparée avec des
          paramètres donnés sans attendre le(s) résultat(s).
<synopsis>int PQsendQueryPrepared(PGconn *conn,
                        const char *stmtName,
                        int nParams,
                        const char * const *paramValues,
                        const int *paramLengths,
                        const int *paramFormats,
                        int resultFormat);
</synopsis>

        Ceci est similaire à <function>PQsendQueryParams</function> mais la
        commande à exécuter est spécifiée en nommant une instruction
        précédemment préparée au lieu de donner une chaîne contenant la
        requête. Les paramètres de la fonction sont gérés de façon identique à
        <function>PQexecPrepared</function>. Comme
        <function>PQexecPrepared</function>, cela ne fonctionnera pas pour les
        connexions utilisant le protocole 2.0.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqsenddescribeprepared">
<term><function>PQsendDescribePrepared</function><indexterm><primary>PQsendDescribePrepared</primary></indexterm></term>
<listitem>
<para>
        Soumet une requête pour obtenir des informations sur l'instruction
        préparée indiquée sans attendre sa fin.
<synopsis>
int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
</synopsis>

        Ceci est la version asynchrone de <function>PQdescribePrepared</function>&nbsp;:
        elle renvoie 1 si elle a été capable d'envoyer la requête, 0 dans le cas
        contraire. Après un appel réussi, appelez <function>PQgetResult</function>
        pour obtenir les résultats.
        Les paramètres de la fonction sont gérés de façon identique à
        <function>PQdescribePrepared</function>. Comme
        <function>PQdescribePrepared</function>, cela ne fontionnera pas avec
        les connexions utilisant le protocole 2.0.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqsenddescribeportal">
<term><function>PQsendDescribePortal</function><indexterm><primary>PQsendDescribePortal</primary></indexterm></term>
<listitem>
<para>
        Soumet une requête pour obtenir des informations sur le portail indiqué
        sans attendre la fin de la commande.
<synopsis>
int PQsendDescribePortal(PGconn *conn, const char *portalName);
</synopsis>

        Ceci est la version asynchrone de <function>PQdescribePortal</function>&nbsp;:
        elle renvoie 1 si elle a été capable d'envoyer la requête, 0 dans le cas
        contraire. Après un appel réussi, appelez <function>PQgetResult</function>
        pour obtenir les résultats.
        Les paramètres de la fonction sont gérés de façon identique à
        <function>PQdescribePortal</function>. Comme
        <function>PQdescribePortal</function>, cela ne fontionnera pas avec
        les connexions utilisant le protocole 2.0.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqgetresult">
<term><function>PQgetResult</function><indexterm><primary>PQgetResult</primary></indexterm></term>
<listitem>
<para>
          Attend le prochain résultat d'un appel précédant à
          <function>PQsendQuery</function>,
          <function>PQsendQueryParams</function>,
  	      <function>PQsendPrepare</function>,
          <function>PQsendQueryPrepared</function>,
          <function>PQsendDescribePrepared</function> ou
          <function>PQsendDescribePortal</function>, et le renvoie. Un pointeur
          nul est renvoyé quand la commande est terminée et qu'il n'y aura plus
          de résultats.
<synopsis>PGresult *PQgetResult(PGconn *conn);
</synopsis>
</para>

<para>
          <function>PQgetResult</function> doit être appelé de façon répété
          jusqu'à ce qu'il retourne un pointeur nul indiquant que la commande
          s'est terminée (si appelé à un moment où aucune commande n'est
          active, <function>PQgetResult</function> renverra seulement un
          pointeur nul à la fois). Chaque résultat non nul provenant de
          <function>PQgetResult</function> devrait être traité en utilisant les
          mêmes fonctions d'accès à <structname>PGresult</structname> que celles
          précédemment décrites. N'oubliez pas de libérer chaque objet résultat
          avec <function>PQclear</function> une fois que vous en avez terminé.
          Notez que <function>PQgetResult</function> bloquera seulement si la
          commande est active et que les données nécessaires en réponse n'ont
          pas encore été lues par <function>PQconsumeInput</function>.
</para>

      <note>
       <para>
        Même quand <function>PQresultStatus</function> indique une erreur
        fatale, <function>PQgetResult</function> doit être appelé
        jusqu'à ce qu'il renvoie un pointeur nul pour permettre à
        <application>libpq</application> de traiter l'information sur
        l'erreur correctement.
       </para>
      </note>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
Utiliser <function>PQsendQuery</function> et <function>PQgetResult</function>
résout un des problèmes de <function>PQexec</function>&nbsp;: si une chaîne de
commande contient plusieurs commandes <acronym>SQL</acronym>, les résultats de
ces commandes peuvent être obtenus individuellement (ceci permet une simple
forme de traitement en parallèle&nbsp;: le client peut gérer les résultats
d'une commande alors que le serveur travaille sur d'autres requêtes de la même
chaîne de commandes).
  </para>

  <para>
   Une autre fonctionnalité fréquemment demandée, pouvant être obtenu avec
   <function>PQsendQuery</function> et <function>PQgetResult</function> est
   la récupération d'un gros résultat une ligne à la fois. Ceci est discuté
   dans <xref linkend="libpq-single-row-mode"/>.
  </para>

  <para>
   Néanmoins, appeler <function>PQgetResult</function>
causera toujours un blocage du client jusqu'à la fin de la prochaine commande
<acronym>SQL</acronym>. Ceci est évitable en utilisant proprement deux
fonctions supplémentaires&nbsp;:

<variablelist>
<varlistentry id="libpq-pqconsumeinput">
<term><function>PQconsumeInput</function><indexterm><primary>PQconsumeInput</primary></indexterm></term>
<listitem>
<para>
          Si l'entrée est disponible à partir du serveur, consommez-la.
<synopsis>int PQconsumeInput(PGconn *conn);
</synopsis>
</para>

<para>
<function>PQconsumeInput</function> renvoie normalement 1 indiquant
<quote>aucune erreur</quote>, mais renvoie zéro s'il y a eu une erreur (auquel
cas <function>PQerrorMessage</function> peut être consulté). Notez que le
résultat ne dit pas si des données ont été récupérées en entrée. Après avoir
appelé <function>PQconsumeInput</function>, l'application devrait vérifier
<function>PQisBusy</function> et/ou <function>PQnotifies</function> pour voir
si leur état a changé.
</para>
<para>
<function>PQconsumeInput</function> pourrait être appelé même si l'application
n'est pas encore préparé à gérer un résultat ou une notification. La fonction
lira les données disponibles et les sauvegardera dans un tampon indiquant
ainsi qu'une lecture d'un <function>select()</function> est possible.
L'application peut donc utiliser <function>PQconsumeInput</function> pour
effacer la condition <function>select()</function> immédiatement, puis pour
examiner les résultats autant que possible.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqisbusy">
<term><function>PQisBusy</function><indexterm><primary>PQisBusy</primary></indexterm></term>
<listitem>
<para>
Renvoie 1 si une commande est occupée, c'est-à-dire que
<function>PQgetResult</function> bloquerait en attendant une entrée. Un zéro
indiquerait que <function>PQgetResult</function> peut être appelé avec
l'assurance de ne pas être bloqué.
<synopsis>int PQisBusy(PGconn *conn);
</synopsis>
</para>

<para>
<function>PQisBusy</function> ne tentera pas lui-même de lire les données à
partir du serveur&nbsp;; du coup, <function>PQconsumeInput</function> doit être
appelé d'abord ou l'état occupé ne s'arrêtera jamais.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
Une application typique de l'utilisation de ces fonctions aura une boucle
principale utilisant <function>select()</function> ou <function>poll()</function> pour
attendre toutes les conditions auxquelles il doit répondre. Une des conditions
sera la disponibilité des données à partir du serveur, ce qui signifie des données
lisibles pour <function>select()</function> sur le descripteur de
fichier identifié par <function>PQsocket</function>. Lorsque la boucle
principale détecte la disponibilité de données, il devrait appeler
<function>PQconsumeInput</function> pour lire l'en-tête. Il peut ensuite appeler
<function>PQisBusy</function> suivi par <function>PQgetResult</function> si
<function>PQisBusy</function> renvoie false (0). Il peut aussi appeler 
<function>PQnotifies</function> pour détecter les messages <command>NOTIFY</command> 
(voir la <xref linkend="libpq-notify"/>).
</para>

<para>
Un client qui utilise
<function>PQsendQuery</function>/<function>PQgetResult</function> peut aussi
tenter d'annuler une commande en cours de traitement par le
serveur&nbsp;; voir la <xref linkend="libpq-cancel"/>. Mais quelque soit la valeur
renvoyée par <function>PQcancel</function>, l'application doit continuer avec
la séquence normale de lecture du résultat en utilisant
<function>PQgetResult</function>. Une annulation réussie causera simplement une
fin plus rapide de la commande.
</para>

<para>
En utilisant les fonctions décrites ci-dessus, il est possible d'éviter le
blocage pendant l'attente de données du serveur. Néanmoins, il est toujours
possible que l'application se bloque en attendant l'envoi vers le serveur.
C'est relativement peu fréquent mais cela peut arriver si de très longues
commandes SQL ou données sont envoyées (c'est bien plus probable si
l'application envoie des données via <command>COPY IN</command>).  Pour
empêcher cette possibilité et réussir des opérations de bases de données
totalement non bloquantes, les fonctions supplémentaires suivantes pourraient
être utilisées.

<variablelist>
<varlistentry id="libpq-pqsetnonblocking">
 <term><function>PQsetnonblocking</function><indexterm><primary>PQsetnonblocking</primary></indexterm></term>
 <listitem>
   <para>
    Initialise le statut non bloquant de la connexion.
<synopsis>int PQsetnonblocking(PGconn *conn, int arg);
</synopsis>
</para>

<para>
    Initialise l'état de la connexion à non bloquant si   
    <parameter>arg</parameter> vaut 1 et à bloquant si
    <parameter>arg</parameter> vaut 0. Renvoie 0 si OK, -1 en cas d'erreur.
   </para>
   <para>
    Dans l'état non bloquant, les appels à
    <function>PQsendQuery</function>,
    <function>PQputline</function>, <function>PQputnbytes</function>
    et <function>PQendcopy</function> ne bloqueront pas mais renverront à la
    place une erreur s'ils ont besoin d'être de nouveau appelés.
   </para>
   <para>
    Notez que <function>PQexec</function> n'honore pas le mode non
    bloquant&nbsp;; s'il est appelé, il agira d'une façon bloquante malgré tout.
   </para>
 </listitem>
</varlistentry>

<varlistentry id="libpq-pqisnonblocking">
<term><function>PQisnonblocking</function><indexterm><primary>PQisnonblocking</primary></indexterm></term>
<listitem>
<para>
       Renvoie le statut bloquant de la connexion à la base de données.
<synopsis>int PQisnonblocking(const PGconn *conn);
</synopsis>
</para>

<para>
       Renvoie 1 si la connexion est en mode non bloquant, 1 dans le 
       cas contraire.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqflush">
<term><function>PQflush</function><indexterm><primary>PQflush</primary></indexterm></term>
<listitem>
<para>
Tente de vider les données des queues de sortie du serveur. Renvoie 0 en cas de
succès (ou si la queue d'envoi est vide), -1 en cas d'échec quelque soit la
raison ou 1 s'il a été incapable d'envoyer encore toutes les données dans la
queue d'envoi (ce cas arrive seulement si la connexion est non bloquante).
<synopsis>int PQflush(PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
Après avoir envoyé une commande ou des données dans une connexion non bloquante,
appelez <function>PQflush</function>. S'il renvoie 1, attendez que la socket
soit disponible en écriture et appelez-la de nouveau&nbsp;; répétez cela jusqu'à
ce qu'il renvoie 0. Une fois que <function>PQflush</function> renvoie 0,
attendez que la socket soit disponible en lecture puis lisez la réponse comme
décrit ci-dessus.
</para>

</sect1>

 <sect1 id="libpq-single-row-mode">
  <title>Récupérer le résultats des requêtes ligne par ligne</title>

  <indexterm zone="libpq-single-row-mode">
   <primary>libpq</primary>
   <secondary>mode simple ligne</secondary>
  </indexterm>

  <para>
   D'habitude, <application>libpq</application> récupère le résultat complet
   d'une commande SQL et la renvoie à l'application sous la forme d'une seule
   structure <structname>PGresult</structname>. Ce comportement peut être un
   problème pour les commandes qui renvoient un grand nombre de lignes. Dans
   de tels cas, les applications peuvent utiliser
   <function>PQsendQuery</function> et <function>PQgetResult</function> dans
   le <firstterm>mode simple ligne</firstterm>. Dans ce mode, les lignes du
   résultat sont renvoyées à l'application une par une, au fur et à mesure
   qu'elles sont reçues du serveur.
  </para>

  <para>
   Pour entrer dans le mode simple ligne, appelez
   <function>PQsetSingleRowMode</function> immédiatement après un appel
   réussi à <function>PQsendQuery</function> (ou une fonction similaire).
   Cette sélection de mode ne fonctionne que pour la requête en cours
   d'exécution. Puis appelez <function>PQgetResult</function> de façon répétée,
   jusqu'à ce qu'elle renvoit null, comme documenté dans <xref
   linkend="libpq-async"/>. Si la requête renvoit des lignes, ils sont renvoyées
   en tant qu'objet <structname>PGresult</structname> individuel, qui ressemble
   à des résultats de requêtes standards en dehors du fait qu'elles ont le code
   de statut <literal>PGRES_SINGLE_TUPLE</literal> au lieu de
   <literal>PGRES_TUPLES_OK</literal>. Après la dernière ligne ou immédiatement
   si la requête ne renvoit aucune ligne, un objet de zéro ligne avec le statut
   <literal>PGRES_TUPLES_OK</literal> est renvoyé&nbsp;; c'est le signal
   qu'aucune autre ligne ne va arriver. (Notez cependant qu'il est toujours
   nécessaire de continuer à appeler <function>PQgetResult</function> jusqu'à
   ce qu'elle renvoit null.) Tous les objets <structname>PGresult</structname>
   contiendront les mêmes données de description de lignes (noms de colonnes,
   types, etc) qu'un objet <structname>PGresult</structname> standard aurait
   pour cette requête. Chaque objet doit être libéré avec la fonction
   <function>PQclear</function> comme d'ordinaire.
  </para>

  <para>
   <variablelist>
    <varlistentry id="libpq-pqsetsinglerowmode">
     <term>
      <function>PQsetSingleRowMode</function>
      <indexterm>
       <primary>PQsetSingleRowMode</primary>
      </indexterm>
     </term>

     <listitem>
      <para>
       Sélectionne le mode ligne simple pour la requête en cours d'exécution.

<synopsis>
int PQsetSingleRowMode(PGconn *conn);
</synopsis>
      </para>

      <para>
       Cette fonction peut seulement être appelée immédiatement après
       <function>PQsendQuery</function> ou une de ses fonctions sœurs, avant
       toute autre opération sur la connexion comme
       <function>PQconsumeInput</function> ou
       <function>PQgetResult</function>. Si elle est appelée au bon moment,
       la fonction active le mode simple ligne pour la requête en cours et
       renvoit 1. Sinon, le mode reste inchangé et la fonction renvoit 0. Dans
       tous les cas, le mode retourne à la normale après la fin de la requête
       en cours.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <caution>
   <para>
    Lors du traitement d'une requête, le serveur pourrait renvoyer quelques
    lignes puis rencontrer une erreur, causant l'annulation de la requête.
    D'ordinaire, la bibliothèque partagée <application>libpq</application>
    annule ces lignes et renvoit une erreur. Avec le mode simple ligne,
    des lignes ont déjà pu être envoyées à l'application. Du coup, l'application
    verra quelques objets <structname>PGresult</structname> de statut
    <literal>PGRES_SINGLE_TUPLE</literal> suivi par un objet de statut
    <literal>PGRES_FATAL_ERROR</literal>. Pour un bon comportement transactionnel,
    l'application doit être conçue pour invalider ou annuler tout ce qui a été
    fait avec les lignes précédemment traitées si la requête finit par échouer.
   </para>
  </caution>

 </sect1>

 <sect1 id="libpq-cancel">
  <title>Annuler des requêtes en cours d'exécution</title>
  
  <indexterm zone="libpq-cancel">
  <primary>annulation</primary><secondary>commande SQL</secondary></indexterm>

<para>
  Une application client peut demander l'annulation d'une commande qui est
  toujours en cours d'exécution par le serveur en utilisant les fonctions
  décrites dans cette section.
  
  <variablelist>
    <varlistentry id="libpq-pqgetcancel">
      <term><function>PQgetCancel</function>
      <indexterm><primary>PQgetCancel</primary></indexterm></term>
        <listitem>
          <para>
            Crée une structure de données contenant les informations
            nécessaires à l'annulation d'une commande lancée sur une
            connexion particulière à la base de données.
<synopsis>PGcancel *PQgetCancel(PGconn *conn);
</synopsis>
          </para>
    
          <para>
            <function>PQgetCancel</function> crée un objet fonction 
            <structname>PGcancel</structname><indexterm><primary>PGcancel</primary></indexterm> avec un
            objet connexion <structname>PGconn</structname>. Il renverra
            <symbol>NULL</symbol> si le paramètre <parameter>conn</parameter>
            donné est <symbol>NULL</symbol> ou est une connexion
            invalide. L'objet <structname>PGcancel</structname> est une structure opaque
            qui n'a pas pour but d'être accédé directement par
            l'application&nbsp;; elle peut seulement être passée à
            <function>PQcancel</function> ou <function>PQfreeCancel</function>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry id="libpq-pqfreecancel">
        <term><function>PQfreeCancel</function>
        <indexterm><primary>PQfreeCancel</primary></indexterm></term>
          <listitem>
            <para>
              Libère une structure de données créée par 
              <function>PQgetCancel</function>.
<synopsis>void PQfreeCancel(PGcancel *cancel);
</synopsis>
            </para>
  
            <para>
              <function>PQfreeCancel</function> libère un objet donné par
              <function>PQgetCancel</function>.
            </para>
          </listitem>
      </varlistentry>

      <varlistentry id="libpq-pqcancel">
         <term><function>PQcancel</function>
         <indexterm><primary>PQcancel</primary></indexterm></term>
         <listitem>
           <para>
             Demande que le serveur abandonne l'exécution de la commande en
             cours.
<synopsis>int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
</synopsis>
           </para>
  
           <para>
             La valeur renvoyée est 1 si la demande d'annulation a été
             correctement envoyée et 0 sinon. Si non, <parameter>errbuf</parameter>
             contient un message d'erreur expliquant pourquoi.
             <parameter>errbuf</parameter> doit être un tableau de caractères d'une
             taille de <parameter>errbufsize</parameter> octets (la taille
             recommandée est de 256 octets).
           </para>

           <para>
             Un envoi réussi ne garantit pas que la demande aura un quelconque
             effet. Si l'annulation est réelle, la commande en cours terminera
             plus tôt et renverra une erreur. Si l'annulation échoue (disons,
             parce que le serveur a déjà exécuté la commande), alors il n'y
             aura aucun résultat visible.
           </para>

           <para>
             <function>PQcancel</function> peut être invoqué de façon sûr
             par le gestionnaire de signaux si <parameter>errbuf</parameter> est une
             variable locale dans le gestionnaire de signaux. L'objet
             <structname>PGcancel</structname> est en lecture seule pour ce qui
             concerne <function>PQcancel</function>, pour qu'il puisse aussi
             être appelé à partir d'un thread séparé de celui manipulant
             l'objet <structname>PGconn</structname>.
           </para>
         </listitem>
       </varlistentry>
  </variablelist>

  <variablelist>
    <varlistentry id="libpq-pqrequestcancel">
    <term><function>PQrequestCancel</function>
    <indexterm><primary>PQrequestCancel</primary></indexterm></term>
    <listitem>
      <para>
       <function>PQrequestCancel</function> est une variante obsolète de
       <function>PQcancel</function>.
<synopsis>int PQrequestCancel(PGconn *conn);
</synopsis>
      </para>
  
      <para>
       Demande au serveur l'abandon du traitement de la commande en cours
       d'exécution. Elle opère directement sur l'objet
        <structname>PGconn</structname> et, en cas d'échec, stocke le message d'erreur
        dans l'objet <structname>PGconn</structname> (d'où il peut être récupéré avec
        <function>PQerrorMessage</function>). Bien qu'il s'agisse de la même
        fonctionnalité, cette approche est hasardeuse en cas de programmes
        compatibles avec les threads ainsi que pour les gestionnaires de
        signaux car il est possible que la surcharge du message d'erreur de
        <structname>PGconn</structname> gênera l'opération en cours sur la connexion.
      </para>
    </listitem>
    </varlistentry>
  </variablelist>
</para>

</sect1>

<sect1 id="libpq-fastpath">
<title>Interface à chemin rapide</title>

<indexterm zone="libpq-fastpath"><primary>fast path</primary></indexterm>

<indexterm zone="libpq-fastpath"><primary>chemin rapide</primary></indexterm>

<para>
<productname>PostgreSQL</productname> fournit une interface rapide pour
envoyer des appels de fonctions simples au serveur.
</para>

<tip>
<para>
Cette interface est quelque peu obsolète car vous pourriez réaliser les mêmes
choses avec des performances similaires et plus de fonctionnalités en initialisant
une instruction préparée pour définir l'appel de fonction. Puis, exécuter
l'instruction avec une transmission binaire des paramètres et des substitutions
de résultats pour un appel de fonction à chemin rapide.
</para>
</tip>

<para>
La fonction <function>PQfn</function><indexterm><primary>PQfn</primary></indexterm> demande
l'exécution d'une fonction du serveur via l'interface de chemin rapide&nbsp;:
<synopsis>PGresult* PQfn(PGconn* conn,
               int fnid,
               int *result_buf,
               int *result_len,
               int result_is_int,
               const PQArgBlock *args,
               int nargs);

typedef struct
{
    int len;
    int isint;
    union
    {
        int *ptr;
        int integer;
    } u;
} PQArgBlock;
</synopsis>
</para>

<para>
     L'argument <parameter>fnid</parameter> est l'OID de la fonction à exécuter.
     <parameter>args</parameter> et <parameter>nargs</parameter> définissent les paramètres à
passer à la fonction&nbsp;; ils doivent correspondre à la liste d'arguments
déclarés de la fonction. Quand le champ <parameter>isint</parameter> d'une structure est
vrai, la valeur de <parameter>u.integer</parameter> est envoyée au serveur en tant
qu'entier de la longueur indiquée (qui doit être 1, 2 ou 4 octets)&nbsp;; les
bons échanges d'octets se passent. Quand <parameter>isint</parameter> est faux, le
nombre d'octets indiqué sur <parameter>*u.ptr</parameter> est envoyé au
traitement&nbsp;; les données doivent être dans le format attendu par le
serveur pour la transmission binaire du type de données de l'argument de la
fonction. <parameter>result_buf</parameter> est le tampon dans lequel placer le
code de retour. L'appelant doit avoir alloué suffisamment d'espace pour stocker
le code de retour (il n'y a pas de vérification&nbsp;!). La longueur actuelle
du résultat sera renvoyé dans l'entier pointé par
<parameter>result_len</parameter>. Si un résultat sur un entier de 1, 2 ou
4 octets est attendu, initialisez <parameter>result_is_int</parameter> à 1,
sinon initialisez-le à 0. Initialiser <parameter>result_is_int</parameter> à 1
fait que <application>libpq</application> échange les octets de la valeur si nécessaire,
de façon à ce que la bonne valeur <type>int</type> soit délivrée pour la
machine cliente. Quand <parameter>result_is_int</parameter> vaut 0, la chaîne d'octets
au format binaire envoyée par le serveur est renvoyée non modifiée.
</para>

<para>
<function>PQfn</function> renvoie toujours un pointeur
<structname>PGresult</structname> valide. L'état du résultat devrait être
vérifié avant que le résultat ne soit utilisé. Le demandeur est responsable de
la libération de la structure <structname>PGresult</structname>  avec
<function>PQclear</function> lorsque celle-ci n'est plus nécessaire.
</para>

<para>
Notez qu'il n'est pas possible de gérer les arguments nuls, les résultats nuls
et les résultats d'ensembles nuls en utilisant cette interface.
</para>

</sect1>

<sect1 id="libpq-notify">
<title>Notification asynchrone</title>

  <indexterm zone="libpq-notify">
   <primary>NOTIFY</primary>
   <secondary>dans libpq</secondary>
  </indexterm>

<para>
<productname>PostgreSQL</productname> propose des notifications asynchrone via
les commandes <command>LISTEN</command> et <command>NOTIFY</command>. Une
session cliente enregistre son intérêt dans un canal particulier avec 
la commande <command>LISTEN</command> (et peut arrêter son écoute avec la
commande <command>UNLISTEN</command>). Toutes les sessions écoutant un
canal particulier seront notifiées de façon asynchrone lorsqu'une commande
<command>NOTIFY</command> avec ce nom de canal sera exécutée par une
session. Une chaîne de <quote>charge</quote> peut être renseigné pour fournir
des données supplémentaires aux processus en écoute.
</para>

<para>
Les applications <application>libpq</application> soumettent les commandes
<command>LISTEN</command>, <command>UNLISTEN</command> et <command>NOTIFY</command>
comme des commandes
SQL ordinaires. L'arrivée des messages <command>NOTIFY</command> peut être
détectée ensuite en appelant
<function>PQnotifies</function>.<indexterm><primary>PQnotifies</primary></indexterm>
</para>

<para>
La fonction <function>PQnotifies</function> renvoie la prochaine notification à
partir d'une liste de messages de notification non gérés reçus à partir du
serveur. Il renvoie un pointeur nul s'il n'existe pas de notifications en
attente. Une fois qu'une notification est renvoyée à partir de
<function>PQnotifies</function>, elle est considérée comme étant gérée et sera supprimée
de la liste des notifications.
<synopsis>PGnotify* PQnotifies(PGconn *conn);

typedef struct pgNotify
{
    char *relname;              /* nom du canal de la notification */
    int  be_pid;                /* ID du processus serveur notifiant */
    char *extra;                /* chaîne de charge pour la notification */
} PGnotify;
</synopsis>
Après avoir traité un objet <structname>PGnotify</structname> renvoyé par
<function>PQnotifies</function>, assurez-vous de libérer le pointeur
<function>PQfreemem</function>. Il est suffisant de libérer le pointeur
<structname>PGnotify</structname>&nbsp;; les champs
<structfield>relname</structfield> et <structfield>extra</structfield> ne
représentent pas des allocations séparées
(le nom de ces champs est historique&nbsp;; en particulier, les noms des
canaux n'ont pas besoin d'être liés aux noms des relations.)
</para>

<para>
<xref linkend="libpq-example-2"/> donne un programme d'exemple illustrant
l'utilisation d'une notification asynchrone.
</para>

<para>
<function>PQnotifies</function> ne lit pas réellement les données à partir du
serveur&nbsp;; il renvoie simplement les messages précédemment absorbés par une
autre fonction de <application>libpq</application>. Dans les précédentes
versions de <application>libpq</application>, la seule façon de s'assurer une
réception à temps des messages <command>NOTIFY</command> consistait à soumettre
constamment des commandes de soumission, même vides, puis de vérifier
<function>PQnotifies</function> après chaque <function>PQexec</function>. Bien
que ceci fonctionnait, cela a été abandonné à cause de la perte de puissance.
</para>

<para>
Une meilleure façon de vérifier les messages <command>NOTIFY</command> lorsque vous
n'avez pas de commandes utiles à exécuter est d'appeler
<function>PQconsumeInput</function> puis de vérifier
<function>PQnotifies</function>. Vous pouvez utiliser
<function>select()</function> pour attendre l'arrivée des données à partir du
serveur, donc en utilisant aucune puissance du <acronym>CPU</acronym> sauf
lorsqu'il y a quelque chose à faire (voir <function>PQsocket</function> pour
obtenir le numéro du descripteur de fichiers à utiliser avec
<function>select()</function>). Notez que ceci fonctionnera bien que vous
soumettez les commandes avec
<function>PQsendQuery</function>/<function>PQgetResult</function> ou que vous
utilisez simplement <function>PQexec</function>. Néanmoins, vous devriez vous
rappeler de vérifier <function>PQnotifies</function> après chaque
<function>PQgetResult</function> ou <function>PQexec</function> pour savoir si
des notifications sont arrivées lors du traitement de la commande.
</para>

</sect1>

<sect1 id="libpq-copy">
<title>Fonctions associées avec la commande <command>COPY</command></title>

<indexterm zone="libpq-copy">
 <primary>COPY</primary>
 <secondary>avec libpq</secondary>
</indexterm>

<para>
 Dans <productname>PostgreSQL</productname>, la commande <command>COPY</command>
 a des options pour lire ou écrire à
 partir de la connexion réseau utilisée par <application>libpq</application>.
 Les fonctions décrites dans cette section autorisent les applications à prendre
 avantage de cette capacité en apportant ou en consommant les données copiées.
</para>

<para>
 Le traitement complet est le suivant. L'application lance tout d'abord la
 commande SQL <command>COPY</command> via <function>PQexec</function> ou une
 des fonctions équivalents. La réponse à ceci (s'il n'y a pas d'erreur dans la
 commande) sera un objet <structname>PGresult</structname> avec un code de retour
 <literal>PGRES_COPY_OUT</literal> ou <literal>PGRES_COPY_IN</literal> (suivant
 la direction spécifiée pour la copie). L'application devrait alors utiliser les
 fonctions de cette section pour recevoir ou transmettre des lignes de données.
 Quand le transfert de données est terminé, un autre objet
 <structname>PGresult</structname> est renvoyé pour indiquer le succès ou l'échec du
 transfert. Son statut sera <literal>PGRES_COMMAND_OK</literal> en cas de succès
 et <literal>PGRES_FATAL_ERROR</literal> si un problème a été rencontré. À ce
 point, toute autre commande SQL pourrait être exécutée via
 <function>PQexec</function> (il n'est pas possible d'exécuter d'autres
 commandes SQL en utilisant la même connexion tant que l'opération
 <command>COPY</command> est en cours).
</para>

<para>
 Si une commande <command>COPY</command> est lancée via
 <function>PQexec</function> dans une chaîne qui pourrait contenir d'autres 
 commandes supplémentaires, l'application doit continuer à récupérer les
 résultats via <function>PQgetResult</function> après avoir terminé la séquence
 <command>COPY</command>. C'est seulement quand <function>PQgetResult</function> renvoie
 <symbol>NULL</symbol> que vous pouvez être certain que la chaîne de commandes
 <function>PQexec</function> est terminée et qu'il est possible de lancer
 d'autres commandes.
</para>

<para>
 Les fonctions de cette section devraient seulement être exécutées pour obtenir
 un statut de résultat <literal>PGRES_COPY_OUT</literal> ou
 <literal>PGRES_COPY_IN</literal> à partir de <function>PQexec</function> ou
 <function>PQgetResult</function>.
</para>

<para>
 Un objet <structname>PGresult</structname> gérant un de ces statuts comporte quelques
 données supplémentaires sur l'opération <command>COPY</command> qui commence.
 La données supplémentaire est disponible en utilisant les fonctions qui sont
 aussi utilisées en relation avec les résultats de requêtes&nbsp;:

<variablelist>
<varlistentry id="libpq-pqnfields-1">
<term><function>PQnfields</function><indexterm><primary>PQnfields</primary><secondary>with COPY</secondary></indexterm></term>
<listitem>
<para>
          Renvoie le nombre de colonnes (champs) à copier.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqbinarytuples-1">
<term><function>PQbinaryTuples</function><indexterm><primary>PQbinaryTuples</primary><secondary>with COPY</secondary></indexterm></term>
<listitem>
<para>
                0 indique que le format de copie complet est textuel (lignes
                séparées par des retours chariots, colonnes séparées par des
                caractères de séparation, etc).
                1 indique que le format de copie complet est binaire. Voir
                <xref linkend="sql-copy"/> pour plus
                d'informations.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqfformat-1">
<term><function>PQfformat</function><indexterm><primary>PQfformat</primary><secondary>with COPY</secondary></indexterm></term>
<listitem>
<para>
          Renvoie le code de format (0 pour le texte, 1 pour le binaire)
          associé avec chaque colonne de l'opération de copie. Les codes de
          format par colonne seront toujours zéro si le format de copie complet
          est textuel mais le format binaire supporte à la fois des colonnes
          textuelles et des colonnes binaires (néanmoins, avec l'implémentation
          actuelle de <command>COPY</command>, seules les colonnes binaires
          apparaissent dans une copie binaire&nbsp; donc les formats par
          colonnes correspondent toujours au format complet actuellement).
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<note>
<para>
Ces valeurs de données supplémentaires sont seulement disponibles en
utilisant le protocole 3.0. Lors de l'utilisation du protocole 2.0, toutes ces
fonctions renvoient 0.
</para>
</note>

<sect2 id="libpq-copy-send">
  <title>Fonctions d'envoi de données pour <command>COPY</command></title>

<para>
 Ces fonctions sont utilisées pour envoyer des données lors d'un <literal>COPY
 FROM STDIN</literal>. Elles échoueront si elles sont appelées alors que la connexion
 ne se trouve pas dans l'état <literal>COPY_IN</literal>.
</para>

<variablelist>
<varlistentry id="libpq-pqputcopydata">
<term><function>PQputCopyData</function><indexterm><primary>PQputCopyData</primary></indexterm></term>
<listitem>
<para>
 Envoie des données au serveur pendant un état <literal>COPY_IN</literal>.
<synopsis>int PQputCopyData(PGconn *conn,
                  const char *buffer,
                  int nbytes);
</synopsis>
</para>

<para>
Transmet les données de <command>COPY</command> dans le tampon spécifié
(<parameter>buffer</parameter>), sur <parameter>nbytes</parameter> octets, au serveur. Le résultat
vaut 1 si les données ont été envoyées, zéro si elles n'ont pas été envoyées car
la tentative pourrait bloquer (ce cas n'est possible que lors d'une connexion
en mode non bloquant) ou -1 si une erreur s'est produite (utilisez
<function>PQerrorMessage</function> pour récupérer des détails si la valeur de
retour vaut -1. Si la valeur vaut zéro, attendez qu'il soit prêt en écriture et
ré-essayez).
</para>

<para>
L'application pourrait diviser le flux de données de <command>COPY</command>
dans des chargements de tampon de taille convenable. Les limites n'ont pas de
signification sémantique lors de l'envoi. Le contenu du flux de données doit
correspondre au format de données attendu par la commande
<command>COPY</command>&nbsp;; voir <xref linkend="sql-copy"/>
pour des détails.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqputcopyend">
<term><function>PQputCopyEnd</function><indexterm><primary>PQputCopyEnd</primary></indexterm></term>
<listitem>
<para>
 Envoie une indication de fin de transfert au serveur lors de l'état
 <literal>COPY_IN</literal>.
<synopsis>int PQputCopyEnd(PGconn *conn,
                 const char *errormsg);
</synopsis>
</para>

<para>
Termine l'opération <literal>COPY_IN</literal> avec succès si <parameter>errormsg</parameter>
est <symbol>NULL</symbol>. Si <parameter>errormsg</parameter> n'est pas
<symbol>NULL</symbol> alors <command>COPY</command> échoue, la chaîne pointée par
<parameter>errormsg</parameter> étant utilisée comme message d'erreur (néanmoins, vous
ne devriez pas supposer que ce message d'erreur précis reviendra du
serveur car le serveur pourrait avoir déjà échouée sur la commande
<command>COPY</command> pour des raisons qui lui sont propres). Notez aussi que
l'option forçant l'échec ne fonctionnera pas lors de l'utilisation de
connexions avec un protocole pre-3.0.
</para>

<para>
Le résultat est 1 si la donnée de fin a été envoyée, zéro si elle ne l'a pas été
car cette tentative serait bloquante (ce cas est uniquement possible si la
connexion est dans un mode non bloquant) ou -1 si une erreur est survenue
(utilisez <function>PQerrorMessage</function> pour récupérer les détails si le
code de retour est -1. Si la valeur vaut zéro, attendez que le serveur
soit prêt en écriture et ré-essayez de nouveau).
</para>

<para>
Après un appel réussi à <function>PQputCopyEnd</function>, appelez
<function>PQgetResult</function> pour obtenir le statut de résultat final de la commande
<command>COPY</command>. Vous pouvez attendre que le résultat soit disponible de la
même façon. Puis, retournez aux opérations normales.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="libpq-copy-receive">
  <title>Fonctions de réception des données de <command>COPY</command></title>

<para>
 Ces fonctions sont utilisées pour recevoir des données lors d'un <literal>COPY
 TO STDOUT</literal>. Elles échoueront si elles sont appelées alors que la connexion
 n'est pas dans l'état <literal>COPY_OUT</literal>
</para>

<variablelist>
<varlistentry id="libpq-pqgetcopydata">
<term><function>PQgetCopyData</function><indexterm><primary>PQgetCopyData</primary></indexterm></term>
<listitem>
<para>
 Reçoit des données à partir du serveur lors d'un état <literal>COPY_OUT</literal>.
<synopsis>int PQgetCopyData(PGconn *conn,
                  char **buffer,
                  int async);
</synopsis>
</para>

<para>
Tente d'obtenir une autre ligne de données du serveur lors d'une
opération <command>COPY</command>. Les données ne sont renvoyées qu'une ligne à
la fois&nbsp;; si seulement une ligne partielle est disponible, elle n'est pas
renvoyée. Le retour d'une ligne avec succès implique l'allocation d'une portion
de mémoire pour contenir les données. Le paramètre <parameter>buffer</parameter> ne doit
pas être <symbol>NULL</symbol>. <parameter>*buffer</parameter> est initialisé pour
pointer vers la mémoire allouée ou vers <symbol>NULL</symbol> au cas où aucun
tampon n'est renvoyé. Un tampon résultat non <symbol>NULL</symbol> devra être
libéré en utilisant <function>PQfreemem</function> lorsqu'il ne sera plus utile.
</para>

<para>
Lorsqu'une ligne est renvoyée avec succès, le code de retour est le 
nombre d'octets de la donnée dans la ligne (et sera donc supérieur
à zéro). La chaîne renvoyée est toujours terminée par un octet nul bien que ce
ne soit utile que pour les <command>COPY</command> textuels. Un résultat
zéro indique que la commande <command>COPY</command> est toujours en cours mais
qu'aucune ligne n'est encore disponible (ceci est seulement possible lorsque
<parameter>async</parameter> est vrai). Un résultat -1 indique que
<command>COPY</command> a terminé. Un résultat -2 indique qu'une erreur est
survenue (consultez <function>PQerrorMessage</function> pour en connaître la raison).
</para>

<para>
Lorsque <parameter>async</parameter> est vraie (différent de zéro),
<function>PQgetCopyData</function> ne bloquera pas en attente d'entrée&nbsp;; il
renverra zéro si <command>COPY</command> est toujours en cours mais qu'aucune
ligne n'est encore disponible (dans ce cas, attendez qu'il soit prêt en
lecture puis appelez <function>PQconsumeInput</function> avant d'appeler
<function>PQgetCopyData</function> de nouveau). Quand <parameter>async</parameter> est faux (zéro),
<function>PQgetCopyData</function> bloquera tant que les données ne seront pas
disponibles ou tant que l'opération n'aura pas terminée.
</para>

<para>
Après que <function>PQgetCopyData</function> ait renvoyé -1, appelez
<function>PQgetResult</function> pour obtenir le statut de résultat final de la commande
<command>COPY</command>. Vous pourriez attendre la disponibilité de ce résultat comme
d'habitude. Puis, retournez aux opérations habituelles.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="libpq-copy-deprecated">
  <title>Fonctions obsolètes pour <command>COPY</command></title>

<para>
 Ces fonctions représentent d'anciennes méthodes de gestion de
 <command>COPY</command>. Bien qu'elles fonctionnent toujours, elles sont obsolètes à
 cause de leur pauvre gestion des erreurs, des méthodes non convenables de
 détection d'une fin de transmission, et du manque de support des transferts
 binaires et des transferts non bloquants.
</para>

<variablelist>
<varlistentry id="libpq-pqgetline">
<term><function>PQgetline</function><indexterm><primary>PQgetline</primary></indexterm></term>
<listitem>
<para>
          Lit une ligne de caractères terminée par un retour chariot (transmis
          par le serveur) dans un tampon de taille <parameter>length</parameter>.
<synopsis>int PQgetline(PGconn *conn,
              char *buffer,
              int length);
</synopsis>
</para>

<para>
Cette fonction copie jusqu'à <parameter>length</parameter>-1 caractères dans le tampon
et convertit le retour chariot en un octet nul. <function>PQgetline</function>
renvoie <symbol>EOF</symbol> à la fin de l'entrée, 0 si la ligne entière a été
lu et 1 si le tampon est complet mais que le retour chariot à la fin n'a pas
encore été lu.
</para>
<para>
Notez que l'application doit vérifier si un retour chariot est constitué de
deux caractères <literal>\.</literal>, ce qui indique que le serveur a terminé
l'envoi des résultats de la commande <command>COPY</command>. Si l'application
peut recevoir des lignes de plus de <parameter>length</parameter>-1 caractères, une
attention toute particulière est nécessaire pour s'assurer qu'elle reconnaisse
la ligne <literal>\.</literal> correctement (et ne la confond pas, par exemple,
avec la fin d'une longue ligne de données).
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqgetlineasync">
<term><function>PQgetlineAsync</function><indexterm><primary>PQgetlineAsync</primary></indexterm></term>
<listitem>
<para>
          Lit une ligne de données <command>COPY</command>
          (transmise par le serveur) dans un tampon sans blocage.
<synopsis>int PQgetlineAsync(PGconn *conn,
                   char *buffer,
                   int bufsize);
</synopsis>
</para>

<para>
Cette fonction est similaire à <function>PQgetline</function> mais elle peut
être utilisée par des applications qui doivent lire les données de
<command>COPY</command> de façon asynchrone, c'est-à-dire sans blocage. Après
avoir lancé la commande <command>COPY</command> et obtenu une réponse
<literal>PGRES_COPY_OUT</literal>, l'application devrait appeler
<function>PQconsumeInput</function> et
<function>PQgetlineAsync</function> jusqu'à ce que le signal de fin des données
ne soit détecté.
</para>
<para>
Contrairement à <function>PQgetline</function>, cette fonction prend la
responsabilité de détecter la fin de données.
</para>
<para>
À chaque appel, <function>PQgetlineAsync</function> renverra des données si une
ligne de données complète est disponible dans le tampon d'entrée de
<application>libpq</application>. Sinon, aucune ligne n'est renvoyée jusqu'à l'arrivée du
reste de la ligne. La fonction renvoie -1 si le marqueur de fin de copie des
données a été reconnu, 0 si aucune donnée n'est disponible ou un nombre
positif indiquant le nombre d'octets renvoyés. Si -1 est renvoyé, l'appelant
doit ensuite appeler <function>PQendcopy</function> puis retourner aux
traitements habituels.
</para>
<para>
Les données renvoyées ne seront pas étendues au delà de la limite de la ligne.
Si possible, une ligne complète sera retournée en une fois. Mais si le tampon
offert par l'appelant est trop petit pour contenir une ligne envoyée par le
serveur, alors une ligne de données partielle sera renvoyée. Avec des données
textuelles, ceci peut être détecté en testant si le dernier octet renvoyé est
<literal>\n</literal> ou non (dans un <command>COPY</command> binaire, l'analyse
réelle du format de données <command>COPY</command> sera nécessaire pour faire la
détermination équivalente). La chaîne renvoyée n'est pas terminée par un
octet nul (si vous voulez ajouter un octet nul de terminaison, assurez-vous de
passer un <parameter>bufsize</parameter> inférieur de 1 par rapport à l'espace
réellement disponible).
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqputline">
<term><function>PQputline</function><indexterm><primary>PQputline</primary></indexterm></term>
<listitem>
<para>
Envoie une chaîne terminée par un octet nul au serveur. Renvoie 0 si tout va
bien et <symbol>EOF</symbol> s'il est incapable d'envoyer la chaîne.
<synopsis>int PQputline(PGconn *conn,
              const char *string);
</synopsis>
</para>

<para>
Le flux de données de <command>COPY</command> envoyé par une série d'appels à
<function>PQputline</function> a le même format que celui renvoyé par
<function>PQgetlineAsync</function>, sauf que les applications ne sont pas
obligées d'envoyer exactement une ligne de données par appel à
<function>PQputline</function>&nbsp;; il est correct d'envoyer une ligne
partielle ou plusieurs lignes par appel.
</para>

<note>
<para>
Avant le protocole 3.0 de <productname>PostgreSQL</productname>, il était
nécessaire pour l'application d'envoyer explicitement les deux caractères
<literal>\.</literal> comme ligne finale pour indiquer qu'il a terminé l'envoi
des données du <command>COPY</command> data. Bien que ceci fonctionne toujours, cette
méthode est abandonnée et la signification spéciale de <literal>\.</literal>
pourrait être supprimée dans une prochaine version. Il est suffisant d'appeler
<function>PQendcopy</function> après avoir envoyé les vraies données.
</para>
</note>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqputnbytes">
<term><function>PQputnbytes</function><indexterm><primary>PQputnbytes</primary></indexterm></term>
<listitem>
<para>
Envoie une chaîne non terminée par un octet nul au serveur. Renvoie 0 si tout
va bien et <symbol>EOF</symbol> s'il n'a pas été capable d'envoyer la chaîne.
<synopsis>int PQputnbytes(PGconn *conn,
                const char *buffer,
                int nbytes);
</synopsis>
</para>

<para>
C'est exactement comme <function>PQputline</function> sauf que le tampon de
donnée n'a pas besoin d'être terminé avec un octet nul car le nombre d'octets
envoyés est spécifié directement. Utilisez cette procédure pour envoyer des
données binaires.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqendcopy">
<term><function>PQendcopy</function><indexterm><primary>PQendcopy</primary></indexterm></term>
<listitem>
<para>
 Se synchronise avec le serveur.
<synopsis>int PQendcopy(PGconn *conn);
</synopsis>
 Cette fonction attend que le serveur ait terminé la copie. Il devrait soit
 indiquer quand la dernière chaîne a été envoyée au serveur en utilisant
 <function>PQputline</function> soit le moment où la dernière chaîne a été reçue
 du serveur en utilisant <function>PGgetline</function>. Si ce n'est pas fait,
 le serveur renverra un <quote>out of sync</quote> (perte de
 synchronisation) au client. Suivant le retour de cette fonction, le serveur est
 prêt à recevoir la prochaine commande SQL. Le code de retour 0 indique un
 succès complet et est différent de zéro dans le cas contraire (utilisez
 <function>PQerrorMessage</function> pour récupérer des détails sur l'échec).
</para>

<para>
Lors de l'utilisation de <function>PQgetResult</function>, l'application
devrait répondre à un résultat <literal>PGRES_COPY_OUT</literal> en exécutant
<function>PQgetline</function> de façon répétée, suivi par un
<function>PQendcopy</function> une fois la ligne de terminaison aperçue.
Il devrait ensuite retourner à la boucle <function>PQgetResult</function>
jusqu'à ce que <function>PQgetResult</function> renvoie un pointeur nul. De
façon similaire, un résultat <literal>PGRES_COPY_IN</literal> est traité par une
série d'appels à <function>PQputline</function> suivis par un
<function>PQendcopy</function>, ensuite retour à la boucle
<function>PQgetResult</function>. Cet arrangement vous assurera qu'une commande
<command>COPY</command> intégrée dans une série de commandes
<acronym>SQL</acronym> sera exécutée correctement.
</para>

<para>
Les anciennes applications soumettent un <command>COPY</command> via
<function>PQexec</function> et assument que la transaction est faite après un
<function>PQendcopy</function>. Ceci fonctionnera correctement seulement si 
<command>COPY</command> est la seule commande <acronym>SQL</acronym> dans la
chaîne de commandes.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

</sect1>

<sect1 id="libpq-control">
<title>Fonctions de contrôle</title>

<para>
Ces fonctions contrôlent divers détails du comportement de
<application>libpq</application>.
</para>

<variablelist>
   <varlistentry id="libpq-pqclientencoding">
    <term>
     <function>PQclientEncoding</function>
     <indexterm>
      <primary>PQclientEncoding</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      Renvoie l'encodage client.
      <synopsis>
      int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
      </synopsis>

      Notez qu'il renvoie l'identifiant d'encodage, pas une chaîne symbolique
      telle que <literal>EUC_JP</literal>. Pour convertir un identifiant
      d'encodage en nom, vous pouvez utiliser&nbsp;:

<synopsis>
char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
</synopsis>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="libpq-pqsetclientencoding">
    <term>
     <function>PQsetClientEncoding</function>
     <indexterm>
      <primary>PQsetClientEncoding</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      Configure l'encodage client.
      <synopsis>
      int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
      </synopsis>

      <replaceable>conn</replaceable> est la connexion au serveur, et
      <replaceable>encoding</replaceable> est l'encodage que vous voulez
      utiliser. Si la fonction initialise l'encodage avec succès, elle
      renvoie 0, sinon -1. L'encodage actuel de cette connexion peut être
      déterminé en utilisant <function>PQclientEncoding</function>.
     </para>
    </listitem>
   </varlistentry>

<varlistentry id="libpq-pqseterrorverbosity">
<term><function>PQsetErrorVerbosity</function><indexterm><primary>PQsetErrorVerbosity</primary></indexterm></term>
<listitem>
<para>
Détermine la verbosité des messages renvoyés par
<function>PQerrorMessage</function> et <function>PQresultErrorMessage</function>.
<synopsis>typedef enum
²{
    PQERRORS_TERSE,
    PQERRORS_DEFAULT,
    PQERRORS_VERBOSE
} PGVerbosity;

PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
</synopsis>
<function>PQsetErrorVerbosity</function> initialise le mode de verbosité, renvoyant le
paramétrage précédant de cette connexion. Dans le mode <firstterm>terse</firstterm>, les
messages renvoyés incluent seulement la sévérité, le texte principal et la
position&nbsp;; ceci tiendra normalement sur une seule ligne. Le mode par
défaut produit des messages qui inclut ces champs ainsi que les champs détail,
astuce ou contexte (ils pourraient être sur plusieurs lignes). Le mode
<firstterm>VERBOSE</firstterm> inclut tous les champs disponibles. Modifier la verbosité
n'affecte pas les messages disponibles à partir d'objets
<structname>PGresult</structname> déjà existants, seulement ceux créés après.
</para>
</listitem>
</varlistentry>

<varlistentry id="libpq-pqtrace">
<term><function>PQtrace</function><indexterm><primary>PQtrace</primary></indexterm></term>
<listitem>
<para>
          Active les traces de communication entre client et serveur dans un
          flux fichier de débogage.
<synopsis>void PQtrace(PGconn *conn, FILE *stream);
</synopsis>
</para>
<note>
<para>
Sur Windows, si la bibliothèque <application>libpq</application> et une application sont
compilées avec des options différentes, cet appel de fonction arrêtera 
brutalement l'application car la représentation interne des pointeurs
<literal>FILE</literal> diffère. Spécifiquement, les options multi-threaded/single-threaded
release/debug et static/dynamic devraient être identiques pour la bibliothèque et les
applications qui l'utilisent.
</para>
</note>
</listitem>
</varlistentry>

<varlistentry id="libpq-pquntrace">
<term><function>PQuntrace</function><indexterm><primary>PQuntrace</primary></indexterm></term>
<listitem>
<para>
          Désactive les traces commencées avec <function>PQtrace</function>.
<synopsis>void PQuntrace(PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="libpq-misc">
<title>Fonctions diverses</title>

<para>
Comme toujours, certains fonctions ne sont pas catégorisables.
</para>

  <variablelist>
   <varlistentry id="libpq-pqfreemem">
    <term>
     <function>PQfreemem</function>
     <indexterm>
      <primary>PQfreemem</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      Libère la mémoire allouée par <application>libpq</application>.
      <synopsis>
       void PQfreemem(void *ptr);
      </synopsis>
     </para>

     <para>
      Libère la mémoire allouée par <application>libpq</application>,
      particulièrement <function>PQescapeByteaConn</function>,
      <function>PQescapeBytea</function>, <function>PQunescapeBytea</function>,
      et <function>PQnotifies</function>. Il est particulièrement important
      que cette fonction, plutôt que <function>free()</function>, 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
      <function>free()</function> de la bibliothèque standard.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="libpq-pqconninfofree">
    <term>
     <function>PQconninfoFree</function>
     <indexterm>
      <primary>PQconninfoFree</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      Libère les structures de données allouées par
      <function>PQconndefaults</function> ou
      <function>PQconninfoParse</function>.
      <synopsis>
       void PQconninfoFree(PQconninfoOption *connOptions);
      </synopsis>
     </para>

     <para>
      Un simple appel à <function>PQfreemem</function> ne suffira pas car le
      tableau contient des références à des chaînes supplémentaires.
     </para>
    </listitem>
   </varlistentry>

<varlistentry id="libpq-pqencryptpassword">
<term><function>PQencryptPassword</function><indexterm><primary>PQencryptPassword</primary></indexterm></term>
<listitem>
<para>
Prépare la forme chiffrée du mot de passe <productname>PostgreSQL</productname>.
<synopsis>
char * PQencryptPassword(const char *passwd, const char *user);
</synopsis>
Cette fonction est utilisée par les applications clientes qui souhaitent envoyées
des commandes comme <literal>ALTER USER joe PASSWORD 'passe'</literal>.
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 <function>malloc</function> 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 <function>PQfreemem</function> pour libérer
le résultat une fois terminé.
</para>
</listitem>
</varlistentry>

   <varlistentry id="libpq-pqmakeemptypgresult">
    <term>
     <function>PQmakeEmptyPGresult</function>
     <indexterm>
      <primary>PQmakeEmptyPGresult</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      Construit un objet <structname>PGresult</structname> vide avec la statut
      indiqué.
      <synopsis>
       PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
      </synopsis>
     </para>

     <para>
      C'est une fonction interne de la <application>libpq</application> pour
      allouer et initialiser un objet <structname>PGresult</structname> 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 <parameter>conn</parameter> n'est pas <symbol>NULL</symbol> et que
      <parameter>status</parameter> indique une erreur, le message d'erreur
      actuel de la connexion indiquée est copié dans
      <structname>PGresult</structname>. De plus, si
      <parameter>conn</parameter> n'est pas NULL, toute procédure d'événement
      enregistrée dans la connexion est copiée dans le
      <structname>PGresult</structname>. (Elles n'obtiennent pas d'appels
      <literal>PGEVT_RESULTCREATE</literal>, mais jetez un &oelig;il à
      <function>PQfireResultCreateEvents</function>.)
      Notez que <function>PQclear</function> devra être appelé sur l'objet,
      comme pour un <structname>PGresult</structname> renvoyé par
      <application>libpq</application> lui-même.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="libpq-pqfireresultcreateevents">
    <term>
     <function>PQfireResultCreateEvents</function>
     <indexterm>
      <primary>PQfireResultCreateEvents</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Déclenche un événement <literal>PGEVT_RESULTCREATE</literal> (voir <xref
      linkend="libpq-events"/>) pour chaque procédure d'événement enregistré
      dans l'objet <structname>PGresult</structname>. Renvoit autre chose que
      zéro en cas de succès, zéro si la procédure d'événement échoue.

      <synopsis>
       int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
      </synopsis>
     </para>

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

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

     <para>
      La raison principale pour séparer cette fonction de
      <function>PQmakeEmptyPGResult</function> est qu'il est souvent approprié
      de créer un <structname>PGresult</structname> et de le remplir avec des
      données avant d'appeler les procédures d'événement.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="libpq-pqcopyresult">
    <term>
     <function>PQcopyResult</function>
     <indexterm>
      <primary>PQcopyResult</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      Fait une copie de l'objet <structname>PGresult</structname>. La copie
      n'est liée en aucune façon au résultat source et
      <function>PQclear</function> doit être appelée dans que la copie n'est
      plus nécessaire. Si la fonction échoue, <symbol>NULL</symbol> est renvoyé.

      <synopsis>
       PGresult *PQcopyResult(const PGresult *src, int flags);
      </synopsis>
     </para>

     <para>
      Cela n'a pas pour but de faire une copie exacte. Le résultat renvoyé a
      toujours le statut <literal>PGRES_TUPLES_OK</literal>, et ne copie aucun
      message d'erreur dans la source. (Néanmoins, il copie la chaîne de statut
      de commande.) L'argument <parameter>flags</parameter> détermine le reste
      à copier. C'est un OR bit à bit de plusieurs drapeaux.
      <literal>PG_COPYRES_ATTRS</literal> indique la copie des attributs du
      résultat source (définition des colonnes).
      <literal>PG_COPYRES_TUPLES</literal> indique la copie des lignes du
      résultat source. (Cela implique de copier aussi les attributs.)
      <literal>PG_COPYRES_NOTICEHOOKS</literal> indique la copie des
      gestionnaires de notification du résultat source.
      <literal>PG_COPYRES_EVENTS</literal> 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.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="libpq-pqsetresultattrs">
    <term>
     <function>PQsetResultAttrs</function>
     <indexterm>
      <primary>PQsetResultAttrs</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      Initialise les attributs d'un objet <structname>PGresult</structname>.
      <synopsis>
       int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
      </synopsis>
     </para>

     <para>
      Les <parameter>attDescs</parameter> fournis sont copiés dans le résultat.
      Si le pointeur <parameter>attDescs</parameter> est <symbol>NULL</symbol> ou si
      <parameter>numAttributes</parameter> est inférieur à 1, la requête est
      ignorée et la fonction réussit. Si <parameter>res</parameter> 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.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="libpq-pqsetvalue">
    <term>
     <function>PQsetvalue</function>
     <indexterm>
      <primary>PQsetvalue</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      Initialise la valeur d'un champ d'une ligne d'un objet
      <structname>PGresult</structname>.
      <synopsis>
       int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
      </synopsis>
     </para>

     <para>
      La fonction fera automatiquement grossir le tableau de lignes internes des
      résultats, si nécessaire. Néanmoins, l'argument
      <parameter>tup_num</parameter> doit être inférieur ou égal à
      <function>PQntuples</function>, 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 à <parameter>field_num</parameter> existe déjà, elle
      sera écrasée. Si <parameter>len</parameter> vaut 1 ou
      si <parameter>value</parameter> est <literal>NULL</literal>, la valeur
      du champ sera configurée à la valeur SQL <literal>NULL</literal>.
      <parameter>value</parameter> 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.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="libpq-pqresultalloc">
    <term>
     <function>PQresultAlloc</function>
     <indexterm>
      <primary>PQresultAlloc</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      Alloue un stockage supplémentaire pour un objet
      <structname>PGresult</structname>.
      <synopsis>
       void *PQresultAlloc(PGresult *res, size_t nBytes);
      </synopsis>
     </para>

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

   <varlistentry id="libpq-pqlibversion">
    <term>
     <function>PQlibVersion</function>
     <indexterm>
      <primary>PQlibVersion</primary>
      <seealso>PQserverVersion</seealso>
     </indexterm>
    </term>

    <listitem>
     <para>
      Renvoie la version de <productname>libpq</productname> en cours
      d'utilisation.
<synopsis>
int PQlibVersion(void);
</synopsis>
     </para>

     <para>
      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 <function>PQconnectdb</function> ou si
      la sortie <literal>hex</literal> du type <type>bytea</type>
      ajoutée par PostgreSQL 9.0 est supportée.
     </para>

     <para>
      Le nombre est formé par conversion des numéros majeur, mineur et
      de révision en nombre à deux chiffres et en les concaténant les
      uns aux autres. Par exemple, la version 9.1 sera renvoyée en tant
      que 90100, alors que la version 9.1.2 sera renvoyée en tant que
      90102 (Les zéros en début de chiffres ne sont pas affichées).
     </para>

     <note>
      <para>
       Cette fonction apparaît en version 9.1 de
       <productname>PostgreSQL</productname>, donc elle ne peut pas être
       utilisée pour détecter des fonctionnalités des versions
       précédentes car l'édition de lien créera une dépendance sur la
       version 9.1.
      </para>
     </note>
    </listitem>
   </varlistentry>

</variablelist>

</sect1>

<sect1 id="libpq-notice-processing">
<title>Traitement des messages</title>

<indexterm zone="libpq-notice-processing">
 <primary>traitement des messages</primary>
 <secondary>dans libpq</secondary>
</indexterm>

<para>
Les messages de note et d'avertissement générés par le serveur ne sont pas
renvoyés par les fonctions d'exécution des requêtes car elles n'impliquent pas
d'échec dans la requête. À la place, elles sont passées à la fonction de
gestion des messages et l'exécution continue normalement après le retour du
gestionnaire. La fonction par défaut de gestion des messages affiche le message
sur <filename>stderr</filename> mais l'application peut surcharger ce
comportement en proposant sa propre fonction de gestion.
</para>

<para>
Pour des raisons historiques, il existe deux niveaux de gestion de messages,
appelés la réception des messages et le traitement. Pour la réception, le
comportement par défaut est de formater le message et de passer une chaîne au
traitement pour affichage. Néanmoins, une application qui choisit de
fournir son propre receveur de messages ignorera typiquement la couche d'envoi
de messages et effectuera tout le travail au niveau du receveur.
</para>

<para>
La fonction <function>PQsetNoticeReceiver</function>
<indexterm><primary>receveur
de message</primary></indexterm><indexterm><primary>PQsetNoticeReceiver</primary></indexterm>
initialise ou examine le receveur actuel de messages pour un objet de
connexion. De la même façon, <function>PQsetNoticeProcessor</function>
<indexterm><primary>traiteur de messages</primary></indexterm><indexterm><primary>
PQsetNoticeProcessor</primary></indexterm> initialise ou examine l'émetteur actuel de messages.

<synopsis>typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);

PQnoticeReceiver
PQsetNoticeReceiver(PGconn *conn,
                    PQnoticeReceiver proc,
                    void *arg);

typedef void (*PQnoticeProcessor) (void *arg, const char *message);

PQnoticeProcessor
PQsetNoticeProcessor(PGconn *conn,
                     PQnoticeProcessor proc,
                     void *arg);
</synopsis>

Chacune de ces fonctions reçoit le pointeur de fonction du précédent receveur
ou émetteur de messages et configure la nouvelle valeur. Si vous fournissez un
pointeur de fonction nul, aucune action n'est réalisée mais le pointeur actuel
est renvoyé.
</para>

<para>
Quand un message de note ou d'avertissement est reçu du serveur ou généré de
façon interne par <application>libpq</application>, la fonction de réception du
message est appelée. Le message lui est passé sous la forme d'un
<structname>PGresult</structname> <symbol>PGRES_NONFATAL_ERROR</symbol> (ceci
permet au receveur d'extraire les champs individuels en utilisant
<function>PQresultErrorField</function> ou le message complet préformaté en utilisant
<function>PQresultErrorMessage</function>). Le même pointeur void passé à
<function>PQsetNoticeReceiver</function> est aussi renvoyé (ce pointeur peut
être utilisé pour accéder à un état spécifique de l'application si nécessaire).
</para>

<para>
Le receveur de messages par défaut extrait simplement le message (en utilisant
<function>PQresultErrorMessage</function>) et le passe au système de traitement du
message.
</para>

<para>
Ce dernier est responsable de la gestion du message de note ou d'avertissement
donné au format texte. La chaîne texte du message est passée avec un retour
chariot supplémentaire, plus un pointeur sur void identique à celui passé à
<function>PQsetNoticeProcessor</function> (ce pointeur est utilisé pour
accéder à un état spécifique de l'application si nécessaire).
</para>

<para>
Le traitement des messages par défaut est simplement
<programlisting>static void
defaultNoticeProcessor(void * arg, const char * message)
{
    fprintf(stderr, "%s", message);
}
</programlisting>
</para>

<para>
Une fois que vous avez initialisé un receveur ou une fonction de traitement des
messages, vous devez vous attendre à ce que la fonction soit appelée aussi
longtemps que l'objet <structname>PGconn</structname> ou qu'un objet
<structname>PGresult</structname> réalisé à partir de celle-ci existent. À la création
d'un <structname>PGresult</structname>, les pointeurs de gestion actuels de
<structname>PGconn</structname> sont copiés dans <structname>PGresult</structname> pour une
utilisation possible par des fonctions comme <function>PQgetvalue</function>.
</para>

 </sect1>

 <sect1 id="libpq-events">
  <title>Système d'événements</title>

  <para>
   Le système d'événements de <application>libpq</application> est conçu pour
   notifier les gestionnaires d'événements enregistrés de l'arrivée d'événements
   intéressants de la <application>libpq</application>, comme par exemple la
   création ou la destruction d'objets <structname>PGconn</structname> et
   <structname>PGresult</structname>. Un cas d'utilisation principal est de
   permettre aux applications d'associer leur propres données avec un
   <structname>PGconn</structname> ou un <structname>PGresult</structname> et
   de s'assurer que les données soient libérées au bon moment.
  </para>

  <para>
   Chaque gestionnaire d'événement enregistré est associé avec deux types de
   données, connus par <application>libpq</application> comme des pointeurs
   opaques, c'est-à-dire <literal>void *</literal>. Il existe un pointeur
   <firstterm>passthrough</firstterm> fournie par l'application quand le
   gestionnaire d'événements est enregistré avec un <structname>PGconn</structname>.
   Le pointeur passthrough ne change jamais pendant toute la durée du
   <structname>PGconn</structname> et des <structname>PGresult</structname>
   générés grâce à lui&nbsp;; donc s'il est utilisé, il doit pointer vers
   des données vivantes. De plus, il existe une pointeur de <firstterm>données
   instanciées</firstterm>, qui commence à NULL dans chaque objet
   <structname>PGconn</structname> et <structname>PGresult</structname>. Ce
   pointeur peut être manipulé en utilisant les fonctions
   <function>PQinstanceData</function>, <function>PQsetInstanceData</function>,
   <function>PQresultInstanceData</function> et
   <function>PQsetResultInstanceData</function>. Notez que, contrairement au
   pointeur passthrough, les <structname>PGresult</structname> n'héritent pas
   automatiquement des données instanciées d'un
   <structname>PGconn</structname>. <application>libpq</application> ne sait
   pas vers quoi pointent les pointeurs passthrough et de données instanciées,
   et n'essaiera hamais de les libérer &mdash; cela tient de la responsabilité
   du gestionnaire d'événements.
  </para>

  <sect2 id="libpq-events-types">
   <title>Types d'événements</title>

   <para>
    La variable <literal>PGEventId</literal> de type enum précise tous les types
    d'événements gérés par le système d'événements. Toutes ces valeurs ont des
    noms commençant avec <literal>PGEVT</literal>. Pour chaque type d'événement,
    il existe une structure d'informations sur l'événement, précisant les
    paramètres passés aux gestionnaires d'événement. Les types d'événements
    sont&nbsp;:
   </para>

   <variablelist>
    <varlistentry id="libpq-pgevt-register">
     <term><literal>PGEVT_REGISTER</literal></term>
     <listitem>
      <para>
       L'événement d'enregistrement survient quand <function>PQregisterEventProc</function>
       est appelé.; C'est le moment idéal pour initialiser toute structure
       <literal>instanceData</literal> qu'une procédure d'événement pourrait avoir
       besoin. Seul un événement d'enregistrement sera déclenché par gestionnaire
       d'évévenement sur une connexion. Si la procédure échoue, l'enregistrement
       est annulé.

      <synopsis>
typedef struct
{
    PGconn *conn;
} PGEventRegister;
      </synopsis>

       Quand un événement <literal>PGEVT_REGISTER</literal> est reçu, le pointeur
       <parameter>evtInfo</parameter> doit être converti en un
       <structname>PGEventRegister *</structname>. Cette structure contient un
       <structname>PGconn</structname> qui doit être dans le statut
       <literal>CONNECTION_OK</literal>&nbsp;; garanti si
       <function>PQregisterEventProc</function> est appelé juste après avoir
       obtenu un bon <structname>PGconn</structname>. Lorsqu'elle renvoit
       un code d'erreur, le nettoyage doit être réalisé car aucun événement
       <literal>PGEVT_CONNDESTROY</literal> ne sera envoyé.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pgevt-connreset">
     <term><literal>PGEVT_CONNRESET</literal></term>
     <listitem>
      <para>
       L'événement de réinitialisation de connexion est déclenché après un
       <function>PQreset</function> ou un <function>PQresetPoll</function>.  Dans
       les deux cas, l'événement est seulement déclenché si la ré-initialisation
       est réussie. Si la procédure échoue, la réinitialisation de connexion
       échouera&nbsp;; la structure <structname>PGconn</structname> est placée
       dans le statut <literal>CONNECTION_BAD</literal> et
       <function>PQresetPoll</function> renverra
       <literal>PGRES_POLLING_FAILED</literal>.

      <synopsis>
typedef struct
{
    PGconn *conn;
} PGEventConnReset;
      </synopsis>

       Quand un événement <literal>PGEVT_CONNRESET</literal> est reçu, le
       pointeur <parameter>evtInfo</parameter> doit être converti en un
       <structname>PGEventConnReset *</structname>. Bien que le
       <structname>PGconn</structname> a été réinitialisé, toutes les données
       de l'événement restent inchangées. Cet événement doit être utilisé pour
       ré-initialiser/recharger/re-requêter tout <literal>instanceData</literal>
       associé. Notez que même si la procédure d'événement échoue à traiter
       <literal>PGEVT_CONNRESET</literal>, elle recevra toujours un événement
       <literal>PGEVT_CONNDESTROY</literal> à la fermeture de la connexion.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pgevt-conndestroy">
     <term><literal>PGEVT_CONNDESTROY</literal></term>
     <listitem>
      <para>
       L'événement de destruction de la connexion est déclenchée en réponse
       à <function>PQfinish</function>. Il est de la responsabilité de la
       procédure de l'événement de nettoyer proprement ses données car
       libpq n'a pas les moyens de gérer cette mémoire. Un échec du
       nettoyage amènera des pertes mémoire.

      <synopsis>
typedef struct
{
    PGconn *conn;
} PGEventConnDestroy;
      </synopsis>

       Quand un événement <literal>PGEVT_CONNDESTROY</literal> est reçu, le
       pointeur <parameter>evtInfo</parameter> doit être converti en un
       <structname>PGEventConnDestroy *</structname>. Cet événement est
       déclenché avant que <function>PQfinish</function> ne réalise d'autres
       nettoyages. La valeur de retour de la procédure est ignorée car il
       n'y a aucun moyen d'indiquer un échec de <function>PQfinish</function>.
       De plus, un échec de la procédure ne doit pas annuler le nettoyage de
       la mémoire non désirée.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pgevt-resultcreate">
     <term><literal>PGEVT_RESULTCREATE</literal></term>
     <listitem>
      <para>
       L'événement de création de résultat est déclenché en réponse à
       l'utilisation d'une fonction d'exécution d'une requête, par exemple
       <function>PQgetResult</function>. Cet événement sera déclenché seulement
       après la création réussie du résultat.

      <synopsis>
typedef struct
{
    PGconn *conn;
    PGresult *result;
} PGEventResultCreate;
      </synopsis>

       Quand un événement <literal>PGEVT_RESULTCREATE</literal> est reçu, le
       pointeur <parameter>evtInfo</parameter> doit être converti en un
       <structname>PGEventResultCreate *</structname>. Le paramètre
       <parameter>conn</parameter> est la connexion utilisée pour générer le
       résultat. C'est le moment idéal pour initialiser tout
       <literal>instanceData</literal> qui doit être associé avec le résultat.
       Si la procédure échoue, le résultat sera effacé et l'échec sera propagé.
       Le procédure d'événement ne doit pas tenter un <function>PQclear</function>
       sur l'objet résultat lui-même. Lors du renvoi d'un code d'échec, tout le
       nettoyage doit être fait car aucun événement
       <literal>PGEVT_RESULTDESTROY</literal> ne sera envoyé.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pgevt-resultcopy">
     <term><literal>PGEVT_RESULTCOPY</literal></term>
     <listitem>
      <para>
       L'événement de copie du résultat est déclenché en réponse à un
       <function>PQcopyResult</function>. Cet événement se déclenchera
       seulement une fois la copie terminée. Seules les procédures qui ont
       gérées avec succès l'événement <literal>PGEVT_RESULTCREATE</literal>
       ou <literal>PGEVT_RESULTCOPY</literal> pour le résultat source recevront
       les événements <literal>PGEVT_RESULTCOPY</literal>.

      <synopsis>
typedef struct
{
    const PGresult *src;
    PGresult *dest;
} PGEventResultCopy;
      </synopsis>

       Quand un événement <literal>PGEVT_RESULTCOPY</literal> est reçu, le
       pointeur <parameter>evtInfo</parameter> doit être converti en un
       <structname>PGEventResultCopy *</structname>. Le résultat
       résultat <parameter>src</parameter> correspond à ce qui a été copié
       alors que le résultat <parameter>dest</parameter> correspond à la
       destination. Cet événement peut être utilisé pour fournir une copie
       complète de <literal>instanceData</literal>, ce que 
       <literal>PQcopyResult</literal> ne peut pas faire. Si la procédure
       échoue, l'opération complète de copie échouera et le résultat
       <parameter>dest</parameter> sera effacé. Au renvoi d'un code d'échec,
       tout le nettoyage doit être réalisé car aucun événement
       <literal>PGEVT_RESULTDESTROY</literal> ne sera envoyé pour le résultat
       de destination.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pgevt-resultdestroy">
     <term><literal>PGEVT_RESULTDESTROY</literal></term>
     <listitem>
      <para>
       L'événement de destruction de résultat est déclenché en réponse à la
       fonction <function>PQclear</function>. C'est de la responsabilité de
       l'événement de nettoyer proprement les données de l'événement car libpq
       n'a pas cette capacité en matière de gestion de mémoire. Si le nettoyage
       échoue, cela sera la cause de pertes mémoire.

      <synopsis>
typedef struct
{
    PGresult *result;
} PGEventResultDestroy;
      </synopsis>

       Quand un événement <literal>PGEVT_RESULTDESTROY</literal> est reçu, le
       pointeur <parameter>evtInfo</parameter> doit être converti en un
       <structname>PGEventResultDestroy *</structname>. Cet événement est
       déclenché avant que <function>PQclear</function> ne puisse faire de
       nettoyage. La valeur de retour de la procédure est ignorée car il
       n'existe aucun moyen d'indiquer un échec à partir de
       <function>PQclear</function>. De plus, un échec de la procédure ne doit
       pas annuler le nettoyage de la mémoire non désirée.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 id="libpq-events-proc">
   <title>Procédure de rappel de l'événement</title>

   <variablelist>
    <varlistentry id="libpq-pgeventproc">
     <term>
      <literal>PGEventProc</literal>
      <indexterm>
       <primary>PGEventProc</primary>
      </indexterm>
     </term>

     <listitem>
      <para>
       <literal>PGEventProc</literal> est une définition de type pour un pointeur
       vers une procédure d'événement, c'est-à-dire la fonction utilisateur
       appelée pour les événements de la libpq. La signature d'une telle fonction
       doit être&nbsp;:

      <synopsis>
int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)
      </synopsis>

       Le paramètre <parameter>evtId</parameter> indique l'événement
       <literal>PGEVT</literal> qui est survenu. Le pointeur
       <parameter>evtInfo</parameter> doit être converti vers le type
       de structure approprié pour obtenir plus d'informations sur l'événement.
       Le paramètre <parameter>passThrough</parameter> est le pointeur fourni
       à <function>PQregisterEventProc</function> quand la procédure de
       l'événement a été enregistrée. La fonction doit renvoyer une valeur
       différente de zéro en cas de succès et zéro en cas d'échec.
      </para>

      <para>
       Une procédure d'événement particulière peut être enregistrée une fois
       seulement pour un <structname>PGconn</structname>. Ceci est dû au fait
       que l'adresse de la procédure est utilisée comme clé de recherche pour
       identifier les données instanciées associées.
      </para>

      <caution>
       <para>
        Sur Windows, les fonctions peuvent avoir deux adresses différentes&nbsp;:
	une visible de l'extérieur de la DLL et une visible de l'intérieur. Il
	faut faire attention que seule une de ces adresses est utilisée avec les
	fonctions d'événement de la <application>libpq</application>, sinon une
	confusion en résultera. La règle la plus simple pour écrire du code qui
	fonctionnera est de s'assurer que les procédures d'événements sont
	déclarées <literal>static</literal>. Si l'adresse de la procédure doit
	être disponible en dehors de son propre fichier source,  il faut exposer
	une fonction séparée pour renvoyer l'adresse.
       </para>
      </caution>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 id="libpq-events-funcs">
   <title>Fonctions de support des événements</title>

    <variablelist>
    <varlistentry id="libpq-pqregistereventproc">
     <term>
      <function>PQregisterEventProc</function>
      <indexterm>
       <primary>PQregisterEventProc</primary>
      </indexterm>
     </term>

     <listitem>
      <para>
       Enregistre une procédure de rappel pour les événements avec libpq.

       <synopsis>
        int PQregisterEventProc(PGconn *conn, PGEventProc proc,
                                const char *name, void *passThrough);
       </synopsis>
      </para>

      <para>
       Une procédure d'évenement doit être enregistré une fois pour chaque
       <structname>PGconn</structname> pour lequel vous souhaitez recevoir des
       événements. Il n'existe pas de limites, autre que la mémoire, sur le
       nombre de procédures d'événements qui peuvent être enregistrées avec
       une connexion. La fonction renvoie une valeur différente de zéro en cas
       de succès, et zéro en cas d'échec.
      </para>

      <para>
       L'argument <parameter>proc</parameter> sera appelé quand se déclenchera
       un événement libpq. Son adresse mémoire est aussi utilisée pour rechercher
       <literal>instanceData</literal>. L'argument <parameter>name</parameter>
       est utilisé pour faire référence à la procédure d'évenement dans les
       messages d'erreur. Cette valeur ne peut pas être <symbol>NULL</symbol> ou une chaîne de
       longueur nulle. La chaîne du nom est copiée dans
       <structname>PGconn</structname>, donc ce qui est passé n'a pas besoin de
       durer longtemps. Le pointeur <parameter>passThrough</parameter> est
       passé à <parameter>proc</parameter> à chaque arrivée d'un événement. Cet
       argument peut être <symbol>NULL</symbol>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqsetinstancedata">
     <term>
      <function>PQsetInstanceData</function>
      <indexterm>
       <primary>PQsetInstanceData</primary>
      </indexterm>
     </term>
     <listitem>
      <para>
       Initialise <literal>instanceData</literal> de la connexion pour la
       procédure <parameter>proc</parameter> avec <parameter>data</parameter>.
       Cette fonction renvoit zéro en cas d'échec et autre chose en cas de réussite.
       (L'échec est seulement possible si <parameter>proc</parameter> n'a pas été correctement
       enregistré dans le résultat.)

       <synopsis>
        int PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data);
       </synopsis>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqinstancedata">
     <term>
      <function>PQinstanceData</function>
      <indexterm>
       <primary>PQinstanceData</primary>
      </indexterm>
     </term>
     <listitem>
      <para>
       Renvoie le <literal>instanceData</literal> de la connexion associée
       avec <parameter>connproc</parameter> ou <symbol>NULL</symbol> s'il
       n'y en a pas.

       <synopsis>
        void *PQinstanceData(const PGconn *conn, PGEventProc proc);
       </synopsis>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqresultsetinstancedata">
     <term>
      <function>PQresultSetInstanceData</function>
      <indexterm>
       <primary>PQresultSetInstanceData</primary>
      </indexterm>
     </term>
     <listitem>
      <para>
       Initialise le <literal>instanceData</literal> du résultat pour la
       procédure <parameter>proc</parameter> avec <parameter>data</parameter>.
       Cette fonction renvoit zéro en cas d'échec et autre chose en cas de réussite.
       (L'échec est seulement possible si proc n'a pas été correctement
       enregistré dans le résultat.)

       <synopsis>
        int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data);
       </synopsis>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqresultinstancedata">
     <term>
      <function>PQresultInstanceData</function>
      <indexterm>
       <primary>PQresultInstanceData</primary>
      </indexterm>
     </term>
     <listitem>
      <para>
       Renvoie le <literal>instanceData</literal> du résultat associé avec
       <parameter>proc</parameter> ou <symbol>NULL</symbol> s'il n'y
       en a pas.

       <synopsis>
        void *PQresultInstanceData(const PGresult *res, PGEventProc proc);
       </synopsis>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 id="libpq-events-example">
   <title>Exemple d'un événement</title>

   <para>
    Voici un exemple d'une gestion de données privées associée aux connexions
    et aux résultats de la libpq.
   </para>

   <programlisting>
<![CDATA[
/* en-tête nécssaire pour les événements de la libpq (note : inclut libpq-fe.h) */
#include <libpq-events.h>

/* la donnée instanciée : instanceData */
typedef struct
{
    int n;
    char *str;
} mydata;

/* PGEventProc */
static int myEventProc(PGEventId evtId, void *evtInfo, void *passThrough);

int
main(void)
{
    mydata *data;
    PGresult *res;
    PGconn *conn = PQconnectdb("dbname = postgres");

    if (PQstatus(conn) != CONNECTION_OK)
    {
        fprintf(stderr, "Connection to database failed: %s",
                PQerrorMessage(conn));
        PQfinish(conn);
        return 1;
    }

    /* appelée une fois pour toute connexion qui doit recevoir des événements.
     * Envoit un PGEVT_REGISTER à myEventProc.
     */
    if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL))
    {
        fprintf(stderr, "Cannot register PGEventProc\n");
        PQfinish(conn);
        return 1;
    }

    /* la connexion instanceData est disponible */
    data = PQinstanceData(conn, myEventProc);

    /* Envoit un PGEVT_RESULTCREATE à myEventProc */
    res = PQexec(conn, "SELECT 1 + 1");

    /* le résultat instanceData est disponible */
    data = PQresultInstanceData(res, myEventProc);

    /* Si PG_COPYRES_EVENTS est utilisé, envoit un PGEVT_RESULTCOPY à myEventProc */
    res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS);

    /* le résultat instanceData est disponible si PG_COPYRES_EVENTS a été
     * utilisé lors de l'appel à PQcopyResult.
     */
    data = PQresultInstanceData(res_copy, myEventProc);

    /* Les deux fonctions de nettoyage envoient PGEVT_RESULTDESTROY à myEventProc */
    PQclear(res);
    PQclear(res_copy);

    /* Envoit un PGEVT_CONNDESTROY à myEventProc */
    PQfinish(conn);

    return 0;
}

static int
myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
{
    switch (evtId)
    {
        case PGEVT_REGISTER:
        {
            PGEventRegister *e = (PGEventRegister *)evtInfo;
            mydata *data = get_mydata(e->conn);

            /* associe des données spécifiques de l'application avec la connexion */
            PQsetInstanceData(e->conn, myEventProc, data);
            break;
        }

        case PGEVT_CONNRESET:
        {
            PGEventConnReset *e = (PGEventConnReset *)evtInfo;
            mydata *data = PQinstanceData(e->conn, myEventProc);

            if (data)
              memset(data, 0, sizeof(mydata));
            break;
        }

        case PGEVT_CONNDESTROY:
        {
            PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo;
            mydata *data = PQinstanceData(e->conn, myEventProc);

            /* libère les données instanciées car la connexion est en cours de destruction */
            if (data)
              free_mydata(data);
            break;
        }

        case PGEVT_RESULTCREATE:
        {
            PGEventResultCreate *e = (PGEventResultCreate *)evtInfo;
            mydata *conn_data = PQinstanceData(e->conn, myEventProc);
            mydata *res_data = dup_mydata(conn_data);

            /* associe des données spécifiques à l'application avec les résultats (copié de la connexion) */
            PQsetResultInstanceData(e->result, myEventProc, res_data);
            break;
        }

        case PGEVT_RESULTCOPY:
        {
            PGEventResultCopy *e = (PGEventResultCopy *)evtInfo;
            mydata *src_data = PQresultInstanceData(e->src, myEventProc);
            mydata *dest_data = dup_mydata(src_data);

            /* associe des données spécifiques à l'application avec les résultats (copié d'un résultat) */
            PQsetResultInstanceData(e->dest, myEventProc, dest_data);
            break;
        }

        case PGEVT_RESULTDESTROY:
        {
            PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo;
            mydata *data = PQresultInstanceData(e->result, myEventProc);

            /* libère les données instanciées car le résultat est en cours de destruction */
            if (data)
              free_mydata(data);
            break;
        }

        /* unknown event id, just return TRUE. */
        default:
            break;
    }

    return TRUE; /* event processing succeeded */
}
]]>
</programlisting>
  </sect2>
 </sect1>

<sect1 id="libpq-envars">
<title>Variables d'environnement</title>

<indexterm zone="libpq-envars">
 <primary>variable d'environnement</primary>
</indexterm>

<para>
Les variables d'environnement suivantes peuvent être utilisées pour
sélectionner des valeurs par défaut pour les paramètres de connexion, valeurs
qui seront utilisées par <function>PQconnectdb</function>, <function>PQsetdbLogin</function> et
<function>PQsetdb</function> si aucune valeur n'est directement précisée par
le code d'appel. Elles sont utiles pour éviter de coder en dur les
informations de connexion à la base de données dans les applications
clients, par exemple.

<itemizedlist>
<listitem>
<para>
<indexterm>
 <primary><envar>PGHOST</envar></primary>
</indexterm>
<envar>PGHOST</envar> se comporte de la même façon que le paramètre de
configuration <xref linkend="libpq-connect-host"/>.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGHOSTADDR</envar></primary>
</indexterm>
<envar>PGHOSTADDR</envar> se comporte de la même façon que le paramètre de
configuration <xref linkend="libpq-connect-hostaddr"/>.
Elle peut être initialisée avec <envar>PGHOST</envar> pour éviter
la surcharge des recherches DNS.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGPORT</envar></primary>
</indexterm>
<envar>PGPORT</envar> se comporte de la même façon que le paramètre de
configuration <xref linkend="libpq-connect-port"/>.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGDATABASE</envar></primary>
</indexterm>
<envar>PGDATABASE</envar> se comporte de la même façon que le paramètre de
configuration <xref linkend="libpq-connect-dbname"/>.
      </para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGUSER</envar></primary>
</indexterm>
<envar>PGUSER</envar> se comporte de la même façon que le paramètre de
configuration <xref linkend="libpq-connect-user"/>.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGPASSWORD</envar></primary>
</indexterm>
<envar>PGPASSWORD</envar> se comporte de la même façon que le paramètre de
configuration <xref linkend="libpq-connect-password"/>. L'utilisation de cette variable
d'environnement n'est pas recommandée pour des raisons de sécurité (certains
systèmes d'exploitation autorisent les utilisateurs autres que root à voir les
variables d'environnement du processus via <application>ps</application>)&nbsp;; à la
place, considérez l'utilisation du fichier <filename>~/.pgpass</filename> (voir la <xref
linkend="libpq-pgpass"/>).
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGPASSFILE</envar></primary>
</indexterm>
<envar>PGPASSFILE</envar>
spécifie le nom du fichier de mot de passe à utiliser pour les recherches.
Sa valeur par défaut est <filename>~/.pgpass</filename> (voir la <xref
linkend="libpq-pgpass"/>).
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGSERVICE</envar></primary>
</indexterm>
<envar>PGSERVICE</envar> se comporte de la même façon que le paramètre de
configuration <xref linkend="libpq-connect-service"/>.
</para>
</listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGSERVICEFILE</envar></primary>
      </indexterm>
      <envar>PGSERVICEFILE</envar> indique le nom du fichier service de
      connexion par utilisateur. S'il n'est pas configuré, sa valeur par
      défaut est <filename>~/.pg_service.conf</filename>
      (voir <xref linkend="libpq-pgservice"/>).
     </para>
    </listitem>

<listitem>
<para>
<indexterm>
 <primary><envar>PGREALM</envar></primary>
</indexterm>
<envar>PGREALM</envar> initialise le domaine Kerberos à utiliser avec
<productname>PostgreSQL</productname> s'il est différent du domaine local. Si
<envar>PGREALM</envar> est initialisé, les applications
<application>libpq</application> tenteront une authentification avec les
serveurs de ce domaine et utiliseront les fichiers tickets séparés pour éviter
les conflits avec les fichiers tickets locaux. Cette variable d'environnement
est seulement utilisée si l'authentification Kerberos est sélectionnée par le
serveur.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGOPTIONS</envar></primary>
</indexterm>
<envar>PGOPTIONS</envar> se comporte de la même façon que le paramètre de
configuration <xref linkend="libpq-connect-options"/>.
</para>
</listitem>
    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGAPPNAME</envar></primary>
      </indexterm>
      <envar>PGAPPNAME</envar> se comporte de la même façon que le paramètre
      de connexion <xref linkend="libpq-connect-application-name"/>.
     </para>
    </listitem>

<listitem>
<para>
<indexterm>
 <primary><envar>PGSSLMODE</envar></primary>
</indexterm>
<envar>PGSSLMODE</envar> se comporte de la même façon que le paramètre de
configuration <xref linkend="libpq-connect-sslmode"/>.
</para>
</listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGREQUIRESSL</envar></primary>
      </indexterm>
      <envar>PGREQUIRESSL</envar> se comporte de la même façon que le paramètre
      de configuration <xref linkend="libpq-connect-requiressl"/>.
     </para>
    </listitem>
    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGSSLKEY</envar></primary>
      </indexterm>
      <envar>PGSSLKEY</envar> spécifie le jeton matériel qui stocke la clé
      secrète pour le certificat client. La valeur de cette variable doit
      consister d'un nom de moteur séparé par une virgule (les moteurs sont
      les modules chargeables d'<productname>OpenSSL</productname>) et un
      identifiant de clé spécifique au moteur. Si elle n'est pas
      configurée, la clé secrète doit être conservée dans un fichier.
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGSSLCOMPRESSION</envar></primary>
      </indexterm>
      <envar>PGSSLCOMPRESSION</envar> se comporte de la même façon que le
      paramètre de connexion <xref linkend="libpq-connect-sslcompression"/>.
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGSSLCERT</envar></primary>
      </indexterm>
      <envar>PGSSLCERT</envar> se comporte de la même façon que le paramètre de
      configuration <xref linkend="libpq-connect-sslcert"/>.
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGSSLKEY</envar></primary>
      </indexterm>
      <envar>PGSSLKEY</envar> se comporte de la même façon que le paramètre de
      configuration <xref linkend="libpq-connect-sslkey"/>.
     </para>
    </listitem>
    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGSSLROOTCERT</envar></primary>
      </indexterm>
      <envar>PGSSLROOTCERT</envar> se comporte de la même façon que le paramètre
      de configuration <xref linkend="libpq-connect-sslrootcert"/>.
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGSSLCRL</envar></primary>
      </indexterm>
      <envar>PGSSLCRL</envar> se comporte de la même façon que le paramètre de
      configuration <xref linkend="libpq-connect-sslcrl"/>.
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGREQUIREPEER</envar></primary>
      </indexterm>
      <envar>PGREQUIREPEER</envar> se comporte de la même façon que le
      paramètre de connexion <xref linkend="libpq-connect-requirepeer"/>.
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGKRBSRVNAME</envar></primary>
      </indexterm>
      <envar>PGKRBSRVNAME</envar> se comporte de la même façon que le paramètre
      de configuration <xref linkend="libpq-connect-krbsrvname"/>.
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGGSSLIB</envar></primary>
      </indexterm>
      <envar>PGGSSLIB</envar> se comporte de la même façon que le paramètre de
      configuration <xref linkend="libpq-connect-gsslib"/>.
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGCONNECT_TIMEOUT</envar></primary>
      </indexterm>
      <envar>PGCONNECT_TIMEOUT</envar> se comporte de la même façon que le
      paramètre de configuration <xref linkend="libpq-connect-connect-timeout"/>.
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGCLIENTENCODING</envar></primary>
      </indexterm>
      <envar>PGCLIENTENCODING</envar> se comporte de la même façon que
      le paramètre de connexion <xref
      linkend="libpq-connect-client-encoding"/>.
     </para>
    </listitem>
</itemizedlist>
</para>

<para>
Les variables d'environnement par défaut peuvent être utilisées pour
spécifier le comportement par défaut de chaque session
<productname>PostgreSQL</productname> (voir aussi les commandes
<xref linkend="sql-alterrole"/> et
<xref linkend="sql-alterdatabase"/>
pour des moyens d'initialiser le
comportement par défaut sur des bases par utilisateur ou par bases de données).

<itemizedlist>
<listitem>
<para>
<indexterm>
 <primary><envar>PGDATESTYLE</envar></primary>
</indexterm>
<envar>PGDATESTYLE</envar>
initialise le style par défaut de la représentation de la date et de l'heure
(équivalent à <literal>SET datestyle TO ...</literal>).
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGTZ</envar></primary>
</indexterm>
<envar>PGTZ</envar> initialise le fuseau horaire par défaut
(équivalent à <literal>SET timezone TO ...</literal>).
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGGEQO</envar></primary>
</indexterm>
<envar>PGGEQO</envar>
initialise le mode par défaut pour l'optimiseur générique de requêtes
(équivalent à <literal>SET geqo TO ...</literal>).
</para>
</listitem>
</itemizedlist>

Référez-vous à la commande <acronym>SQL</acronym>
<xref linkend="sql-set"/> pour
plus d'informations sur des valeurs correctes pour ces variables
d'environnement.
</para>

<para>
  Les variables d'environnement suivantes déterminent le comportement interne
  de <application>libpq</application>&nbsp;; elles surchargent les valeurs
  internes par défaut.
  
  <itemizedlist>
    <listitem>
      <para>
        <indexterm>
          <primary><envar>PGSYSCONFDIR</envar></primary>
        </indexterm>
        <envar>PGSYSCONFDIR</envar>
        configure le répertoire contenant le fichier
        <filename>pg_service.conf</filename> et dans une future version
        d'autres fichiers de configuration globaux au système.
      </para>
    </listitem>
    <listitem>
      <para>
        <indexterm>
          <primary><envar>PGLOCALEDIR</envar></primary>
        </indexterm>
        <envar>PGLOCALEDIR</envar>
        configure le répertoire contenant les fichiers <literal>locale</literal> pour 
        l'internationalisation des messages.
      </para>
    </listitem>
  </itemizedlist>
</para>

</sect1>


<sect1 id="libpq-pgpass">
<title>Fichier de mots de passe</title>

<indexterm zone="libpq-pgpass">
 <primary>fichier de mots de passe</primary>
</indexterm>
<indexterm zone="libpq-pgpass">
 <primary>.pgpass</primary>
</indexterm>

<para>
Le fichier <filename>.pgpass</filename>, situé dans le répertoire personnel de
l'utilisateur, ou le fichier référencé par <envar>PGPASSFILE</envar> est un
fichier contenant les mots de passe à utiliser si la
connexion requiert un mot de passe (et si aucun mot de passe n'a été spécifié).
Sur Microsoft Windows, le fichier est nommé
<filename>%APPDATA%\postgresql\pgpass.conf</filename> (où <filename>%APPDATA%</filename>
fait référence au sous-répertoire Application Data du profile de l'utilisateur).
</para>

<para>
Ce fichier devra être composé de lignes au format suivant (une ligne par connexion)&nbsp;: 
<synopsis><replaceable>nom_hote</replaceable>:<replaceable>port</replaceable>:<replaceable>database</replaceable>:<replaceable>nomutilisateur</replaceable>:<replaceable>motdepasse</replaceable> </synopsis> 
(Vous pouvez ajouter en commentaire dans le fichier cette ligne que vous
précédez d'un dièse (<literal>#</literal>).)
Chacun des quatre premiers champs 
pourraient être une valeur littérale ou <literal>*</literal> (qui correspond à 
tout). La première ligne réalisant une correspondance pour les paramètres de 
connexion sera utilisée (du coup, placez les entrées plus spécifiques en premier 
lorsque vous utilisez des jokers). Si une entrée a besoin de contenir 
<literal>:</literal> ou <literal>\</literal>, échappez ce caractère avec 
<literal>\</literal>. Un nom d'hôte <literal>localhost</literal> correspond à la 
fois à une connexion TCP (nom d'hôte <literal>localhost</literal>) et à une 
connexion par socket de domaine Unix (<literal>pghost</literal> vide ou le 
répertoire par défaut du socket) provenant de la machine locale. Dans un
serveur en standby, le nom de la base de données <literal>replication</literal>
correspond aux connexions réalisées par le serveur maître pour la réplication
en flux.
   Le champ <literal>database</literal> est d'une utilité limitée car les
   utilisateurs ont le même mot de passe pour toutes les bases de données
   de la même instance.
</para>

<para>
   Sur les systèmes Unix, les droits sur <filename>.pgpass</filename> doivent
   interdire l'accès au groupe et au reste du monde&nbsp;; faites-le par cette
   commande&nbsp;: <command>chmod 0600 ~/.pgpass</command>. Si les droits sont
   moins stricts que cela, le fichier sera ignoré. Sur Microsoft Windows, il est
   supposé que le fichier est stocké dans un répertoire qui est sécurisé, donc
   aucune vérification des droits n'est effectuée.
</para>
</sect1>

<sect1 id="libpq-pgservice">
<title>Fichier des connexions de service</title>

<indexterm zone="libpq-pgservice">
 <primary>fichier des connexions de service</primary>
</indexterm>
<indexterm zone="libpq-pgservice">
 <primary>pg_service.conf</primary>
</indexterm>
  <indexterm zone="libpq-pgservice">
   <primary>.pg_service.conf</primary>
  </indexterm>

<para>
Le fichier des connexions de service autorise l'association des paramètres de
connexions avec un seul nom de service. Ce nom de service peut ensuite être
spécifié par une connexion libpq et les paramétrages associés seront utilisés.
Ceci permet de modifier les paramètres de connexion sans avoir à recompiler
l'application libpq. Le nom de service peut aussi être spécifié en utilisant
la variable d'environnement <envar>PGSERVICE</envar>.
</para>

  <para>
   Le fichier de service pour la connexion peut être un fichier par utilisateur
   sur <filename>~/.pg_service.conf</filename> ou à l'emplacement indiqué par
   la variable d'environnement <envar>PGSERVICEFILE</envar>. Il peut aussi être
   un fichier global au système dans le répertoire
   <filename>etc/pg_service.conf</filename> ou dans le répertoire indiqué par
   la variable d'environnement <envar>PGSYSCONFDIR</envar>. Si les définitions
   de service de même nom existent dans le fichier utilisateur et système,
   le fichier utilisateur est utilisé.
  </para>

  <para>
   Le fichier utiliser le format des <quote>fichiers INI</quote> où le nom de
   la section et les paramètres sont des paramètres de connexion&nbsp;; voir
   <xref linkend="libpq-paramkeywords"/> pour une liste. Par exemple&nbsp;:
<programlisting>
# comment
[mabase]
host=unhote
port=5433
user=admin
</programlisting>
   Un fichier exemple est fourni sur
   <filename>share/pg_service.conf.sample</filename>.
  </para>
</sect1>

<sect1 id="libpq-ldap">
 <title>Recherches LDAP des paramètres de connexion</title>

<indexterm zone="libpq-ldap">
 <primary>Recherche LDAP des paramètres de connexion</primary>
</indexterm>

<para>
Si <application>libpq</application> a été compilé avec le support de LDAP (option
<literal><option>--with-ldap</option></literal> du script <command>configure</command>),
il est possible de récupérer les options de connexion comme <literal>host</literal>
ou <literal>dbname</literal> via LDAP à partir d'un serveur central.
L'avantage en est que, si les paramètres de connexion d'une base évolue,
l'information de connexion n'a pas à être modifiée sur toutes les machines
clientes.
</para>

<para>
La recherche LDAP des paramètres de connexion utilise le fichier service
<filename>pg_service.conf</filename> (voir <xref linkend="libpq-pgservice"/>).
Une ligne dans <filename>pg_service.conf</filename> commençant par
<literal>ldap://</literal> sera reconnue comme une URL LDAP et une requête LDAP
sera exécutée. Le résultat doit être une liste de paires <literal>motclé =
valeur</literal> qui sera utilisée pour configurer les options de connexion.
L'URL doit être conforme à la RFC 1959 et être de la forme&nbsp;:
<synopsis>
ldap://[<replaceable>hôte</replaceable>[:<replaceable>port</replaceable>]]/<replaceable>base_recherche</replaceable>?<replaceable>attribut</replaceable>?<replaceable>étendue_recherche</replaceable>?<replaceable>filtre</replaceable>
</synopsis>
où <replaceable>hôte</replaceable> vaut par défaut <literal>localhost</literal>
et <replaceable>port</replaceable> vaut par défaut 389.
</para>

<para>
Le traitement de <filename>pg_service.conf</filename> se termine après une
recherche réussie dans LDAP, mais continu si le serveur LDAP ne peut pas
être contacté. Cela fournit un moyen de préciser d'autres URL LDAP pointant
vers d'autres serveurs LDAP, des paires classiques <literal>motclé =
valeur</literal> ou les options de connexion par défaut. Si vous obtenez à la
place un message d'erreur, ajoutez une ligne syntaxiquement incorrecte après
l'URL LDAP.
</para>

<para>
Un exemple d'une entrée LDAP qui a été créée à partir d'un fichier LDIF
<programlisting>
version: 1
dn: cn=mabase,dc=masociété,dc=com
changetype: add
objectclass: top
objectclass: groupOfUniqueNames
cn: mabase
uniqueMember: host=monserveur.masociété.com
uniqueMember: port=5439
uniqueMember: dbname=mabase
uniqueMember: user=monutilisateur_base
uniqueMember: sslmode=require
</programlisting>
amènera l'exécution de l'URL LDAP suivante&nbsp;:
<programlisting>
ldap://ldap.masociété.com/dc=masociété,dc=com?uniqueMember?one?(cn=mabase)
</programlisting>
</para>

  <para>
   Vous pouvez mélanger des entrées d'un fichier de service standard avec
   des recherches par LDAP. Voici un exemple complet dans
   <filename>pg_service.conf</filename>&nbsp;:
   <programlisting>
    # seuls l'hôte et le port sont stockés dans LDAP,
    # spécifiez explicitement le nom de la base et celui de l'utilisateur
    [customerdb]
    dbname=clients
    user=utilisateurappl
    ldap://ldap.acme.com/cn=serveur,cn=hosts?pgconnectinfo?base?(objectclass=*)
   </programlisting>
  </para>
</sect1>


<sect1 id="libpq-ssl">
  <title>Support de SSL</title>
  
  <indexterm zone="libpq-ssl">
    <primary>SSL</primary>
  </indexterm>
  
  <para>
    <productname>PostgreSQL</productname> dispose d'un support natif des connexions
    <acronym>SSL</acronym> pour crypter les connexions client/serveur et améliorer
    ainsi la sécurité. Voir la <xref linkend="ssl-tcp"/> pour des détails sur la
    fonctionnalité <acronym>SSL</acronym> côté serveur.
  </para>

  <para>
   <application>libpq</application> lit le fichier de configuration système
   d'<productname>OpenSSL</productname>. Par défaut, ce fichier est nommé
   <filename>openssl.cnf</filename> et est placé dans le répertoire indiqué par
   <literal>openssl version -d</literal>. Cette valeur par défaut peut être
   surchargé en configurant la variable d'environnement
   <envar>OPENSSL_CONF</envar> avec le nom du fichier de configuration
   souhaité.
  </para>

 <sect2 id="libq-ssl-certificates">
  <title>Vérification par le client du certificat serveur</title>

  <para>
   Par défaut, <productname>PostgreSQL</productname> ne vérifie pas le certificat
   du serveur. Cela signifie qu'il est possible de se faire passer pour le
   serveur final (par exemple en modifiant un enregistrement DNS ou en prenant
   l'adresse IP du serveur) sans que le client ne le sache. Pour empêcher ceci,
   la vérification du certificat <acronym>SSL</acronym> doit être activée.
  </para>

  <para>
   Si le paramètre <literal>sslmode</literal> est configuré à
   <literal>verify-ca</literal>, libpq vérifiera que le serveur est de confiance
   en vérifiant que le certificat a bien été généré par une autorité de
   certificats (<acronym>CA</acronym>)
   de confiance. Si <literal>sslmode</literal> est configuré à
   <literal>verify-full</literal>, libpq vérifiera <emphasis>aussi</emphasis>
   que le nom du serveur correspond à son certificat. La connexion SSL
   échouera si le certificat du serveur n'établit pas ces correspondances. La
   connexion SSL échouera si le certificat du serveur ne peut pas être vérifié.
   <literal>verify-full</literal> est recommandé pour les environnements les
   plus sensibles à la sécurité.
  </para>

  <para>
   Dans le mode <literal>verify-full</literal>, l'attribut <literal>cn</literal>
   (<acronym>Common Name</acronym>) du certificat est testé par rapport au nom du serveur . Si l'attribut
   <literal>cn</literal> commence avec un astérisque(<literal>*</literal>), il
   sera traité comme un joker, et correspondra à tous les caractères
   <emphasis>sauf</emphasis> un point (<literal>.</literal>). Cela signifie
   que le certificat ne pourra pas être utilisé pour des sous-domaines complets.
   Si la connexion se fait en utilisant une adresse IP au lieu d'un nom d'hôte,
   l'adresse IP sera vérifiée (sans faire de recherche DNS).
  </para>

  <para>
   Pour permettre la vérification du certificat du serveur, le certificat d'un
   ou plusieurs <acronym>CA</acronym> de confiance doit être placé dans le fichier
   <filename>~/.postgresql/root.crt</filename> dans le répertoire personnel de
   l'utilisateur. Su Microsoft Windows, le fichier est nommé
   <filename>%APPDATA%\postgresql\root.crt</filename>.
  </para>

  <para>

   Les entrées de la liste de révocation des certificats (CRL) sont aussi
   vérifiées si le fichier <filename>~/.postgresql/root.crl</filename> existe
   (<filename>%APPDATA%\postgresql\root.crl</filename> sur Microsoft
   Windows).
  </para>

  <para>
   L'emplacement du certificat racine et du CRL peuvent être changés avec
   les paramètres de connexion <literal>sslrootcert</literal> et
   <literal>sslcrl</literal>, ou les variables d'environnement
   <envar>PGSSLROOTCERT</envar> et <envar>PGSSLCRL</envar>.
  </para>

  <note>
   <para>
    Pour une compatibilité ascendantes avec les anciennes versions de
    PostgreSQL, si un certificat racine d'autorité existe, le comportement
    de <literal>sslmode</literal>=<literal>require</literal> sera identique
    à celui de <literal>verify-ca</literal>. Cela signifie que le
    certificat du serveur est validé par l'autorité de certificat. Il ne
    faut pas se baser sur ce comportement. Les applications qui ont besoin
    d'une validation du certificat doivent toujours utiliser
    <literal>verify-ca</literal> ou <literal>verify-full</literal>.
   </para>
  </note>

 </sect2>

 <sect2 id="libpq-ssl-clientcert">
  <title>Certificats des clients</title>

  <para>
   Si le serveur réclame un certificat de confiance du client,
   <application>libpq</application> enverra le certificat stocké dans le
   fichier <filename>~/.postgresql/postgresql.crt</filename> du répertoire
   personnel de l'utilisateur. Le certificat doit être signé par une des
   autorités (<acronym>CA</acronym>) de confiance du serveur. Un fichier de
   clé privé correspondant <filename>~/.postgresql/postgresql.key</filename>
   doit aussi être présent. Le fichier de clé privée ne doit pas permettre son
   accès pour le groupe ou pour le reste du monde&nbsp;; cela se fait avec la
   commande <command>chmod 0600 ~/.postgresql/postgresql.key</command>. Sur
   Microsoft Windows, ces fichiers sont nommés
   <filename>%APPDATA%\postgresql\postgresql.crt</filename> et
   <filename>%APPDATA%\postgresql\postgresql.key</filename>, et il n'existe pas
   de vérification de droits car ce répertoire est présumé sécurisé.
   L'emplacement des fichiers certificat et clé peut être surchargé par les
   paramètres de connexion <literal>sslcert</literal> et
   <literal>sslkey</literal>, ou les variables d'environnement
   <envar>PGSSLCERT</envar> et <envar>PGSSLKEY</envar>.
  </para>

  <para>
   Dans certains cas, le certificat du client peut être signé par une autorité
   de certificat <quote>intermédiaire</quote>, plutôt que par un qui est
   directement accepté par le serveur. Pour utiliser un tel certificat,
   ajoutez le certificat de l'autorité signataire du fichier
   <filename>postgresql.crt</filename>, alors son certificat de l'autorité
   parente, et ainsi de suite jusqu'à arriver à l'autorité
   <quote>racine</quote> qui est accepté par le serveur. Le certificat
   racine doit être inclus dans chaque cas où
   <filename>postgresql.crt</filename> contient plus d'un certificat.
  </para>

  <para>
   Notez que <filename>root.crt</filename> liste les autorités de certificat
   de haut-niveau qui sont considérées de confiance pour les certificats
   serveur signataires. En principe, il n'a pas besoin de lister l'autorité
   de certificats qui a signé le certificat du client, bien que dans la plupart
   des cas, l'autorité du certificat sera aussi de confiance pour les
   certificats serveur.
  </para>

 </sect2>

 <sect2 id="libpq-ssl-protection">
  <title>Protection fournie dans les différents modes</title>

  <para>
   Les différentes valeurs du paramètre <literal>sslmode</literal> fournissent
   différents niveaux de protection. SSL peut fournir une protection contre trois types d'attaques différentes&nbsp;:
   <variablelist>
    <varlistentry>
     <term>L'écoute</term>
     <listitem>
      <para>Si une troisième partie peut examiner le trafic réseau entre le
       client et le serveur, il peut lire à la fois les informations de
       connexion (ceci incluant le nom de l'utilisateur et son mot de passe)
       ainsi que les données qui y passent. <acronym>SSL</acronym> utilise
       le chiffrement pour empêcher cela.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>Man in the middle (<acronym>MITM</acronym>)</term>
     <listitem>
      <para>Si une troisième partie peut modifier les données passant entre
       le client et le serveur, il peut prétendre être le serveur et, du coup,
       voir et modifier les données <emphasis>y compris si elles sont
       chiffrées</emphasis>. La troisième partie peut ensuite renvoyer les
       informations de connexion et les données au serveur d'origine, rendant à
       ce dernier impossible la détection de cette attaque. Les vecteurs communs
       pour parvenir à ce type d'attaque sont l'empoisonnement des DNS et la
       récupération des adresses IP où le client est dirigé vers un autre serveur
       que celui attendu. Il existe aussi plusieurs autres méthodes d'attaque
       pour accomplir ceci. <acronym>SSL</acronym> utilise la vérification des
       certificats pour empêcher ceci, en authentifiant le serveur auprès du
       client.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
     <term>Impersonnification</term>
     <listitem>
      <para>Si une troisième partie peut prétendre être un client autorisé, il
       peut tout simplement accéder aux données auquel il n'a pas droit.
       Typiquement, cela peut arrier avec une gestion incorrecte des mots de
       passe. <acronym>SSL</acronym> utilise les certificats clients pour
       empêcher ceci, en s'assurant que seuls les propriétaires de certificats
       valides peuvent accéder au serveur.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
   Pour qu'une connexion soit sûre, l'utilisation de SSL doit être configurée
   <emphasis>sur le client et sur le serveur</emphasis> avant que
   la connexion ne soit effective. Si c'est seulement configuré sur le serveur,
   le client pourrait envoyer des informations sensibles (comme les mots de
   passe) avant qu'il ne sache que le serveur réclame une sécurité importante.
   Dans libpq, les connexions sécurisées peuvent être garanties en configurant le paramètre
   <literal>sslmode</literal> à <literal>verify-full</literal> ou
   <literal>verify-ca</literal>, et en fournissant au système un certificat
   racine à vérifier. Ceci est analogue à l'utilisation des <acronym>URL</acronym>
   <literal>https</literal> pour la navigation web chiffrée.
  </para>

  <para>
   Une fois que le serveur est authentifié, le client peut envoyer des données
   sensibles. Cela signifie que jusqu'à ce point, le client n'a pas besoin de
   savoir si les certificats seront utilisés pour l'authentification, rendant
   particulièrement sûr de ne spécifier que ceci dans la configuration du
   serveur.
  </para>

  <para>
   Toutes les options <acronym>SSL</acronym> ont une surcharge du type
   chiffrement et échange de clés. Il y a donc une balance entre performance et
   sécurité. <xref linkend="libpq-ssl-sslmode-statements"/> illustre les risques que les différentes valeurs
   de <literal>sslmode</literal> cherchent à protéger, et ce que cela apporte
   en sécurité et fait perdre en performances.
  </para>

  <table id="libpq-ssl-sslmode-statements">
   <title>Description des modes SSL</title>
   <tgroup cols="4">
    <thead>
     <row>
      <entry><literal>sslmode</literal></entry>
      <entry>Protection contre l'écoute</entry>
      <entry>Protection contre l'attaque <acronym>MITM</acronym></entry>
      <entry>Remarques</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><literal>disable</literal></entry>
      <entry>Non</entry>
      <entry>Non</entry>
      <entry>Peu m'importe la sécurité, je ne veux pas la surcharge apportée
       par le chiffrement.
      </entry>
     </row>

     <row>
      <entry><literal>allow</literal></entry>
      <entry>Peut-être</entry>
      <entry>Non</entry>
      <entry>Peu m'importe la sécurité, mais je vais accepter la surcharge du
       chiffrement si le serveur insiste là-dessus.
      </entry>
     </row>

     <row>
      <entry><literal>prefer</literal></entry>
      <entry>Peut-être</entry>
      <entry>Non</entry>
      <entry>Peu m'importe la sécurité, mais j'accepte la surcharge du
       chiffrement si le serveur le supporte.
      </entry>
     </row>

     <row>
      <entry><literal>require</literal></entry>
      <entry>Oui</entry>
      <entry>Non</entry>
      <entry>Je veux chiffrer mes données, et j'accepte la surcharge. Je fais
       confiance au résreau pour me connecter toujours au serveur que je veux.
      </entry>
     </row>

     <row>
      <entry><literal>verify-ca</literal></entry>
      <entry>Oui</entry>
      <entry><literal>Depends on CA</literal>-policy</entry>
      <entry>Je veux chiffrer mes données, et j'accepte la surcharge. Je veux
       aussi être sûr que je me connecte à un serveur en qui j'ai confiance.
      </entry>
     </row>

     <row>
      <entry><literal>verify-full</literal></entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
       <entry>Je veux chiffrer mes données, et j'accepte la surcharge. Je veux
        être sûr que je me connecte à un serveur en qui j'ai confiance et que
	c'est bien celui que j'indique.
       </entry>
      </row>

    </tbody>
   </tgroup>
  </table>

  <para>
   La différence entre <literal>verify-ca</literal> et <literal>verify-full</literal>
   dépend de la politique du <acronym>CA</acronym> racine. Si un
   <acronym>CA</acronym> publique est utilisé, <literal>verify-ca</literal> permet
   les connexions à un serveur que <emphasis>quelqu'un d'autre</emphasis> a pu
   enregistrer avec un <acronym>CA</acronym> accepté. Dans ce cas,
   <literal>verify-full</literal> devrait toujours être utilisé. Si un
   <acronym>CA</acronym> local est utilisé, voire même un certificat signé
   soi-même, utiliser <literal>verify-ca</literal> fournit souvent suffisamment de
   protection.
  </para>

  <para>
   La valeur par défaut pour <literal>sslmode</literal> est <literal>prefer</literal>.
   Comme l'indique la table ci-dessus, cela n'a pas de sens d'un point de vue
   de la sécurité, et cela ne promet qu'une surcharge en terme de performance
   si possible. C'est uniquement fourni comme valeur par défaut pour la
   compatibilité ascendante, et n'est pas recommandé pour les déploiements de
   serveurs nécessitant de la sécurité.
  </para>

 </sect2>

 <sect2 id="libpq-ssl-fileusage">
  <title>Utilisation des fichiers SSL</title>

  <para>
   <xref linkend="libpq-ssl-file-usage"/> résume les fichiers liés à la
   configuration de SSL sur le client.
  </para>

  <table id="libpq-ssl-file-usage">
   <title>Utilisation des fichiers SSL libpq/client</title>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Fichier</entry>
      <entry>Contenu</entry>
      <entry>Effet</entry>
     </row>
    </thead>

    <tbody>

     <row>
      <entry><filename>~/.postgresql/postgresql.crt</filename></entry>
      <entry>certificat client</entry>
      <entry>requis par le serveur</entry>
     </row>

     <row>
      <entry><filename>~/.postgresql/postgresql.key</filename></entry>
      <entry>clé privée du client</entry>
      <entry>prouve le certificat client envoyé par l'utilisateur&nbsp;;
        n'indique pas que le propriétaire du certificat est de
        confiance</entry>
     </row>

     <row>
      <entry><filename>~/.postgresql/root.crt</filename></entry>
      <entry>autorité de confiance du certificat</entry>
      <entry>vérifie que le certificat du serveur est signé par une autorité
        de confiance</entry>
     </row>

     <row>
      <entry><filename>~/.postgresql/root.crl</filename></entry>
      <entry>certificats révoqués par les autorités</entry>
      <entry>le certificat du serveur ne doit pas être sur cette liste</entry>
     </row>

    </tbody>
   </tgroup>
  </table>
 </sect2>

 <sect2 id="libpq-ssl-initialize">
  <title>Initialisation de la bibliothèque SSL</title>

  <para>
   Si votre application initialise les bibliothèques <literal>libssl</literal>
   et/ou <literal>libcrypto</literal> et que <application>libpq</application>
   est construit avec le support de <acronym>SSL</acronym>, vous devez appeler
   la fonction <function>PQinitOpenSSL</function> pour indiquer à
   <application>libpq</application> que les bibliothèques
   <literal>libssl</literal> et/ou <literal>libcrypto</literal> ont été
   initialisées par votre application, de façon à ce que
   <application>libpq</application> n'initialise pas elle-aussi ces
   bibliothèques.
   <!-- If this URL changes replace it with a URL to www.archive.org. -->
   Voir <ulink
   url="http://h71000.www7.hp.com/doc/83final/BA554_90007/ch04.html"></ulink>
   pour plus de détails sur l'API SSL.
  </para>

  <para>
   <variablelist>
    <varlistentry id="libpq-pqinitopenssl">
     <term>
      <function>PQinitOpenSSL</function>
      <indexterm>
       <primary>PQinitOpenSSL</primary>
      </indexterm>
     </term>

     <listitem>
      <para>
       Permet aux applications de sélectionner les bibliothèques de sécurité
       à initialiser.
       <synopsis>
        void PQinitOpenSSL(int do_ssl, int do_crypto);
       </synopsis>
      </para>

      <para>
       Quand <parameter>do_ssl</parameter> est différent de zéro,
       <application>libpq</application> initialisera la bibliothèque
       <application>OpenSSL</application> avant d'ouvrir une connexion à la base
       de données. Quand <parameter>do_crypto</parameter> est différent de
       zéro, la bibliothèque <literal>libcrypto</literal> sera initialisée. Par
       défaut (si <function>PQinitOpenSSL</function> n'est pas appelé), les deux
       bibliothèques sont initialisées. Quand le support de SSL n'est pas
       intégré, cette fonction est présente mais ne fait rien.
      </para>

      <para>
       Si votre application utilise et initialise soit
       <application>OpenSSL</application> soit <literal>libcrypto</literal>,
       vous <emphasis>devez</emphasis> appeler cette fonction avec des zéros
       pour les paramètres appropriés avant d'ouvrir la première connexion à la
       base de données. De plus, assurez-vous que vous avez fait cette
       initialisation avant d'ouvrir une connexion à la base de données.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-pqinitssl">
     <term>
      <function>PQinitSSL</function>
      <indexterm>
       <primary>PQinitSSL</primary>
      </indexterm>
     </term>

     <listitem>
      <para>
       Permet aux applications de sélectionner les bibliothèques de sécurité
       à initialiser.
       <synopsis>
        void PQinitSSL(int do_ssl);
       </synopsis>
      </para>

      <para>
       Cette fonction est équivalent à
       <literal>PQinitOpenSSL(do_ssl, do_ssl)</literal>. C'est suffisant pour les
       applications qui initialisent à la fois <application>OpenSSL</application>
       et<literal>libcrypto</literal> ou aucune des deux.
      </para>

      <para>
       <function>PQinitSSL</function> est présente depuis
       <productname>PostgreSQL</productname> 8.0, alors que
       <function>PQinitOpenSSL</function> a été ajoutée dans
       <productname>PostgreSQL</productname> 8.4, donc
       <function>PQinitSSL</function> peut être préférée pour les applications
       qui ont besoin de fonctionner avec les anciennes versions de
       <application>libpq</application>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </sect2>

</sect1>

<sect1 id="libpq-threading">
      <title>Comportement des programmes threadés</title>

<indexterm zone="libpq-threading">
 <primary>threads</primary>
 <secondary>avec libpq</secondary>
</indexterm>

<para>
<application>libpq</application> est réentrante et sûre avec les threads par
défaut. Vous pourriez avoir besoin d'utiliser des options de
compilation supplémentaires en ligne lorsque vous compiler le code de votre
application. Référez-vous aux documentations de votre système pour savoir
comment construire des applications actives au niveau thread ou recherchez
<literal>PTHREAD_CFLAGS</literal> et <literal>PTHREAD_LIBS</literal> dans
<filename>src/Makefile.global</filename>. Cette fonction permet d'exécuter
des requêtes sur le statut de <application>libpq</application> concernant les
threads&nbsp;:
</para>

<variablelist>
<varlistentry id="libpq-pqisthreadsafe">
<term><function>PQisthreadsafe</function><indexterm><primary>PQisthreadsafe</primary></indexterm></term>
<listitem>
<para>
       Renvoie le statut de sûreté des threads pour <application>libpq</application>
       library.
<synopsis>
int PQisthreadsafe();
</synopsis>
</para>

<para>
       Renvoie 1 si <application>libpq</application> supporte les threads,
       0 dans le cas contraire.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
Une restriction&nbsp;: il ne doit pas y avoir deux tentatives de threads
manipulant le même objet <structname>PGconn</structname> à la fois. En particulier, vous
ne pouvez pas lancer des commandes concurrentes à partir de threads différents
à travers le même objet de connexion (si vous avez besoin de lancer des
commandes concurrentes, utilisez plusieurs connexions).
</para>

<para>
Les objets <structname>PGresult</structname> sont en lecture seule après
leur création et, du coup, ils peuvent être passés librement entre les
threads. Les objets <structname>PGresult</structname> sont en lecture
seule après leur création et, du coup, ils peuvent être passés librement
entre les threads. Néanmoins, si vous utilisez une des fonctions de
modification d'un <structname>PGresult</structname> décrites dans <xref
linkend="libpq-misc"/> ou <xref linkend="libpq-events"/>, vous devez
aussi éviter toute opération concurrente sur le même
<structname>PGresult</structname>.
</para>

<para>
Les fonctions obsolètes
<function>PQrequestCancel</function> et
<function>PQoidStatus</function>
ne gèrent pas les threads et ne devraient pas être utilisées dans des programmes multithread. <function>PQrequestCancel</function> peut être
remplacé par <function>PQcancel</function>.
<function>PQoidStatus</function> peut être remplacé par
<function>PQoidValue</function>.
</para>

<para>
Si vous utilisez Kerberos avec votre application (ainsi que dans
<application>libpq</application>), vous aurez besoin de verrouiller les appels
Kerberos car les fonctions Kerberos ne sont pas sûres lorsqu'elles sont
utilisées avec des threads. Voir la fonction <function>PQregisterThreadLock</function>
dans le code source de <application>libpq</application> pour récupérer un moyen
de faire un verrouillage coopératif entre <application>libpq</application> et
votre application.
</para>

<para>
Si vous expérimentez des problèmes avec les applications utilisant des threads,
lancez le programme dans <filename>src/tools/thread</filename> pour voir si votre
plateforme à des fonctions non compatibles avec les threads. Ce programme
est lancé par <filename>configure</filename> mais, dans le cas des
distributions binaires, votre bibliothèque pourrait ne pas correspondre à la bibliothèque utilisée pour construire les binaires.
</para>
</sect1>


 <sect1 id="libpq-build">
  <title>Construire des applications avec
<application>libpq</application></title>

  <indexterm zone="libpq-build">
   <primary>compilation</primary>
   <secondary>applications libpq</secondary>
  </indexterm>

  <para>
   Pour construire (c'est-à-dire compiler et lier) un programme utilisant
   <application>libpq</application>, vous avez besoin de faire tout ce qui
   suit&nbsp;:

   <itemizedlist>
    <listitem>
     <para>
      Incluez le fichier d'en-tête <filename>libpq-fe.h</filename>&nbsp;:
<programlisting>#include &lt;libpq-fe.h&gt;
</programlisting>
      Si vous ne le faites pas, alors vous obtiendrez normalement les messages
      d'erreurs similaires à ceci
<screen>foo.c: In function `main':
foo.c:34: `PGconn' undeclared (first use in this function)
foo.c:35: `PGresult' undeclared (first use in this function)
foo.c:54: `CONNECTION_BAD' undeclared (first use in this function)
foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function)
foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function)
</screen>
     </para>
    </listitem>

    <listitem>
     <para>
      Pointez votre compilateur sur le répertoire où les fichiers d'en-tête 
      de <productname>PostgreSQL</productname> ont été installés en fournissant l'option
      <literal>-I<replaceable>répertoire</replaceable></literal> à votre
      compilateur (dans certains cas, le compilateur cherchera dans le
      répertoire en question par défaut, donc vous pouvez omettre cette
      option). Par exemple, votre ligne de commande de compilation devrait
      ressembler à ceci&nbsp;:
<programlisting>cc -c -I/usr/local/pgsql/include testprog.c
</programlisting>
      Si vous utilisez des makefiles, alors ajoutez cette option à la variable
      <varname>CPPFLAGS</varname>&nbsp;:
<programlisting>CPPFLAGS += -I/usr/local/pgsql/include
</programlisting>
     </para>

     <para>
      S'il existe une chance pour que votre programme soit compilé par
      d'autres utilisateurs, alors vous ne devriez pas coder en dur
      l'emplacement du répertoire. À la place, vous pouvez exécuter l'outil
      <command>pg_config</command><indexterm><primary>pg_config</primary><secondary
      sortas="libpq">avec libpq</secondary></indexterm> pour trouver où sont placés les fichiers
      d'en-tête sur le système local&nbsp;:
<screen><prompt>$</prompt> pg_config --includedir
<computeroutput>/usr/local/include</computeroutput>
</screen>
     </para>

     <para>
      If you
      have <command>pkg-config</command><indexterm><primary>pkg-config</primary><secondary sortas="libpq">with
      libpq</secondary></indexterm> installed, you can run instead:
<screen>
<prompt>$</prompt> pkg-config --cflags libpq
<computeroutput>-I/usr/local/include</computeroutput>
</screen>
      Note that this will already include the <option>-I</option> in front of
      the path.
     </para>

     <para>
      Un échec sur la spécification de la bonne option au compilateur
      résultera en un message d'erreur tel que
<screen>testlibpq.c:8:22: libpq-fe.h: No such file or directory
</screen>
     </para>
    </listitem>

    <listitem>
     <para>
      Lors de l'édition des liens du programme final, spécifiez l'option
      <literal>-lpq</literal> de façon à ce que 
      les bibliothèques <application>libpq</application> soient intégrées, ainsi
      que l'option <literal>-L<replaceable>répertoire</replaceable></literal>
      pour pointer le compilateur vers le répertoire où les bibliothèques
      <application>libpq</application> résident (de nouveau, le compilateur
      cherchera certains répertoires par défaut). Pour une portabilité maximale,
      placez l'option <option>-L</option> avant l'option <option>-lpq</option>.
      Par exemple&nbsp;:
<programlisting>cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq
</programlisting>
     </para>

     <para>
      Vous pouvez aussi récupérer le répertoire des bibliothèques en utilisant
      <command>pg_config</command>&nbsp;:
<screen><prompt>$</prompt> pg_config --libdir
<computeroutput>/usr/local/pgsql/lib</computeroutput>
</screen>
     </para>

     <para>
      Or again use <command>pkg-config</command>:
<screen>
<prompt>$</prompt> pkg-config --libs libpq
<computeroutput>-L/usr/local/pgsql/lib -lpq</computeroutput>
</screen>
      Note again that this prints the full options, not only the path.
     </para>

     <para>
      Les messages d'erreurs, pointant vers des problèmes de ce style,
      pourraient ressembler à ce qui suit.
<screen>testlibpq.o: In function `main':
testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin'
testlibpq.o(.text+0x71): undefined reference to `PQstatus'
testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
</screen>
      Ceci signifie que vous avez oublié <option>-lpq</option>.
<screen>/usr/bin/ld: cannot find -lpq
</screen>
      Ceci signifie que vous avez oublié l'option <option>-L</option> ou que
      vous n'avez pas indiqué le bon répertoire.
     </para>
    </listitem>
   </itemizedlist>
  </para>

 </sect1>


 <sect1 id="libpq-example">
  <title>Exemples de programmes</title>

  <para>
   Ces exemples (et d'autres) sont disponibles dans le répertoire
   <filename>src/test/examples</filename> de la distribution des sources.
  </para>

  <example id="libpq-example-1">
   <title>Premier exemple de programme pour
    <application>libpq</application></title>

<programlisting><![CDATA[/*
 * testlibpq.c
 *
 *      Test the C version of libpq, the PostgreSQL frontend library.
 */
#include <stdio.h>
#include <stdlib.h>
#include <libpq-fe.h>

static void
exit_nicely(PGconn *conn)
{
    PQfinish(conn);
    exit(1);
}

int
main(int argc, char **argv)
{
    const char *conninfo;
    PGconn     *conn;
    PGresult   *res;
    int         nFields;
    int         i,
                j;

    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    if (argc > 1)
        conninfo = argv[1];
    else
        conninfo = "dbname = postgres";

    /* Make a connection to the database */
    conn = PQconnectdb(conninfo);

    /* Check to see that the backend connection was successfully made */
    if (PQstatus(conn) != CONNECTION_OK)
    {
        fprintf(stderr, "Connection to database failed: %s",
                PQerrorMessage(conn));
        exit_nicely(conn);
    }

    /*
     * Our test case here involves using a cursor, for which we must be inside
     * a transaction block.  We could do the whole thing with a single
     * PQexec() of "select * from pg_database", but that's too trivial to make
     * a good example.
     */

    /* Start a transaction block */
    res = PQexec(conn, "BEGIN");
    if (PQresultStatus(res) != PGRES_COMMAND_OK)
    {
        fprintf(stderr, "BEGIN command failed: %s", PQerrorMessage(conn));
        PQclear(res);
        exit_nicely(conn);
    }

    /*
     * Should PQclear PGresult whenever it is no longer needed to avoid memory
     * leaks
     */
    PQclear(res);

    /*
     * Fetch rows from pg_database, the system catalog of databases
     */
    res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database");
    if (PQresultStatus(res) != PGRES_COMMAND_OK)
    {
        fprintf(stderr, "DECLARE CURSOR failed: %s", PQerrorMessage(conn));
        PQclear(res);
        exit_nicely(conn);
    }
    PQclear(res);

    res = PQexec(conn, "FETCH ALL in myportal");
    if (PQresultStatus(res) != PGRES_TUPLES_OK)
    {
        fprintf(stderr, "FETCH ALL failed: %s", PQerrorMessage(conn));
        PQclear(res);
        exit_nicely(conn);
    }

    /* first, print out the attribute names */
    nFields = PQnfields(res);
    for (i = 0; i < nFields; i++)
        printf("%-15s", PQfname(res, i));
    printf("\n\n");

    /* next, print out the rows */
    for (i = 0; i < PQntuples(res); i++)
    {
        for (j = 0; j < nFields; j++)
            printf("%-15s", PQgetvalue(res, i, j));
        printf("\n");
    }

    PQclear(res);

    /* close the portal ... we don't bother to check for errors ... */
    res = PQexec(conn, "CLOSE myportal");
    PQclear(res);

    /* end the transaction */
    res = PQexec(conn, "END");
    PQclear(res);

    /* close the connection to the database and cleanup */
    PQfinish(conn);

    return 0;
}
]]></programlisting>
  </example>

  <example id="libpq-example-2">
   <title>Deuxième exemple de programme pour
    <application>libpq</application></title>

<programlisting><![CDATA[/*
 * testlibpq2.c
 *      Test of the asynchronous notification interface
 *
 * Start this program, then from psql in another window do
 *   NOTIFY TBL2;
 * Repeat four times to get this program to exit.
 *
 * Or, if you want to get fancy, try this:
 * populate a database with the following commands
 * (provided in src/test/examples/testlibpq2.sql):
 *
 *   CREATE TABLE TBL1 (i int4);
 *
 *   CREATE TABLE TBL2 (i int4);
 *
 *   CREATE RULE r1 AS ON INSERT TO TBL1 DO
 *     (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2);
 *
 * and do this four times:
 *
 *   INSERT INTO TBL1 VALUES (10);
 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <sys/time.h>
#include <libpq-fe.h>

static void
exit_nicely(PGconn *conn)
{
    PQfinish(conn);
    exit(1);
}

int
main(int argc, char **argv)
{
    const char *conninfo;
    PGconn     *conn;
    PGresult   *res;
    PGnotify   *notify;
    int         nnotifies;

    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    if (argc > 1)
        conninfo = argv[1];
    else
        conninfo = "dbname = postgres";

    /* Make a connection to the database */
    conn = PQconnectdb(conninfo);

    /* Check to see that the backend connection was successfully made */
    if (PQstatus(conn) != CONNECTION_OK)
    {
        fprintf(stderr, "Connection to database failed: %s",
                PQerrorMessage(conn));
        exit_nicely(conn);
    }

    /*
     * Issue LISTEN command to enable notifications from the rule's NOTIFY.
     */
    res = PQexec(conn, "LISTEN TBL2");
    if (PQresultStatus(res) != PGRES_COMMAND_OK)
    {
        fprintf(stderr, "LISTEN command failed: %s", PQerrorMessage(conn));
        PQclear(res);
        exit_nicely(conn);
    }

    /*
     * should PQclear PGresult whenever it is no longer needed to avoid memory
     * leaks
     */
    PQclear(res);

    /* Quit after four notifies are received. */
    nnotifies = 0;
    while (nnotifies < 4)
    {
        /*
         * Sleep until something happens on the connection.  We use select(2)
         * to wait for input, but you could also use poll() or similar
         * facilities.
         */
        int         sock;
        fd_set      input_mask;

        sock = PQsocket(conn);

        if (sock < 0)
            break;              /* shouldn't happen */

        FD_ZERO(&input_mask);
        FD_SET(sock, &input_mask);

        if (select(sock + 1, &input_mask, NULL, NULL, NULL) < 0)
        {
            fprintf(stderr, "select() failed: %s\n", strerror(errno));
            exit_nicely(conn);
        }

        /* Now check for input */
        PQconsumeInput(conn);
        while ((notify = PQnotifies(conn)) != NULL)
        {
            fprintf(stderr,
                    "ASYNC NOTIFY of '%s' received from backend PID %d\n",
                    notify->relname, notify->be_pid);
            PQfreemem(notify);
            nnotifies++;
        }
    }

    fprintf(stderr, "Done.\n");

    /* close the connection to the database and cleanup */
    PQfinish(conn);

    return 0;
}
]]></programlisting>
  </example>

  <example id="libpq-example-3">
   <title>Troisième exemple de programme pour
    <application>libpq</application></title>

<programlisting><![CDATA[/*
 * testlibpq3.c
 *      Test out-of-line parameters and binary I/O.
 *
 * Before running this, populate a database with the following commands
 * (provided in src/test/examples/testlibpq3.sql):
 *
 * CREATE TABLE test1 (i int4, t text, b bytea);
 *
 * INSERT INTO test1 values (1, 'joe''s place', '\\000\\001\\002\\003\\004');
 * INSERT INTO test1 values (2, 'ho there', '\\004\\003\\002\\001\\000');
 *
 * The expected output is:
 *
 * tuple 0: got
 *  i = (4 bytes) 1
 *  t = (11 bytes) 'joe's place'
 *  b = (5 bytes) \000\001\002\003\004
 *
 * tuple 0: got
 *  i = (4 bytes) 2
 *  t = (8 bytes) 'ho there'
 *  b = (5 bytes) \004\003\002\001\000
 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <libpq-fe.h>

/* for ntohl/htonl */
#include <netinet/in.h>
#include <arpa/inet.h>


static void
exit_nicely(PGconn *conn)
{
    PQfinish(conn);
    exit(1);
}

/*
 * This function prints a query result that is a binary-format fetch from
 * a table defined as in the comment above.  We split it out because the
 * main() function uses it twice.
 */
static void
show_binary_results(PGresult *res)
{
    int         i,
                j;
    int         i_fnum,
                t_fnum,
                b_fnum;

    /* Use PQfnumber to avoid assumptions about field order in result */
    i_fnum = PQfnumber(res, "i");
    t_fnum = PQfnumber(res, "t");
    b_fnum = PQfnumber(res, "b");

    for (i = 0; i < PQntuples(res); i++)
    {
        char       *iptr;
        char       *tptr;
        char       *bptr;
        int         blen;
        int         ival;

        /* Get the field values (we ignore possibility they are null!) */
        iptr = PQgetvalue(res, i, i_fnum);
        tptr = PQgetvalue(res, i, t_fnum);
        bptr = PQgetvalue(res, i, b_fnum);

        /*
         * The binary representation of INT4 is in network byte order, which
         * we'd better coerce to the local byte order.
         */
        ival = ntohl(*((uint32_t *) iptr));

        /*
         * The binary representation of TEXT is, well, text, and since libpq
         * was nice enough to append a zero byte to it, it'll work just fine
         * as a C string.
         *
         * The binary representation of BYTEA is a bunch of bytes, which could
         * include embedded nulls so we have to pay attention to field length.
         */
        blen = PQgetlength(res, i, b_fnum);

        printf("tuple %d: got\n", i);
        printf(" i = (%d bytes) %d\n",
               PQgetlength(res, i, i_fnum), ival);
        printf(" t = (%d bytes) '%s'\n",
               PQgetlength(res, i, t_fnum), tptr);
        printf(" b = (%d bytes) ", blen);
        for (j = 0; j < blen; j++)
            printf("\\%03o", bptr[j]);
        printf("\n\n");
    }
}

int
main(int argc, char **argv)
{
    const char *conninfo;
    PGconn     *conn;
    PGresult   *res;
    const char *paramValues[1];
    int         paramLengths[1];
    int         paramFormats[1];
    uint32_t    binaryIntVal;

    /*
     * If the user supplies a parameter on the command line, use it as the
     * conninfo string; otherwise default to setting dbname=postgres and using
     * environment variables or defaults for all other connection parameters.
     */
    if (argc > 1)
        conninfo = argv[1];
    else
        conninfo = "dbname = postgres";

    /* Make a connection to the database */
    conn = PQconnectdb(conninfo);

    /* Check to see that the backend connection was successfully made */
    if (PQstatus(conn) != CONNECTION_OK)
    {
        fprintf(stderr, "Connection to database failed: %s",
                PQerrorMessage(conn));
        exit_nicely(conn);
    }

    /*
     * The point of this program is to illustrate use of PQexecParams() with
     * out-of-line parameters, as well as binary transmission of data.
     *
     * This first example transmits the parameters as text, but receives the
     * results in binary format.  By using out-of-line parameters we can
     * avoid a lot of tedious mucking about with quoting and escaping, even
     * though the data is text.  Notice how we don't have to do anything
     * special with the quote mark in the parameter value.
     */

    /* Here is our out-of-line parameter value */
    paramValues[0] = "joe's place";

    res = PQexecParams(conn,
                       "SELECT * FROM test1 WHERE t = $1",
                       1,       /* one param */
                       NULL,    /* let the backend deduce param type */
                       paramValues,
                       NULL,    /* don't need param lengths since text */
                       NULL,    /* default to all text params */
                       1);      /* ask for binary results */

    if (PQresultStatus(res) != PGRES_TUPLES_OK)
    {
        fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn));
        PQclear(res);
        exit_nicely(conn);
    }

    show_binary_results(res);

    PQclear(res);

    /*
     * In this second example we transmit an integer parameter in binary
     * form, and again retrieve the results in binary form.
     *
     * Although we tell PQexecParams we are letting the backend deduce
     * parameter type, we really force the decision by casting the parameter
     * symbol in the query text.  This is a good safety measure when sending
     * binary parameters.
     */

    /* Convert integer value "2" to network byte order */
    binaryIntVal = htonl((uint32_t) 2);

    /* Set up parameter arrays for PQexecParams */
    paramValues[0] = (char *) &binaryIntVal;
    paramLengths[0] = sizeof(binaryIntVal);
    paramFormats[0] = 1;        /* binary */

    res = PQexecParams(conn,
                       "SELECT * FROM test1 WHERE i = $1::int4",
                       1,       /* one param */
                       NULL,    /* let the backend deduce param type */
                       paramValues,
                       paramLengths,
                       paramFormats,
                       1);      /* ask for binary results */

    if (PQresultStatus(res) != PGRES_TUPLES_OK)
    {
        fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn));
        PQclear(res);
        exit_nicely(conn);
    }

    show_binary_results(res);

    PQclear(res);

    /* close the connection to the database and cleanup */
    PQfinish(conn);

    return 0;
}
]]></programlisting>
  </example>

 </sect1>
</chapter>