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> 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 si la connexion s'est bien effectuée avant de lancer des
   requêtes via l'objet de connexion.

   <variablelist>
    <varlistentry>
     <term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</primary></indexterm></term>
     <listitem>
      <para>
       Crée une nouvelle connexion au 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 à partir de la chaîne <literal>conninfo</literal>.
   Contrairement à <function>PQsetdbLogin</function> ci-dessous, l'ensemble des
   paramètres peut être étendu sans changer la signature de la fonction, donc
   utiliser cette fonction (ou son analogue non bloquant,
   <function>PQconnectStart</function> et <function>PQconnectPoll</function>) est
   préférée pour la programmation de nouvelles applications.
   </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étrages séparés par des espaces
    blancs. Chaque paramètre est de la forme <literal>motclé = valeur</literal>.
    Les espaces autour du signe égal sont optionnels. Pour écrire une valeur
    vide ou une valeur contenant des espaces, entourez-les de guillemets simples,
    c'est-à-dire <literal>motclé = 'une valeur'</literal>. À l'intérieur de la
    valeur, des guillemets simples et des antislashs peuvent être échappés
    avec un antislash, par exemple
    <literal>\'</literal> et <literal>\\</literal>.
    </para>

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

   <variablelist>
    <varlistentry>
     <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>
     <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.
      Néanmoins, les authentifications Kerberos et GSSAPI requièrent un nom
      d'hôte. Du coup, ce
      qui suit s'applique&nbsp;: si <literal>host</literal> est spécifié sans
      <literal>hostaddr</literal>, une recherche de nom d'hôte a lieu. Si
      <literal>hostaddr</literal> est spécifié sans <literal>host</literal>, la valeur de
      <literal>hostaddr</literal> donne l'adresse distante. Lorsque Kerberos est
      utilisée, une recherche de nom inverse est effectuée pour obtenir le nom
      d'hôte pour Kerberos. Si à la fois <literal>host</literal> et
      <literal>hostaddr</literal> sont spécifiés, la valeur de <literal>hostaddr</literal>
      donne l'adresse distante&nbsp;; la valeur de <literal>host</literal> est ignorée
      sauf si Kerberos est utilisé, auquel cas il s'agit de la valeur utilisée
      pour l'authentification Kerberos (notez que l'authentification a des
      risques d'échouer si <application>libpq</application> se voit donner un
      nom qui n'est pas le nom de la machine sur <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>
     <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>
     <term><literal>dbname</literal></term>
     <listitem>
     <para>
      Nom de la base de données. Par défaut, la même que le nom utilisateur.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <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>
     <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>
     <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>
     <term><literal>options</literal></term>
     <listitem>
      <para>
       Options en ligne de commande à envoyer au serveur.
      </para>
     </listitem>
    </varlistentry>

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

    <varlistentry>
     <term><literal>sslmode</literal></term>
     <listitem>
      <para>
       Cette option détermine si ou avec quelle priorité une connexion
       TCP/IP <acronym>SSL</acronym> sera négociée avec le serveur. Il existe quatre
       modes&nbsp;: <literal>disable</literal> essaiera uniquement une connexion non
       cryptée <acronym>SSL</acronym>&nbsp;; <literal>allow</literal> négociera en essayant
       tout d'abord une connexion sans <acronym>SSL</acronym> puis, si cela échoue, une
       connexion <acronym>SSL</acronym>&nbsp;; <literal>prefer</literal> (la valeur par
       défaut) négociera en essayant d'abord une connexion <acronym>SSL</acronym> puis,
       en cas d'échec, une connexion non <acronym>SSL</acronym>&nbsp;;
       <literal>require</literal> essaiera uniquement une connexion <acronym>SSL</acronym>.
       <literal>sslmode</literal> est ignoré pour la communication avec des sockets de
       domaine Unix.
      </para>

      <para>
       Si <productname>PostgreSQL</productname> est compilé sans le support de SSL,
       l'utilisation de l'option <literal>require</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>
     <term><literal>requiressl</literal></term>
     <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>
     <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"/> and <xref linkend="gssapi-auth"/>.)
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <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>
     <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>

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

 <varlistentry>
  <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>,
	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é comme ci-dessus.
      </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <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>
  <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 *PQconnectStart(const char *conninfo);
</synopsis>
<synopsis>PostgresPollingStatusType PQconnectPoll(PGconn *conn);
</synopsis>
</para>
<para>
   Ces deux 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>PQconnectdb</function>, et donc l'application peut gérer des opérations en
   parallèle à d'autres activités.
  </para>
  <para>
   La connexion à la base de données est faite en utilisant les paramètres pris
   dans la chaîne <literal>conninfo</literal>, passée à
   <function>PQconnectStart</function>. Cette chaîne est du même format que
   celle décrite pour <function>PQconnectdb</function>.
  </para>
  <para>
   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>PQconnectdb</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>
   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;:

    <variablelist>
     <varlistentry>
      <term><symbol>CONNECTION_STARTED</symbol></term>
      <listitem>
       <para>
        Attente de la connexion à réaliser.
       </para>
      </listitem>
     </varlistentry> 

     <varlistentry>
      <term><symbol>CONNECTION_MADE</symbol></term>
      <listitem>
       <para>
        Connexion OK&nbsp;; attente d'un envoi.
       </para>
      </listitem>
     </varlistentry>  

     <varlistentry>
      <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
      <listitem>
       <para>
        Attente d'une réponse du serveur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <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>
      <term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
      <listitem>
       <para>
        Négociation du cryptage SSL.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><symbol>CONNECTION_SETENV</symbol></term>
      <listitem>
       <para>
        Négociation des paramétrages de l'environnement.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>

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

 <varlistentry>
  <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;  /* Caractère à afficher pour 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>
  <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>
  <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>
  <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);
</synopsis>
<synopsis>PostgresPollingStatusType PQresetPoll(PGconn *conn);
</synopsis>
</para>

<para>
    Ces fonctions fermeront la connexion au serveur et tenteront de rétablir
    une nouvelle connexion au même serveur en utilisant les mêmes paramètres
    que précédemment. Ceci pourrait être utile en cas de récupération après une
    erreur si une connexion est perdue. Elles diffèrent de
    <function>PQreset</function> (ci-dessus) car elles agissent d'une façon non
    bloquante. Ces fonctions souffrent des mêmes restrictions que
    <function>PQconnectStart</function> et <function>PQconnectPoll</function>.
   </para>
   <para>
    Pour initier une réinitialisation de la connexion, appelez
    <function>PQresetStart</function>. S'il renvoie 0, la réinitialisation a
    échoué. S'il renvoie 1, activez la réinitialisation en utilisant
    <function>PQresetPoll</function> exactement de la même façon que vous
    créeriez la connexion en utilisant <function>PQconnectPoll</function>.
   </para>
  </listitem>
 </varlistentry>

 </variablelist>
</para>
</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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>PQconnectStart</function> et de
       <function>PQconnectPoll</function> en regard aux autres codes de statut, qui
       pourraient être vus.
      </para>
     </listitem>
    </varlistentry>

<varlistentry>
<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>
<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
<literal>server_version</literal>,
<literal>server_encoding</literal>,
<literal>client_encoding</literal>,
<literal>is_superuser</literal>,
<literal>session_authorization</literal>,
<literal>datestyle</literal>,
<literal>TimeZone</literal>,
<literal>integer_datetimes</literal> et
<literal>standard_conforming_strings</literal>.
(<literal>server_encoding</literal>, <literal>TimeZone</literal> et
<literal>integer_datetimes</literal> n'étaient pas rapportés dans les versions
antérieures à la 8.0&nbsp;;
<literal>standard_conforming_strings</literal> n'était pas rapporté dans les versions
antérieures à la 8.1).
Notez que
<literal>server_version</literal>,
<literal>server_encoding</literal> et
<literal>integer_datetimes</literal>
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 <literal>server_version</literal> et
<literal>client_encoding</literal>. 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
<literal>client_encoding</literal> via <command>SET</command> après le lancement de la
connexion, ne seront pas reflétées par <function>PQparameterStatus</function>). Pour
<literal>server_version</literal>, 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 <literal>standard_conforming_strings</literal>,
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>
<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). Ceci 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>
  <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>
     <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> inclura 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>
     <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>
     <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>
     <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>
     <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 fourni par l'appelant. Renvoie false (0) sinon.

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

      </para>

      <para>
       Cette fonction détecte si un mot de passe fourni à la fonction de
       connexion a réellement été utilisé. Les mots de passe obtenus à partir
       d'autres sources (comme le fichier <filename>.pgpass</filename>) ne sont
       pas considérés comme fourni par l'utilisateur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <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>SSL *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>
       Vous pouvez définir <symbol>USE_SSL</symbol> pour obtenir le bon prototype
       de cette fonction. Faire cela inclura automatiquement
       <filename>ssl.h</filename> à partir d'<productname>OpenSSL</productname>.
      </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>
<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.
	  Si un pointeur NULL est renvoyé, il devrait être traité comme un
	  résultat <symbol>PGRES_FATAL_ERROR</symbol>. Utilisez
          <function>PQerrorMessage</function> pour obtenir plus d'informations
          sur l'erreur.
</para>
</listitem>
</varlistentry>
</variablelist>

Inclure plusieurs commandes SQL (séparées par des points virgules) dans la
chaîne de commande est autorisé. 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>
<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>
    </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>
      <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"
endterm="sql-prepare-title"/>. 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"
endterm="sql-deallocate-title"/> peut être utilisée dans ce but.
</para>

<para>
<variablelist>
<varlistentry>
<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>
<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 sir 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 NULL pour
référencer l'instruction non nommée. Sinon, ce doit être le nom d'une instruction
préparée existante. En cas de succès, un <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>
<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 NULL pour
référencer un portail sans nom. Sinon, il doit correspondre au nom d'un portail
existant. En cas de succès, un <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>
<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>
  <term><literal>PGRES_EMPTY_QUERY</literal></term>
  <listitem>
   <para>La chaîne envoyée au serveur était vide.</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <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>
  <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>
  <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>
  <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>
  <term><literal>PGRES_BAD_RESPONSE</literal></term>
  <listitem>
   <para>La réponse du serveur n'a pas été comprise.</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><literal>PGRES_NONFATAL_ERROR</literal></term>
  <listitem>
   <para>Une erreur non fatale (une note ou un avertissement) est
    survenue.</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><literal>PGRES_FATAL_ERROR</literal></term>
  <listitem>
   <para>Une erreur fatale est survenue.</para>
  </listitem>
 </varlistentry>
</variablelist>

Si le statut du résultat est <literal>PGRES_TUPLES_OK</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>, <command>UPDATE</command>, 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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>

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

<varlistentry>
<term><function>PQmakeEmptyPGresult</function><indexterm><primary>PQmakeEmptyPGresult</primary></indexterm></term>
<listitem>
<para>
          Construit un objet <structname>PGresult</structname> vide avec le
          statut donné.
<synopsis>PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
</synopsis>
</para>

<para>
Il s'agit d'une fonction interne de <application>libpq</application> pour allouer et
initialiser un objet <structname>PGresult</structname> vide. Cette fonction
renvoie NULL si la mémoire n'a pas pu être allouée. Il est exporté car
certaines applications la trouvent utiles pour générer eux-même des objets
résultats (particulièrement des objets avec des statuts d'erreur). Si
<parameter>conn</parameter> n'est pas NULL et que <parameter>status</parameter> indique
une erreur, le message d'erreur actuel pour la connexion spécifiée est copié
dans <structname>PGresult</structname>. Notez que <function>PQclear</function>
devrait éventuellement être appelé sur l'objet, comme avec un
<structname>PGresult</structname> renvoyé par <application>libpq</application>
elle-même.
</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>). 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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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 les informations de résultats pour les autres
   commandes</title>

<para>
Ces fonctions sont utilisées pour extraire des informations des objets
<structname>PGresult</structname> qui ne sont pas les résultats d'instructions
<command>SELECT</command>.
</para>

<variablelist>
<varlistentry>
<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>
<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>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>
<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>
<term><function>PQoidStatus</function><indexterm><primary>PQoidStatus</primary></indexterm></term>
<listitem>
<para>
          Renvoie une chaîne avec l'OID de la ligne insérée si la commande
          <acronym>SQL</acronym> était une instruction
	  <command>INSERT</command> qui insère exactement une ligne, ou un
	  <command>EXECUTE</command> d'une instruction préparée consistant en
          une commande <command>INSERT</command> (la chaîne sera <literal>0</literal> si
          l'instruction <command>INSERT</command> n'a inséré qu'une seule ligne
          ou si la table cible n'a pas d'OID). Si la commande n'était pas un
          <command>INSERT</command>, renvoie une chaîne vide.
<synopsis>char * PQoidStatus(const PGresult *res);
</synopsis>
</para>

<para>
Cette fonction est obsolète et remplacée par <function>PQoidValue</function>.
Elle n'est pas compatible avec les threads.
</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>PQescapeStringConn</primary>
   </indexterm>
   <indexterm zone="libpq-exec-escape-string">
    <primary>PQescapeString</primary>
   </indexterm>
   <indexterm zone="libpq-exec-escape-string">
    <primary>chaînes d'échappement</primary>
    <secondary>dans libpq</secondary>
   </indexterm>

<para>
<function>PQescapeStringConn</function> échappe une chaîne à utiliser dans une
commande SQL. Ceci est utile lors de l'insertion de valeurs comme constantes
littérales. Certains caractères (tels que les guillemets et les antislashs)
doivent être échappés pour les empêcher d'être interprétés spécialement par
l'analyseur SQL. <function>PQescapeStringConn</function> réalise cette opération.
</para>

<tip>
<para>
Il est tout particulièrement important de faire cet échappement proprement lors
de la gestion de chaînes reçues d'une source non sûre. Sinon, il existe un
risque de sécurité&nbsp;: vous êtes vulnérable à une attaque par
<quote>injection de SQL</quote> où des commandes SQL non souhaitées
remplissent votre base de données.
</para>
</tip>

<para>
Notez qu'il n'est ni nécessaire ni correct de faire un échappement
lorsque une valeur est passée comme paramètre séparé dans
<function>PQexecParams</function> ou ses routines similaires.

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

<para>
<function>PQescapeStringConn</function> écrit une version échappée de la chaîne
<parameter>from</parameter> dans le tampon <parameter>to</parameter>, en échappant les
caractères spéciaux de façon à ce qu'ils ne puissent causer aucun problème,
et en ajoutant un octet nul de terminaison. Les guillemets simples qui
doivent entourer les chaînes <productname>PostgreSQL</productname> ne sont pas
incluses dans la chaîne résultante&nbsp;; ils doivent être fournis dans la
commande SQL où le résultat sera inséré.
Le paramètre <parameter>from</parameter> pointe le premier caractère d'une chaîne à
protéger et le paramètre <parameter>length</parameter> donne le nombre d'octets
dans cette chaîne. Un octet de terminaison, zéro, n'est pas requis et ne
devrait pas être compté dans <parameter>length</parameter> (si un octet de terminaison
est trouvé avant que <parameter>length</parameter> octets ne soient traités,
<function>PQescapeStringConn</function> s'arrête au zéro&nbsp;; le comportement ressemble
donc à <function>strncpy</function>). <parameter>to</parameter> devrait pointer
vers un tampon capable de contenir au moins un octet de plus que le double de
la valeur de <parameter>length</parameter>, sinon le comportement est indéfini.
Le comportement est indéfini si les chaînes <parameter>to</parameter> et
<parameter>from</parameter> se surchargent.
</para>
<para>
Si le paramètre <parameter>error</parameter> n'est pas NULL, alors
<literal>*error</literal> est initialisé à zéro en cas de succès et à une valeur
différente de zéro dans le cas contraire. Actuellement, les seules conditions
d'erreurs possibles impliquent un codage multi-octets invalide dans la chaîne
en entrée. La chaîne en sortie est toujours générée en cas d'erreur mais il est
probable que le serveur la rejettera en indiquant qu'elle est malformée. En cas
d'erreur, un message adéquat est stocké dans l'objet <parameter>conn</parameter>,
que <parameter>error</parameter> soit NULL ou non.
</para>
<para>
<function>PQescapeString</function> renvoie le nombre d'octets écrits dans
<parameter>to</parameter>, sans inclure l'octet de terminaison.
</para>

<para>
<synopsis>size_t PQescapeString (char *to, const char *from, size_t length);</synopsis>
</para>

<para>
<function>PQescapeString</function> est une version obsolète de
<function>PQescapeStringConn</function>&nbsp;; la différence réside dans le fait
qu'elle ne prend pas de paramètres <parameter>conn</parameter> ou <parameter>error</parameter>.
À cause de ceci, elle ne peut ajuster son comportement suivant les propriétés
de la connexion comme le codage des caractères et donc <emphasis>elle pourrait
renvoyer des résultats faux</emphasis>. De plus, il n'existe aucun moyen de renvoyer
les conditions de l'erreur.
</para>
<para>
<function>PQescapeString</function> peut être utilisé sereinement dans les programmes
clients à un seul thread et fonctionnant avec une seule connexion
<productname>PostgreSQL</productname> à la fois (dans ce cas, il peut trouver les informations
qui l'intéressent <quote>en arrière-plan</quote>). Les autres contextes devraient être
évités et <function>PQescapeStringConn</function> devrait être utilisé à la place.
</para>
</sect2>


 <sect2 id="libpq-exec-escape-bytea">
  <title>Échapper des chaînes binaires pour une inclusion dans des commandes
   SQL</title>

  <indexterm zone="libpq-exec-escape-bytea">
   <primary>bytea</primary>
   <secondary sortas="libpq">dans libpq</secondary>
  </indexterm>

  <variablelist>
  <varlistentry>
  <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 (mais
   toutes les valeurs d'octets <emphasis>peuvent</emphasis> être échappées)
   lorsqu'elles font partie d'un littéral <type>bytea</type> dans une
   instruction <acronym>SQL</acronym>. En général, pour échapper un octet, il
   est converti dans le nombre à trois chiffres correspondant à sa valeur
   octale et précédé habituellement par deux antislashs. Le guillemet simple et le caractère
   antislash ont des séquences d'échappements alternatives. Voir la <xref
   linkend="datatype-binary"/> pour plus d'informations.
   <function>PQescapeByteaConn</function> réalise cette opération en échappant
   seulement les octets requis.
  </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>
  <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>. À cause de ceci, il ne peut ajuster son comportement
   suivant les propriétés de la connexion (en particulier si les chaînes
   conformes au standard sont activées) et, du coup, <emphasis>il pourrait
   donner de mauvais résultats</emphasis>. De plus, il n'a aucun moyen de renvoyer un
   message d'erreur en cas d'échec.
  </para>

  <para>
   <function>PQescapeBytea</function> peut être utilisé en toute sécurité dans les
   programmes clients avec un seul thread et fonctionnant avec une seule
   connexion <productname>PostgreSQL</productname> en même temps (dans ce cas, il peut
   trouver ce dont il a besoin de savoir <quote>en arrière-plan</quote>). Dans
   d'autres contextes, il devrait être remplacé par <function>PQescapeByteaConn</function>.
  </para>
  </listitem>
  </varlistentry>

  <varlistentry>
  <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 NULL 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>

  <varlistentry>
  <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 soit utilisée sur
   Microsoft Windows à la place de <function>free()</function>. Ceci est dû
   au fait qu'une allocation de mémoire dans une DLL et à sa libération dans
   l'application ne fonctionne que si les options multithread/monothread,
   release/debug et statique/dynamique sont identiques pour la DLL et pour
   l'application. Sur les autres plateformes que Microsoft Windows, cette
   fonction est identique à celle de la bibliothèque standard,
   <function>free()</function>.
  </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>
</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>
<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>
<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>
  <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>
<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>
<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>
<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>
<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> ou
          <function>PQsendQueryPrepared</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>
</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). 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>
<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>
<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>
 <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>
<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>
<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-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>
      <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 NULL si le
            paramètre <parameter>conn</parameter> donné est NULL 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>
        <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>
         <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>
    <term><function>PQrequestCancel</function>
    <indexterm><primary>PQrequestCancel</primary></indexterm></term>
    <listitem>
      <para>
        Demande que le serveur abandonne le traitement de la commande en
        cours.
<synopsis>int PQrequestCancel(PGconn *conn);
</synopsis>
      </para>
  
      <para>
        <function>PQrequestCancel</function> est une variante obsolète de
        <function>PQcancel</function>. 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 une notification particulière avec 
la commande <command>LISTEN</command> (et peut arrêter son écoute avec la
commande <command>UNLISTEN</command>). Toutes les sessions écoutant une
condition particulière seront notifiées de façon asynchrone lorsqu'une commande
<command>NOTIFY</command> avec ce nom de condition sera exécutée par une
session. Aucune autre information n'est passée du notifieur au notifié. Du
coup, typiquement, toute donnée qui a besoin d'être communiquée est transférée
via une table de la base. D'habitude, le nom de la condition est identique à la
table associée mais il n'est pas nécessaire d'avoir une table associée.
</para>

<para>
Les applications <application>libpq</application> soumettent les commandes
<command>LISTEN</command> et <command>UNLISTEN</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 de la condition de la notification */
    int  be_pid;                /* ID du processus serveur notifiant */
    char *extra;                /* paramètre de 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
(actuellement, le champ <structfield>extra</structfield> est inutilisé et
pointera en permanence vers une chaîne vide).
</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>
<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>
<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" endterm="sql-copy-title"/> pour plus
                d'informations.
</para>
</listitem>
</varlistentry>

<varlistentry>
<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>
<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" endterm="sql-copy-title"/>
pour des détails.
</para>
</listitem>
</varlistentry>

<varlistentry>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
    <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>
    <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>
<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>
<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>
<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>
<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>
</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-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> initialise le nom du serveur de la base de données. S'il
commence avec une barre oblique, il spécifie une communication de domaine Unix
plutôt qu'une communication TCP/IP&nbsp;; la valeur est le nom du répertoire où
le fichier socket est stocké (dans une installation par défaut, cela serait
<filename>/tmp</filename>).
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGHOSTADDR</envar></primary>
</indexterm>
<envar>PGHOSTADDR</envar> spécifie l'adresse IP numérique du serveur de la base
de données. Elle peut être initialisée avec <envar>PGHOST</envar> pour éviter
la surcharge des recherches DNS. Voir la documentation de ces paramètres, dans
<function>PQconnectdb</function> ci-dessus, pour des détails sur leur
interaction.
</para>
<para>
Quand ni <envar>PGHOST</envar> ni <envar>PGHOSTADDR</envar> n'est initialisé,
le comportement par défaut est de se connecter en utilisant un socket de domaine
Unix&nbsp;; ou sur les machines sans sockets de domaine Unix,
<application>libpq</application> essaiera de se connecter à
<literal>localhost</literal>.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGPORT</envar></primary>
</indexterm>
<envar>PGPORT</envar> initialise le numéro de port TCP ou l'extension du
fichier socket de domaine Unix pour la communication avec le serveur
<productname>PostgreSQL</productname>.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGDATABASE</envar></primary>
</indexterm>
<envar>PGDATABASE</envar>  initialise le nom de la base de données sous
<productname>PostgreSQL</productname>.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGUSER</envar></primary>
</indexterm>
<envar>PGUSER</envar> initialise le nom de l'utilisateur se connectant à la
base de données.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGPASSWORD</envar></primary>
</indexterm>
<envar>PGPASSWORD</envar> initialise le mot de passe utilisé si le serveur
demande une authentification par mot de passe. 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> initialise le nom du service à recherche dans
<filename>pg_service.conf</filename>. Cela offre un raccourci pour la
configuration de tous les paramètres.
</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> initialise les options d'exécution supplémentaires
pour le serveur <productname>PostgreSQL</productname>.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGSSLMODE</envar></primary>
</indexterm>
<envar>PGSSLMODE</envar> détermine si et avec quelle priorité une connexion
<acronym>SSL</acronym> sera négociée avec le serveur. Il existe quatre modes&nbsp;:
<literal>disable</literal> tentera seulement une connexion non cryptée, donc sans
<acronym>SSL</acronym>&nbsp;; <literal>allow</literal> négociera en commençant par une
connexion non <acronym>SSL</acronym> puis, s'il échoue, tentera une connexion
<acronym>SSL</acronym>&nbsp;; <literal>prefer</literal> (la valeur par défaut) négociera en
commençant  par une connexion <acronym>SSL</acronym> puis, en cas d'échec, essaiera
une connexion non <acronym>SSL</acronym>&nbsp;; <literal>require</literal> essaiera seulement
une connexion <acronym>SSL</acronym>. Si <productname>PostgreSQL</productname> est compilé sans
le support de SSL, utiliser l'option <literal>require</literal> générera une erreur
bien que les options <literal>allow</literal> et <literal>prefer</literal> seront acceptées
mais, en fait, <application>libpq</application> ne tentera pas de connexion <acronym>SSL</acronym>.
</para>
</listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGREQUIRESSL</envar></primary>
</indexterm>
<envar>PGREQUIRESSL</envar> initialise une connexion via
<acronym>SSL</acronym>. S'il est initialisé à
<quote>1</quote>, <application>libpq</application> refusera de se connecter si le serveur
n'accepte pas de connexion <acronym>SSL</acronym> (équivalent à un
<literal>sslmode</literal> valant <literal>prefer</literal>). Cette option est obsolète et
laisse la place au paramétrage <literal>sslmode</literal>. Elle est seulement disponible
si <productname>PostgreSQL</productname> est compilé avec le support de SSL.
</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>PGKRBSRVNAME</envar></primary>
</indexterm>
<envar>PGKRBSRVNAME</envar> configure le nom du service Kerberos à utiliser
lors de l'authentification avec Kerberos 5 ou GSSAPI.
</para>
</listitem>

    <listitem>
     <para>
      <indexterm>
       <primary><envar>PGGSSLIB</envar></primary>
      </indexterm>
      <envar>PGGSSLIB</envar> configure la bibliothèque GSS pour qu'elle
      utilise l'authentification GSSAPI.
     </para>
    </listitem>
<listitem>
<para>
<indexterm>
 <primary><envar>PGCONNECT_TIMEOUT</envar></primary>
</indexterm>
<envar>PGCONNECT_TIMEOUT</envar> initialise le nombre de secondes maximum que
<application>libpq</application> attendra pour une connexion au serveur
<productname>PostgreSQL</productname>. Si non initialisée ou si valant zéro,
<application>libpq</application> attendra indéfiniment. Il n'est pas recommandé
d'initialiser le délai à moins de deux secondes.
</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-alteruser" endterm="sql-alteruser-title"/> et
<xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title"/>
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>PGCLIENTENCODING</envar></primary>
</indexterm>
<envar>PGCLIENTENCODING</envar> initialise le codage de l'ensemble des
caractères par défaut
(équivalent à <literal>SET client_encoding 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" endterm="sql-set-title"/> 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>.
      </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> 
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. </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>

<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>
Pour utiliser cette fonctionnalité, copiez le fichier
<filename>share/pg_service.conf.sample</filename> dans
<filename>etc/pg_service.conf</filename> et renommez le fichier pour ajouter
les noms de service et paramètres. Ce fichier peut aussi être utilisé pour les
installations avec seulement le client. L'emplacement du fichier peut être
indiqué par la variable d'environnement <envar>PGSYSCONFDIR</envar>.
</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
<synopsis>
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
</synopsis>
amènera l'exécution de l'URL LDAP suivante&nbsp;:
<synopsis>
ldap://ldap.masociété.com/dc=masociété,dc=com?uniqueMember?one?(cn=mabase)
</synopsis>
</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;:
   <synopsis>
    # 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=*)
   </synopsis>
  </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>

  <para>
   Pour vérifier que le certificat du serveur est de confiance, placez les
   certificats des autorités (<acronym>CA</acronym>) de confiance dans le
   fichier <filename>~/.postgresql/root.crt</filename> dans le répertoire
   personnel de l'utilisateur.
   (Sur Microsoft Windows, le fichier est nommé
   <filename>%APPDATA%\postgresql\root.crt</filename>.)
   <application>libpq</application> vérifiera ensuite que le certificat du
   serveur est signé par une des autorités de confiance. La connexion SSL
   échouera si le serveur ne présente pas un certificat de confiance.
   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>
   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 sauf si la clé secrète du certificat est stocké
   dans un jeton matériel, comme spécifié dans <envar>PGSSLKEY</envar>. (Sur
   Microsoft Windows, ces fichiers sont nommés
   <filename>%APPDATA%\postgresql\postgresql.crt</filename> et
   <filename>%APPDATA%\postgresql\postgresql.key</filename>.) Le fichier de
   clé privée ne doit pas être lisible par tout le monde.
  </para>

  <para>
   Si la variable d'environnement <envar>PGSSLKEY</envar> est configuré, sa
   valeur doit consister d'un nom de moteur et d'un identifiant clé séparés par
   une virgule. Dans ce cas, <application>libpq</application> chargera le moteur
   indiqué, c'est-à-dire le module <productname>OpenSSL</productname> qui
   supporte un matériel spécial et référence la clé avec l'identifiant
   indiqué. Les identifiants sont spécifiques au moteur. Typiquement, les
   jetons d'un matériel de chiffrement ne révèlent pas les clés secrètes à
   l'application. À la place, les applications délèguent les opérations
   cryptographiques qui nécessitent la clé secrète du jeton matériel.
  </para>

  <para>
   Si vous utilisez <acronym>SSL</acronym> dans votre application (ainsi que dans
   <application>libpq</application>), vous pouvez utiliser
   <function>PQinitSSL(int)</function> pour indiquer à <application>libpq</application>
   que la bibliothèque <acronym>SSL</acronym> a déjà été initialisée par votre
   application.
   <!-- 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 des détails sur l'API SSL.
  </para>

  <table id="libpq-ssl-file-usage">
   <title>Utilisation du fichier 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>

</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 si
l'option en ligne de commande de <filename>configure</filename>,
<literal>--enable-thread-safety</literal>, a été utilisée lors de la construction de
PostgreSQL. De plus, 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>
<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.
</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>
      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>
      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>/*
 * testlibpq.c
 *
 *      Test the C version of libpq, the PostgreSQL frontend library.
 */
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#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 &gt; 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 &lt; nFields; i++)
        printf("%-15s", PQfname(res, i));
    printf("\n\n");

    /* next, print out the rows */
    for (i = 0; i &lt; PQntuples(res); i++)
    {
        for (j = 0; j &lt; 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>/*
 * 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 &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;errno.h&gt;
#include &lt;sys/time.h&gt;
#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 &gt; 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 &lt; 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 &lt; 0)
            break;              /* shouldn't happen */

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

        if (select(sock + 1, &amp;input_mask, NULL, NULL, NULL) &lt; 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-&gt;relname, notify-&gt;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>/*
 * 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 &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;sys/types.h&gt;
#include "libpq-fe.h"

/* for ntohl/htonl */
#include &lt;netinet/in.h&gt;
#include &lt;arpa/inet.h&gt;


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 &lt; 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 &lt; 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 &gt; 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 *) &amp;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>