.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PERLXS 1"
.TH PERLXS 1 "2005-04-10" "DocFr" "User Contributed Perl Documentation"
.SH "NOM"
.IX Header "NOM"
perlxs \- Manuel de référence du langage \s-1XS\s0
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Sh "Introduction"
.IX Subsection "Introduction"
\&\s-1XS\s0 est un langage utilisé pour réaliser une interface d'extension
entre Perl et une librairie C qu'on souhaite utiliser depuis
Perl. L'interface \s-1XS\s0 est combinée avec la librairie pour produire une
nouvelle librairie susceptible d'être liée avec Perl. Une \fB\s-1XSUB\s0\fR est
une fonction écrite dans le langage \s-1XS\s0 ; c'est le composant central de
l'interface de l'application Perl.
.PP
Le compilateur \s-1XS\s0 s'appelle \fBxsubpp\fR. Ce compilateur insère les
constructions nécessaires pour permettre à une \s-1XSUB\s0, qui n'est autre
qu'une fonction C déguisée, de manipuler des valeurs Perl, et crée la
colle nécessaire pour permettre à Perl d'accéder à la \s-1XSUB\s0. Le
compilateur utilise des \fBtypemaps\fR pour faire la correspondance entre
les variables et les paramètres de fonction C d'une part, et les
valeurs Perl de l'autre. Le typemap par défaut gère de nombreux types
C parmi les plus courants. Un typemap supplémentaire doit être créé
pour traiter les structures et les types spécifiques à la librairie
que l'on veut lier dans Perl.
.PP
Consultez perlxstut pour un guide d'apprentissage du processus de
création d'extensions dans son ensemble.
.PP
Note : pour beaucoup d'extensions, le système \s-1SWIG\s0 de Dave Beazley
fournit un mécanisme nettement plus pratique pour réaliser le code de
liaison \s-1XS\s0. Voyez http://www.cs.utah.edu/~beazley/SWIG pour plus
d'information.
.Sh "Mise en route"
.IX Subsection "Mise en route"
La plupart des exemples qui suivent portent sur la création d'une
interface entre Perl et les fonctions de la librairie de connexion
\&\s-1ONC+\s0 \s-1RPC\s0. La fonction \fIrpcb_gettime()\fR sera utilisée pour illustrer de
nombreuses caractéristiques du langage \s-1XS\s0. Cette fonction accepte deux
paramètres ; le premier est une donnée en entrée et le second une
donnée en sortie. La fonction renvoie aussi une valeur d'état.
.PP
.Vb 1
\&        bool_t rpcb_gettime(const char *host, time_t *timep);
.Ve
.PP
Depuis C, cette fonction est appelée avec les instructions suivantes.
.PP
.Vb 4
\&     #include <rpc/rpc.h>
\&     bool_t status;
\&     time_t timep;
\&     status = rpcb_gettime( "localhost", &timep );
.Ve
.PP
Si on réalise une \s-1XSUB\s0 offrant une traduction directe entre cette
fonction et Perl, cette \s-1XSUB\s0 sera utilisée depuis Perl avec le code
suivant. Les variables \f(CW$status\fR et \f(CW$timep\fR contiendront la sortie de
cette fonction.
.PP
.Vb 2
\&     use RPC;
\&     $status = rpcb_gettime( "localhost", $timep );
.Ve
.PP
Le fichier \s-1XS\s0 suivant présente une sous-routine \s-1XS\s0, ou \s-1XSUB\s0, proposant
un exemple d'interface avec la fonction \fIrpcb_gettime()\fR. Cette \s-1XSUB\s0
représente une traduction directe entre C et Perl et préserve donc
l'interface même depuis Perl. Cette \s-1XSUB\s0 sera appelée depuis Perl de
la même manière que ci\-dessus. Notez que les trois premières
instructions #include, pour \f(CW\*(C`EXTERN.h\*(C'\fR, \f(CW\*(C`perl.h\*(C'\fR et \f(CW\*(C`XSUB.h\*(C'\fR,
seront tout le temps présentes au début d'un fichier \s-1XS\s0. On élargira
plus tard cette approche, et on en présentera d'autres.
.PP
.Vb 4
\&     #include "EXTERN.h"
\&     #include "perl.h"
\&     #include "XSUB.h"
\&     #include <rpc/rpc.h>
.Ve
.PP
.Vb 1
\&     MODULE = RPC  PACKAGE = RPC
.Ve
.PP
.Vb 6
\&     bool_t
\&     rpcb_gettime(host,timep)
\&          char *host
\&          time_t &timep
\&          OUTPUT:
\&          timep
.Ve
.PP
Toutes les extensions à Perl, y compris celles qui contiennent des
\&\s-1XSUB\s0, doivent être accompagnées d'un module Perl d'amorçage
(angl. bootstrap) qui assure l'intégration de l'extension dans
Perl. Ce module exporte les fonctions et les variables de l'extension
vers le programme Perl et entraîne la liaison entre les \s-1XSUB\s0 de
l'extension et Perl. Le module qui suit sera utilisé dans la plupart
des exemples de ce document ; il doit être utilisé depuis Perl avec la
commande \f(CW\*(C`use\*(C'\fR comme on l'a vu précédemment. On approfondira l'étude
des modules Perl plus loin dans ce document.
.PP
.Vb 1
\&     package RPC;
.Ve
.PP
.Vb 4
\&     require Exporter;
\&     require DynaLoader;
\&     @ISA = qw(Exporter DynaLoader);
\&     @EXPORT = qw( rpcb_gettime );
.Ve
.PP
.Vb 2
\&     bootstrap RPC;
\&     1;
.Ve
.PP
Tout au long de ce document, diverses interfaces à la \s-1XSUB\s0
\&\fIrpcb_gettime()\fR seront explorées. L'ordre ou le nombre des paramètres
pris par les \s-1XSUB\s0 variera. Dans chaque cas, la \s-1XSUB\s0 est une
abstraction entre Perl et la vraie fonction C \fIrpcb_gettime()\fR, et la
\&\s-1XSUB\s0 doit toujours s'assurer que la vraie fonction \fIrpcb_gettime()\fR est
appelée avec les bons paramètres. Cette abstraction permettra au
programmeur de réaliser une interface avec la fonction C plus proche
de Perl.
.Sh "Anatomie d'une \s-1XSUB\s0"
.IX Subsection "Anatomie d'une XSUB"
La \s-1XSUB\s0 qui suit permet à un programme Perl d'accéder à une fonction
de librairie C dont le nom est \fIsin()\fR. La \s-1XSUB\s0 fait comme la fonction
C, qui prend un seul paramètre et renvoie une valeur unique.
.PP
.Vb 3
\&     double
\&     sin(x)
\&       double x
.Ve
.PP
Lorsqu'on utilise des pointeurs C, l'opérateur d'indirection \f(CW\*(C`*\*(C'\fR
devrait être considéré comme une partie du type et l'opérateur
d'addressage \f(CW\*(C`&\*(C'\fR comme une partie de la variable, comme on l'a fait
dans la fonction \fIrpcb_gettime()\fR ci\-dessus. Consultez la section sur
les typemaps pour avoir plus de détails sur l'utilisation des
qualificateurs et des opérateurs unaires dans les types C.
.PP
Le nom de la fonction et le type de retour doivent être placés sur des
lignes séparées.
.PP
.Vb 1
\&  INCORRECT                        CORRECT
.Ve
.PP
.Vb 3
\&  double sin(x)                    double
\&    double x                       sin(x)
\&                                     double x
.Ve
.PP
Le corps de la fonction peut être mis en retrait ou ajusté à
gauche. L'exemple suivant montre une fonction dont le corps est ajusté
à gauche. On utilisera un retrait dans la plupart des exemples de ce
document.
.PP
.Vb 1
\&  CORRECT
.Ve
.PP
.Vb 3
\&  double
\&  sin(x)
\&  double
.Ve
.Sh "La pile des arguments"
.IX Subsection "La pile des arguments"
La pile des arguments est utilisée pour stocker les valeurs qui sont
envoyées à la \s-1XSUB\s0 en tant que paramètres, ainsi que la valeur de
retour de la \s-1XSUB\s0. En fait, toutes les fonctions Perl mettent leurs
valeurs sur cette pile en même temps, chacune étant limitée à son
propre intervalle de positions sur la pile. Dans ce document, la
première position dans la pile appartenant à la fonction active sera
désignée comme la position 0 pour cette fonction.
.PP
Les \s-1XSUB\s0 se réfèrent à leurs arguments de la pile avec la macro
\&\fB\s-1ST\s0(x)\fR, où \fIx\fR désigne une position dans l'intervalle appartenant à
la \s-1XSUB\s0 sur la pile. La position 0 pour cette fonction est connue de
la \s-1XSUB\s0 comme \s-1\fIST\s0\fR\|(0). Les paramètres en entrée et les valeurs de retour
de la \s-1XSUB\s0 commencent toujours à \s-1\fIST\s0\fR\|(0). Dans de nombreux cas simples,
le compilateur \fBxsubpp\fR générera le code nécessaire à la manipulation
de la pile des arguments en insérant des morceaux de code trouvés dans
les typemaps. Dans les cas plus complexes, le programmeur devra
fournir le code.
.Sh "La variable \s-1RETVAL\s0"
.IX Subsection "La variable RETVAL"
La variable \s-1RETVAL\s0 est une variable magique qui est toujours du type
retourné par la fonction de la librairie C. Le compilateur \fBxsubpp\fR
fournit cette variable dans chaque \s-1XSUB\s0 et l'utilise par défaut pour y
mettre la valeur de retour de la fonction C appelée. Dans les cas
simples, la valeur de \s-1RETVAL\s0 sera mise dans \s-1\fIST\s0\fR\|(0) sur la pile
d'arguments, où Perl le recevra comme valeur de retour de la \s-1XSUB\s0.
.PP
Si la \s-1XSUB\s0 a un type de retour égal à \f(CW\*(C`void\*(C'\fR, le compilateur ne
fournira pas de variable \s-1RETVAL\s0 pour cette fonction. Lorsqu'on utilise
la directive \s-1PPCODE:\s0, la variable \s-1RETVAL\s0 n'est plus nécessaire, sauf
si on l'utilise explicitement.
.PP
Si la directive \s-1PPCODE:\s0 n'est pas utilisée, la valeur de retour
\&\f(CW\*(C`void\*(C'\fR devrait être utilisée uniquement pour des sous-routines qui ne
renvoient pas de valeur, \fImême si\fR la directive \s-1CODE:\s0 est utilisée
pour positionner \s-1\fIST\s0\fR\|(0) explicitement.
.PP
Dans des versions plus anciennes de ce document, on conseillait
d'utiliser la valeur de retour \f(CW\*(C`void\*(C'\fR dans de tels cas. On a
découvert que cela pouvait mener à des segfaults lorsque la \s-1XSUB\s0 était
\&\fIvraiment\fR \f(CW\*(C`void\*(C'\fR. Cette pratique est maintenant désapprouvée, et
risque de ne plus être supportée dans une version future. Utilisez la
valeur de retour \f(CW\*(C`SV *\*(C'\fR dans ces cas\-là (\f(CW\*(C`xsubpp\*(C'\fR contient
actuellement du code heuristique qui tente de faire la différence
entre les fonctions \*(L"vraiment\-void\*(R" et celles qui sont
\&\*(L"déclarées\-void\-suivant\-l'ancienne\-pratique\*(R" ; votre code est donc à
la merci de l'heuristique si vous n'utilisez pas \f(CW\*(C`SV *\*(C'\fR comme valeur
de retour).
.Sh "Le mot\-clé \s-1MODULE\s0"
.IX Subsection "Le mot-clé MODULE"
Le mot\-clé \s-1MODULE\s0 est utilisé pour marquer le début du code \s-1XS\s0 et
spécifier un paquetage pour les fonctions que l'on est en train de
définir. Tout le texte qui précède le premier mot\-clé \s-1MODULE\s0 est
considéré comme du code C et sera transféré dans la sortie du
compilateur sans modification. Tout module \s-1XS\s0 aura une fonction
d'initialisation utilisée pour brancher la \s-1XSUB\s0 dans Perl. Le nom du
paquetage de cette fonction d'initialisation correspondra à la valeur
de la dernière instruction \s-1MODULE\s0 dans les fichiers source \s-1XS\s0. La
valeur de \s-1MODULE\s0 devrait toujours rester constante à l'intérieur d'un
même fichier \s-1XS\s0, même si cela n'est pas obligatoire.
.PP
L'exemple suivant démarre le code \s-1XS\s0 et place toutes les fonctions
dans un paquetage nommé \s-1RPC\s0.
.PP
.Vb 1
\&     MODULE = RPC
.Ve
.Sh "Le mot\-clé \s-1PACKAGE\s0"
.IX Subsection "Le mot-clé PACKAGE"
Lorsque les fonctions, à l'intérieur d'un fichier source \s-1XS\s0, doivent
être réparties dans des paquetages, il faut utiliser le mot\-clé
\&\s-1PACKAGE\s0. Ce mot\-clé est utilisé avec le mot\-clé \s-1MODULE\s0 et doit être
spécifié immédiatement après lui.
.PP
.Vb 1
\&     MODULE = RPC  PACKAGE = RPC
.Ve
.PP
.Vb 1
\&     [ code XS dans le paquetage RPC ]
.Ve
.PP
.Vb 1
\&     MODULE = RPC  PACKAGE = RPCB
.Ve
.PP
.Vb 1
\&     [ code XS dans le paquetage RPCB ]
.Ve
.PP
.Vb 1
\&     MODULE = RPC  PACKAGE = RPC
.Ve
.PP
.Vb 1
\&     [ code XS dans le paquetage RPC ]
.Ve
.PP
Bien que ce mot\-clé soit optionnel et qu'il fournisse des informations
redondantes dans certains cas, il devrait toujours être utilisé. Il
permet de garantir que la \s-1XSUB\s0 apparaîtra dans le paquetage désiré.
.Sh "Le mot\-clé \s-1PREFIX\s0"
.IX Subsection "Le mot-clé PREFIX"
Le mot\-clé \s-1PREFIX\s0 désigne des préfixes à supprimer dans les noms de
fonction Perl. Si la fonction C est \f(CW\*(C`rpcb_gettime()\*(C'\fR et que la valeur
de \s-1PREFIX\s0 est \f(CW\*(C`rpcb_\*(C'\fR, Perl devra voir cette fonction comme
\&\f(CW\*(C`gettime()\*(C'\fR.
.PP
Ce mot\-clé suit le mot\-clé \s-1PACKAGE\s0 lorsqu'il est utilisé. Si \s-1PACKAGE\s0
n'est pas utilisé, alors \s-1PREFIX\s0 suit le mot\-clé \s-1MODULE\s0.
.PP
.Vb 1
\&     MODULE = RPC  PREFIX = rpc_
.Ve
.PP
.Vb 1
\&     MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_
.Ve
.Sh "Le mot\-clé \s-1OUTPUT\s0"
.IX Subsection "Le mot-clé OUTPUT"
Le mot\-clé \s-1OUTPUT:\s0 indique qu'il faut mettre à jour certains paramètres
de fonction (en rendant les nouvelles valeurs accessibles à Perl)
lorsque la \s-1XSUB\s0 se termine, ou que certaines valeurs doivent être
renvoyées à la fonction Perl. Pour des fonctions simples, comme la
fonction \fIsin()\fR ci\-dessus, la variable \s-1RETVAL\s0 est désignée
automatiquement comme une valeur en sortie. Dans des fonctions plus
complexes, le compilateur \fBxsubpp\fR aura besoin d'aide pour déterminer
quelles variables sont des variables en sortie.
.PP
Ce mot\-clé sera utilisé normalement en complément du mot\-clé
\&\s-1CODE:\s0. La variable \s-1RETVAL\s0 n'est pas reconnue comme une variable en
sortie lorsque le mot\-clé \s-1CODE:\s0 est présent. Le mot\-clé \s-1OUTPUT:\s0 est
utilisé dans cette situation pour dire au compilateur que \s-1RETVAL\s0 est
réellement une variable en sortie.
.PP
Le mot\-clé \s-1OUTPUT:\s0 peut aussi être utilisé pour indiquer que des
paramètres de fonction sont des variables en sortie. Cela peut être
nécessaire lorsqu'un paramètre a été modifié à l'intérieur d'une
fonction et que le programmeur veut que cette modification soit
visible depuis Perl.
.PP
.Vb 6
\&     bool_t
\&     rpcb_gettime(host,timep)
\&          char *host
\&          time_t &timep
\&          OUTPUT:
\&          timep
.Ve
.PP
Le mot\-clé \s-1OUTPUT:\s0 permet aussi à un paramètre en sortie d'être relié
à un morceau de code correspondant plutôt qu'à un typemap.
.PP
.Vb 6
\&     bool_t
\&     rpcb_gettime(host,timep)
\&          char *host
\&          time_t &timep
\&          OUTPUT:
\&          timep sv_setnv(ST(1), (double)timep);
.Ve
.PP
\&\fBxsubpp\fR rajoute automatiquement un \f(CW\*(C`SvSETMAGIC()\*(C'\fR pour tous les
paramètres de la section \s-1OUTPUT\s0 de la \s-1XSUB\s0, sauf pour \s-1RETVAL\s0. C'est le
comportement désiré la plupart du temps, car il se charge d'invoquer
convenablement l'effet 'set' (angl. \*(L"set magic\*(R") sur les données en
sortie (ce qui est nécessaire pour les éléments de tableau simple ou
de tableau associatif passés en paramètre, qui doivent être créés
s'ils n'existent pas). Si, pour une raison donnée, ce comportement
n'est pas désiré, la section \s-1OUTPUT\s0 peut contenir une ligne
\&\f(CW\*(C`SETMAGIC: DISABLE\*(C'\fR qui le désactive pour le restant des paramètres
de la section \s-1OUTPUT:\s0. De même, \f(CW\*(C`SETMAGIC: ENABLE\*(C'\fR peut être utilisé
pour le réactiver pour le restant de la section \s-1OUTPUT\s0. Voyez
perlguts pour plus de détails sur l'effet 'set'.
.Sh "Le mot\-clé \s-1CODE\s0"
.IX Subsection "Le mot-clé CODE"
Ce mot\-clé est utilisé dans des \s-1XSUB\s0 plus complexes qui nécessitent un
traitement spécial pour la fonction C. La variable \s-1RETVAL\s0 est
disponible, mais elle ne sera pas retournée, sauf si elle est
spécifiée sous le mot\-clé \s-1OUTPUT:\s0.
.PP
La \s-1XSUB\s0 qui suit correspond à une fonction C qui requiert un
traitement spécial de ses paramètres. L'utilisation depuis Perl est
donnée en premier.
.PP
.Vb 1
\&     $status = rpcb_gettime( "localhost", $timep );
.Ve
.PP
Voici la \s-1XSUB\s0.
.PP
.Vb 9
\&     bool_t
\&     rpcb_gettime(host,timep)
\&          char *host
\&          time_t timep
\&          CODE:
\&               RETVAL = rpcb_gettime( host, &timep );
\&          OUTPUT:
\&          timep
\&          RETVAL
.Ve
.Sh "Le mot\-clé \s-1INIT\s0"
.IX Subsection "Le mot-clé INIT"
Le mot\-clé \s-1INIT:\s0 permet d'insérer du code d'initialisation dans la
\&\s-1XSUB\s0 avant que le compilateur ne génère l'appel à la fonction
C. Contrairement au mot\-clé \s-1CODE:\s0 ci\-dessus, celui-ci n'affecte pas la
manière dont le compilateur traite \s-1RETVAL\s0.
.PP
.Vb 8
\&    bool_t
\&    rpcb_gettime(host,timep)
\&          char *host
\&          time_t &timep
\&          INIT:
\&          printf("# l'hote est %s\en", host );
\&          OUTPUT:
\&          timep
.Ve
.Sh "Le mot\-clé \s-1NO_INIT\s0"
.IX Subsection "Le mot-clé NO_INIT"
Le mot\-clé NO-INIT sert à indiquer qu'on utilise un paramètre de la
fonction uniquement comme valeur en sortie. Le compilateur \fBxsubpp\fR
génère normalement du code pour lire les valeurs de tous les
paramètres de la fonction sur la pile des arguments, et pour les
assigner à des variables C lors de l'entrée dans la fonction. \s-1NO_INIT\s0
dit au compilateur que certains paramètres seront utilisés en sortie
plutôt qu'en entrée, et qu'ils seront traités avant la fin de la
fonction.
.PP
L'exemple suivant présente une variante de la fonction
\&\fIrpcb_gettime()\fR. Cette fonction utilise la variable timep uniquement
comme variable en sortie, et ne se préoccupe pas de son contenu
initial.
.PP
.Vb 6
\&     bool_t
\&     rpcb_gettime(host,timep)
\&          char *host
\&          time_t &timep = NO_INIT
\&          OUTPUT:
\&          timep
.Ve
.Sh "Initialisation des arguments de fonction"
.IX Subsection "Initialisation des arguments de fonction"
Normalement, les paramètres de fonction sont initialisés avec les
valeurs qu'ils ont dans la pile des arguments. Les typemaps
contiennent les portions de code utilisées pour transférer les valeurs
Perl dans des paramètres C. Le programmeur, toutefois, est autorisé à
surcharger les typemaps et à fournir un code d'initialisation
différent (ou supplémentaire).
.PP
Le code qui suit montre comment fournir du code d'initialisation pour
les paramètres de fonction. Le code d'initialisation est évalué entre
des guillemets par le compilateur (en utilisant \fIeval()\fR), avant d'être
inséré dans le code généré, de sorte que toute expression devant être
interprétée littéralement (essentiellement \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR ou \f(CW\*(C`\e\*(C'\fR) doit
être protégée par des \f(CW\*(C`\e\*(C'\fR. Les variables \f(CW$var\fR, \f(CW$arg\fR et \f(CW$type\fR
peuvent être utilisées comme dans les typemaps.
.PP
.Vb 6
\&     bool_t
\&     rpcb_gettime(host,timep)
\&          char *host = (char *)SvPV($arg,PL_na);
\&          time_t &timep = 0;
\&          OUTPUT:
\&          timep
.Ve
.PP
Ce procédé ne devrait pas être utilisé pour fournir des valeurs par
défaut aux paramètres. Le cas normal d'utilisation est celui où un
paramètre de fonction doit être traité par une autre fonction de la
librairie avant d'être utilisé. Les paramètres par défaut font l'objet
de la prochaine section.
.PP
Si l'initialisation commence par \f(CW\*(C`=\*(C'\fR, elle sera insérée sur la même
ligne que la déclaration de la variable. Si elle commence par \f(CW\*(C`;\*(C'\fR ou
\&\f(CW\*(C`+\*(C'\fR, elle sera insérée une fois que toutes les variables en entrée
auront été déclarées. Les cas \f(CW\*(C`=\*(C'\fR et \f(CW\*(C`;\*(C'\fR remplacent l'initialisation
fournie normalement par le typemap. Dans le cas \f(CW\*(C`+\*(C'\fR, l'initialisation
du typemap précédera le code d'initialisation qui suit le \f(CW\*(C`+\*(C'\fR. Une
variable globale, \f(CW%v\fR, est disponible pour le cas vraiment rare où
une initialisation a besoin d'une information venant d'une autre
initialisation.
.PP
.Vb 6
\&     bool_t
\&     rpcb_gettime(host,timep)
\&          time_t &timep ; /*\e$v{time}=@{[$v{time}=$arg]}*/
\&          char *host + SvOK($v{time}) ? SvPV($arg,PL_na) : NULL;
\&          OUTPUT:
\&          timep
.Ve
.Sh "Valeurs de paramètres par défaut"
.IX Subsection "Valeurs de paramètres par défaut"
On peut donner des valeurs par défaut à des paramètres de fonction en
rajoutant une instruction d'affectation dans la liste des
paramètres. La valeur par défaut peut être un nombre ou une chaîne de
caractères. Les valeurs par défaut doivent toujours être utilisées
uniquement pour les paramètres les plus à droite.
.PP
Afin de permettre à la \s-1XSUB\s0 de \fIrpcb_gettime()\fR d'avoir un hôte par
défaut, les paramètres de la \s-1XSUB\s0 pourraient être réordonnés. La \s-1XSUB\s0
appellera alors la vraie fonction \fIrpcb_gettime()\fR avec les paramètres
placés dans le bon ordre. Perl appellera cette \s-1XSUB\s0 avec l'une des
instructions suivantes.
.PP
.Vb 1
\&     $status = rpcb_gettime( $timep, $host );
.Ve
.PP
.Vb 1
\&     $status = rpcb_gettime( $timep );
.Ve
.PP
La \s-1XSUB\s0 ressemblera au code qui suit. Un bloc \s-1CODE:\s0 est utilisé pour
appeler la vraie fonction \fIrpcb_gettime()\fR avec les paramètres remis
dans l'ordre correct pour cette fonction.
.PP
.Vb 9
\&     bool_t
\&     rpcb_gettime(timep,host="localhost")
\&          char *host
\&          time_t timep = NO_INIT
\&          CODE:
\&               RETVAL = rpcb_gettime( host, &timep );
\&          OUTPUT:
\&          timep
\&          RETVAL
.Ve
.Sh "Le mot\-clé \s-1PREINIT\s0"
.IX Subsection "Le mot-clé PREINIT"
Le mot\-clé \s-1PREINIT:\s0 permet de déclarer des variables supplémentaires
avant que les typemaps soient utilisés. Si une variable est déclarée
dans un bloc \s-1CODE:\s0, elle suivra tout code généré par le typemap. Cela
peut provoquer des fautes de syntaxe en C. Pour forcer la déclaration
de la variable avant le code du typemap, placez-la dans un bloc
\&\s-1PREINIT:\s0. Le mot\-clé \s-1PREINIT:\s0 peut être utilisé une ou plusieurs fois
à l'intérieur d'une \s-1XSUB\s0.
.PP
Les exemples qui suivent sont équivalents, mais, si le code utilise
des typemaps complexes, le premier exemple sera plus sûr.
.PP
.Vb 10
\&     bool_t
\&     rpcb_gettime(timep)
\&          time_t timep = NO_INIT
\&          PREINIT:
\&          char *host = "localhost";
\&          CODE:
\&          RETVAL = rpcb_gettime( host, &timep );
\&          OUTPUT:
\&          timep
\&          RETVAL
.Ve
.PP
Un exemple correct, mais avec des risques d'erreur.
.PP
.Vb 9
\&     bool_t
\&     rpcb_gettime(timep)
\&          time_t timep = NO_INIT
\&          CODE:
\&          char *host = "localhost";
\&          RETVAL = rpcb_gettime( host, &timep );
\&          OUTPUT:
\&          timep
\&          RETVAL
.Ve
.Sh "Le mot\-clé \s-1SCOPE\s0"
.IX Subsection "Le mot-clé SCOPE"
Le mot\-clé \s-1SCOPE:\s0 permet d'activer un niveau spécial de visibilité
(angl. scoping) pour une \s-1XSUB\s0 donnée. Dans ce cas\-là, la \s-1XSUB\s0
invoquera \s-1ENTER\s0 et \s-1LEAVE\s0 automatiquement (Note du Traducteur : les
macros \s-1ENTER\s0 et \s-1LEAVE\s0 sont décrites dans perlcall).
.PP
Afin de supporter des correspondances de type complexes, ce niveau
spécial sera activé automatiquement pour une \s-1XSUB\s0 si elle utilise une
entrée de typemap contenant le commentaire \f(CW\*(C`/*scope*/\*(C'\fR.
.PP
Pour activer ce niveau spécial :
.PP
.Vb 1
\&     SCOPE: ENABLE
.Ve
.PP
Pour le désactiver :
.PP
.Vb 1
\&     SCOPE: DISABLE
.Ve
.Sh "Le mot\-clé \s-1INPUT\s0"
.IX Subsection "Le mot-clé INPUT"
Habituellement, les paramètres de \s-1XSUB\s0 sont évalués juste après
l'entrée dans la \s-1XSUB\s0. Le mot\-clé \s-1INPUT:\s0 peut être utilisé pour forcer
ces paramètres à être évalués un peu plus tard. On peut utiliser le
mot\-clé \s-1INPUT:\s0 plusieurs fois dans une \s-1XSUB\s0, et ceci pour une ou
plusieurs variables en entrée. Ce mot\-clé accompagne le mot\-clé
\&\s-1PREINIT:\s0.
.PP
L'exemple suivant montre comment l'évaluation du paramètre en entrée
\&\f(CW\*(C`timep\*(C'\fR peut être retardée, après un \s-1PREINIT\s0.
.PP
.Vb 13
\&    bool_t
\&    rpcb_gettime(host,timep)
\&          char *host
\&          PREINIT:
\&          time_t tt;
\&          INPUT:
\&          time_t timep
\&          CODE:
\&               RETVAL = rpcb_gettime( host, &tt );
\&               timep = tt;
\&          OUTPUT:
\&          timep
\&          RETVAL
.Ve
.PP
Dans cet autre exemple, chacun des paramètres en entrée voit son
évaluation retardée.
.PP
.Vb 17
\&    bool_t
\&    rpcb_gettime(host,timep)
\&          PREINIT:
\&          time_t tt;
\&          INPUT:
\&          char *host
\&          PREINIT:
\&          char *h;
\&          INPUT: 
\&          time_t timep
\&          CODE:
\&               h = host;
\&               RETVAL = rpcb_gettime( h, &tt );
\&               timep = tt;
\&          OUTPUT:
\&          timep
\&          RETVAL
.Ve
.Sh "Listes de paramètres de longueur variable"
.IX Subsection "Listes de paramètres de longueur variable"
Les \s-1XSUB\s0 peuvent recevoir des listes de paramètres de longueur
variable en spécifiant une ellipse \f(CW\*(C`...\*(C'\fR dans la liste des
paramètres. Cette utilisation de l'ellipse est similaire à celle que
l'on trouve en C \s-1ANSI\s0. Le programmeur peut déterminer le nombre
d'arguments passés à la \s-1XSUB\s0 en examinant la variable \f(CW\*(C`items\*(C'\fR que le
compilateur \fBxsubpp\fR fournit pour chaque \s-1XSUB\s0. Grâce à ce mécanisme,
on peut réaliser une \s-1XSUB\s0 qui accepte une liste de paramètres de
longueur indéterminée.
.PP
Le paramètre \fIhost\fR de la \s-1XSUB\s0 \fIrpcb_gettime()\fR peut être optionnel, de
manière à ce qu'on puisse utiliser l'ellipse pour indiquer que la \s-1XSUB\s0
prendra un nombre variable de paramètres. Perl devrait pouvoir appeler
cette \s-1XSUB\s0 avec chacune des instructions suivantes.
.PP
.Vb 1
\&     $status = rpcb_gettime( $timep, $host );
.Ve
.PP
.Vb 1
\&     $status = rpcb_gettime( $timep );
.Ve
.PP
Voici le code \s-1XS\s0, avec l'ellipse :
.PP
.Vb 12
\&     bool_t
\&     rpcb_gettime(timep, ...)
\&          time_t timep = NO_INIT
\&          PREINIT:
\&          char *host = "localhost";
\&          CODE:
\&                  if( items > 1 )
\&                       host = (char *)SvPV(ST(1), PL_na);
\&                  RETVAL = rpcb_gettime( host, &timep );
\&          OUTPUT:
\&          timep
\&          RETVAL
.Ve
.Sh "Le mot\-clé C_ARGS"
.IX Subsection "Le mot-clé C_ARGS"
Le mot\-clé C_ARGS permet de réaliser des \s-1XSUB\s0 que l'on n'appelle pas
de la même manière depuis Perl que depuis C, sans qu'il soit
nécessaire d'écrire une section \s-1CODE:\s0 ou \s-1PPCODE:\s0. Le contenu du
paragraphe C_ARGS est passé comme argument à la fonction C, sans aucun
changement.
.PP
Supposons par exemple que la fonction C soit déclarée ainsi :
.PP
.Vb 1
\&    symbolic nth_derivative(int n, symbolic function, int flags);
.Ve
.PP
et que la valeur par défaut de \fIflags\fR soit contenue dans la variable
C \fIdefault_flags\fR. Supposons que vous souhaitiez réaliser une
interface que l'on appellera de la manière suivante :
.PP
.Vb 1
\&    $second_deriv = $function->nth_derivative(2);
.Ve
.PP
Pour cela, déclarez la \s-1XSUB\s0 ainsi :
.PP
.Vb 6
\&    symbolic
\&    nth_derivative(function, n)
\&        symbolic        function
\&        int             n
\&    C_ARGS:
\&        n, function, default_flags
.Ve
.Sh "Le mot\-clé \s-1PPCODE\s0"
.IX Subsection "Le mot-clé PPCODE"
Le mot\-clé \s-1PPCODE:\s0 est une variante du mot\-clé \s-1CODE:\s0 qui est utilisée
pour indiquer au compilateur \fBxsubpp\fR que le programmeur fournit le
code contrôlant la pile des arguments pour les valeurs de retour des
\&\s-1XSUB\s0. On souhaite parfois que la \s-1XSUB\s0 renvoie une liste de valeurs et
non une valeur unique. Dans ce cas\-là, il faut utiliser \s-1PPCODE:\s0 et
rajouter de manière explicite la liste des valeurs sur la pile. Les
mots\-clés \s-1PPCODE:\s0 et \s-1CODE:\s0 ne sont pas utilisés simultanément dans la
même \s-1XSUB\s0.
.PP
La \s-1XSUB\s0 suivante appelle la fonction C \fIrpcb_gettime()\fR et renvoie à Perl
ses deux valeurs de sortie, timep et status, comme une seule liste.
.PP
.Vb 11
\&     void
\&     rpcb_gettime(host)
\&          char *host
\&          PREINIT:
\&          time_t  timep;
\&          bool_t  status;
\&          PPCODE:
\&          status = rpcb_gettime( host, &timep );
\&          EXTEND(SP, 2);
\&          PUSHs(sv_2mortal(newSViv(status)));
\&          PUSHs(sv_2mortal(newSViv(timep)));
.Ve
.PP
Remarquez que le programmeur doit fournir le code C assurant l'appel
de la vraie fonction \fIrpcb_gettime()\fR, ainsi que le placement correct
des valeurs de retour sur la pile des arguments.
.PP
Le type de retour \f(CW\*(C`void\*(C'\fR pour cette fonction indique au compilateur
\&\fBxsubpp\fR que la variable \s-1RETVAL\s0 n'est pas nécessaire, qu'elle n'est
pas utlisée, et qu'elle ne devrait pas être créée. Dans la plupart des
cas, il faut utiliser le type de retour void avec l'instruction
\&\s-1PPCODE:\s0.
.PP
On utilise la macro \s-1\fIEXTEND\s0()\fR afin de dégager de la place sur la pile
des arguments pour les 2 valeurs de retour. L'instruction \s-1PPCODE:\s0 fait
en sorte que le compilateur \fBxsubpp\fR crée un pointeur vers la pile
dans la variable \f(CW\*(C`SP\*(C'\fR ; c'est ce pointeur qui est utilisé dans la
macro \s-1\fIEXTEND\s0()\fR. Les valeurs sont ensuite rajoutées sur la pile avec
les macros \fIPUSHs()\fR.
.PP
A présent, la fonction \fIrpcb_gettime()\fR peut être utilisée depuis Perl
avec l'instruction suivante.
.PP
.Vb 1
\&     ($status, $timep) = rpcb_gettime("localhost");
.Ve
.PP
Lorsque vous travaillez sur les paramètres en sortie avec une section
\&\s-1PPCODE:\s0, assurez-vous de traiter l'effet 'set'
convenablement. Consultez perlguts pour plus de détails sur cet
effet 'set'.
.Sh "Renvoyer undef et des listes vides"
.IX Subsection "Renvoyer undef et des listes vides"
Le programmeur voudra parfois renvoyer simplement \f(CW\*(C`undef\*(C'\fR ou une
liste vide si la fonction échoue, plutôt qu'une valeur d'état à
part. La fonction \fIrpcb_gettime()\fR présente justement cette
situation. Nous aimerions que la fonction retourne l'heure si elle
réussit, ou undef si elle échoue. Dans le code Perl suivant, la valeur
de \f(CW$timep\fR sera soit undef, soit une heure valide;
.PP
.Vb 1
\&     $timep = rpcb_gettime( "localhost" );
.Ve
.PP
La \s-1XSUB\s0 suivante n'utilise le type de retour \f(CW\*(C`SV *\*(C'\fR qu'à titre
d'aide\-mémoire, et il utilise un bloc \s-1CODE:\s0 pour indiquer au
compilateur que le programmeur a fourni tout le code
nécessaire. L'appel de \fIsv_newmortal()\fR initialise la valeur de retour à
undef, ce qui en fait la valeur de retour par défaut.
.PP
.Vb 10
\&     SV *
\&     rpcb_gettime(host)
\&          char *  host
\&          PREINIT:
\&          time_t  timep;
\&          bool_t x;
\&          CODE:
\&          ST(0) = sv_newmortal();
\&          if( rpcb_gettime( host, &timep ) )
\&               sv_setnv( ST(0), (double)timep);
.Ve
.PP
Cet autre exemple montre comment on peut mettre un undef explicite
dans la valeur de retour, au cas où le besoin s'en ferait ressentir.
.PP
.Vb 14
\&     SV *
\&     rpcb_gettime(host)
\&          char *  host
\&          PREINIT:
\&          time_t  timep;
\&          bool_t x;
\&          CODE:
\&          ST(0) = sv_newmortal();
\&          if( rpcb_gettime( host, &timep ) ){
\&               sv_setnv( ST(0), (double)timep);
\&          }
\&          else{
\&               ST(0) = &PL_sv_undef;
\&          }
.Ve
.PP
Pour renvoyer une liste vide, il faut utiliser un bloc \s-1PPCODE:\s0 et ne
pas rajouter de valeur de retour sur la pile.
.PP
.Vb 12
\&     void
\&     rpcb_gettime(host)
\&          char *host
\&          PREINIT:
\&          time_t  timep;
\&          PPCODE:
\&          if( rpcb_gettime( host, &timep ) )
\&               PUSHs(sv_2mortal(newSViv(timep)));
\&          else{
\&          /* Rien n'est remis sur la pile, donc une */
\&          /* liste vide est renvoyee implicitement */
\&          }
.Ve
.PP
Certaines personnes préfèrent rajouter un \f(CW\*(C`return\*(C'\fR explicite dans la
\&\s-1XSUB\s0 ci-dessus au lieu de laisser l'exécution se poursuivre jusqu'au
bout. Dans ce cas\-là, il convient plutôt d'utiliser \f(CW\*(C`XSRETURN_EMPTY\*(C'\fR,
ce qui garantira que la pile \s-1XSUB\s0 est ajustée correctement. D'autres
macros sont décrites dans perlguts.
.Sh "Le mot\-clé \s-1REQUIRE\s0"
.IX Subsection "Le mot-clé REQUIRE"
Le mot\-clé \s-1REQUIRE:\s0 sert à indiquer le numéro de version minimal du
compilateur \fBxsubpp\fR requis pour compiler le module \s-1XS\s0. Un module \s-1XS\s0
contenant l'instruction suivante ne pourra être compilé qu'avec une
version de \fBxsubpp\fR égale ou supérieure à 1.922 :
.PP
.Vb 1
\&        REQUIRE: 1.922
.Ve
.Sh "Le mot\-clé \s-1CLEANUP\s0"
.IX Subsection "Le mot-clé CLEANUP"
Ce mot\-clé peut être utilisé quand une \s-1XSUB\s0 doit exécuter des
procédures de nettoyage spéciales avant de se terminer. Quand le
mot\-clé \s-1CLEANUP:\s0 est utilisé, il doit suivre tout bloc \s-1CODE:\s0, \s-1PPCODE:\s0
ou \s-1OUTPUT:\s0 présent dans la \s-1XSUB\s0. Les instructions spécifiées dans le bloc de
nettoyage seront les dernières instructions de la \s-1XSUB\s0.
.Sh "Le mot\-clé \s-1BOOT\s0"
.IX Subsection "Le mot-clé BOOT"
Le mot\-clé \s-1BOOT:\s0 permet de rajouter du code dans la fonction
d'amorçage de l'extension.  La fonction d'amorçage est générée par le
compilateur \fBxsubpp\fR et contient normalement les instructions
nécessaires pour enregistrer toute \s-1XSUB\s0 auprès de Perl. Avec le
mot\-clé \s-1BOOT:\s0, le programmeur peut dire au compilateur de rajouter des
instructions supplémentaires dans la fonction d'amorçage.
.PP
Ce mot\-clé peut être utilisé n'importe quand après le premier mot\-clé
\&\s-1MODULE\s0, et doit être tout seul sur une ligne. La première ligne
blanche après le mot\-clé terminera le bloc de code.
.PP
.Vb 4
\&     BOOT:
\&     # Le message suivant sera affiche lors de l'execution de la
\&     # fonction d'amorcage.
\&     printf("bonjour !\en");
.Ve
.Sh "Le mot\-clé \s-1VERSIONCHECK\s0"
.IX Subsection "Le mot-clé VERSIONCHECK"
Le mot\-clé \s-1VERSIONCHECK:\s0 correspond aux options \f(CW\*(C`\-versioncheck\*(C'\fR et
\&\f(CW\*(C`\-noversioncheck\*(C'\fR de \fBxsubpp\fR. Ce mot\-clé prime sur les options de
la ligne de commande. La vérification de version est activée par
défaut. Lorsqu'elle est activée, le module \s-1XS\s0 essaie de vérifier que
son numéro de version est compatible avec celui du module \s-1PM\s0.
.PP
Pour activer la vérification de version :
.PP
.Vb 1
\&    VERSIONCHECK: ENABLE
.Ve
.PP
Pour la désactiver :
.PP
.Vb 1
\&    VERSIONCHECK: DISABLE
.Ve
.Sh "Le mot\-clé \s-1PROTOTYPES\s0"
.IX Subsection "Le mot-clé PROTOTYPES"
Le mot\-clé \s-1PROTOTYPES:\s0 correspond aux options \f(CW\*(C`\-prototypes\*(C'\fR et
\&\f(CW\*(C`\-noprototypes\*(C'\fR de \fBxsubpp\fR. Ce mot\-clé prime sur les options de la
ligne de commande. Les prototypes sont activés par défaut. Lorsqu'ils
sont activés, les \s-1XSUB\s0 reçoivent des prototypes Perl. Ce mot\-clé peut
être utilisé plusieurs fois dans un module \s-1XS\s0 pour activer et
désactiver les prototypes dans différentes parties du module.
.PP
Pour activer les prototypes :
.PP
.Vb 1
\&    PROTOTYPES: ENABLE
.Ve
.PP
Pour les désactiver :
.PP
.Vb 1
\&    PROTOTYPES: DISABLE
.Ve
.Sh "Le mot\-clé \s-1PROTOTYPE\s0"
.IX Subsection "Le mot-clé PROTOTYPE"
Ce mot\-clé est proche du mot\-clé \s-1PROTOTYPES:\s0 ci\-dessus, mais peut être
utilisé pour forcer \fBxsubpp\fR à utiliser un prototype donné pour la
\&\s-1XSUB\s0. Ce mot\-clé prime sur toute autre option ou mot\-clé relatif au
prototypage, mais n'affecte que la \s-1XSUB\s0 courante. Consultez
\&\*(L"Prototypes\*(R" in perlsub pour plus d'informations sur les prototypes
Perl.
.PP
.Vb 13
\&    bool_t
\&    rpcb_gettime(timep, ...)
\&          time_t timep = NO_INIT
\&          PROTOTYPE: $;$
\&          PREINIT:
\&          char *host = "localhost";
\&          CODE:
\&                  if( items > 1 )
\&                       host = (char *)SvPV(ST(1), PL_na);
\&                  RETVAL = rpcb_gettime( host, &timep );
\&          OUTPUT:
\&          timep
\&          RETVAL
.Ve
.Sh "Le mot\-clé \s-1ALIAS\s0"
.IX Subsection "Le mot-clé ALIAS"
Le mot\-clé \s-1ALIAS:\s0 permet à une \s-1XSUB\s0 de recevoir plusieurs noms en
Perl, et de déterminer lequel de ces noms a été utilisé pour
l'invoquer. Les noms en Perl peuvent être complets avec le nom du
paquetage. Chaque alias reçoit un numéro. Le compilateur crée une
variable nommée \f(CW\*(C`ix\*(C'\fR qui contient le numéro de l'alias
utilisé. Lorsque le nom utilisé pour invoquer la \s-1XSUB\s0 est celui avec
lequel il a été déclaré, \f(CW\*(C`ix\*(C'\fR est égal à 0.
.PP
L'exemple suivant crée des alias \f(CW\*(C`FOO::gettime()\*(C'\fR et \f(CW\*(C`BAR::gettit()\*(C'\fR
pour cette fonction.
.PP
.Vb 11
\&    bool_t
\&    rpcb_gettime(host,timep)
\&          char *host
\&          time_t &timep
\&          ALIAS:
\&            FOO::gettime = 1
\&            BAR::getit = 2
\&          INIT:
\&          printf("# ix = %d\en", ix );
\&          OUTPUT:
\&          timep
.Ve
.Sh "Le mot\-clé \s-1INTERFACE\s0"
.IX Subsection "Le mot-clé INTERFACE"
Ce mot\-clé déclare que la \s-1XSUB\s0 courante sert à garder en réserve la
signature de fonction indiquée. S'il est suivi par du texte, ce texte
est considéré comme une liste de fonctions qui ont cette signature, et
qui doivent être attachées à des \s-1XSUB\s0.
.PP
Par exemple, si vous avez 4 fonctions \fImultiply()\fR, \fIdivide()\fR, \fIadd()\fR et
\&\fIsubtract()\fR, toutes avec la signature
.PP
.Vb 1
\&    symbolic f(symbolic, symbolic);
.Ve
.PP
vous pouvez les implémenter toutes à la fois avec la \s-1XSUB\s0
.PP
.Vb 7
\&    symbolic
\&    interface_s_ss(arg1, arg2)
\&        symbolic        arg1
\&        symbolic        arg2
\&    INTERFACE:
\&        multiply divide
\&        add subtract
.Ve
.PP
L'avantage de cette approche par rapport au mot\-clé \s-1ALIAS:\s0 est que
l'on peut attacher une fonction supplémentaire \fIremainder()\fR lors de
l'exécution en utilisant
.PP
.Vb 3
\&    CV *mycv = newXSproto("Symbolic::remainder",
\&                          XS_Symbolic_interface_s_ss, __FILE__, "$$");
\&    XSINTERFACE_FUNC_SET(mycv, remainder);
.Ve
.PP
(on suppose dans cet exemple qu'il n'y a pas de section
\&\s-1INTERFACE_MACRO:\s0, car il faut alors utiliser autre chose que
\&\f(CW\*(C`XSINTERFACE_FUNC_SET\*(C'\fR)
.Sh "Le mot\-clé \s-1INTERFACE_MACRO\s0"
.IX Subsection "Le mot-clé INTERFACE_MACRO"
Ce mot\-clé permet de définir une \s-1INTERFACE\s0 qui procède d'une manière
différente pour récupérer dans la \s-1XSUB\s0 un pointeur vers la fonction
C. Le texte qui suit ce mot\-clé doit indiquer des noms de macros à
utiliser pour récupérer le pointeur de fonction ou pour l'initialiser
dans la \s-1XSUB\s0. La macro de récupération reçoit le type de retour,
\&\f(CW\*(C`CV*\*(C'\fR, et \f(CW\*(C`XSANY.any_dptr\*(C'\fR pour ce \f(CW\*(C`CV*\*(C'\fR. La macro d'initialisation
reçoit cv et le pointeur de fonction.
.PP
Les valeurs par défaut de ces macros sont \f(CW\*(C`XSINTERFACE_FUNC\*(C'\fR et
\&\f(CW\*(C`XSINTERFACE_FUNC_SET\*(C'\fR. Le mot\-clé \s-1INTERFACE\s0 avec une liste vide de
fonctions peut être omis si \s-1INTERFACE_MACRO\s0 est utilisé.
.PP
Supposons que, dans l'exemple qui précède, des pointeurs de fonction
pour \fImultiply()\fR, \fIdivide()\fR, \fIadd()\fR, et \fIsubtract()\fR soient conservés dans
un tableau C global \f(CW\*(C`fp[]\*(C'\fR, les positions de ces pointeurs par
rapport au début du tableau étant contenues dans des variables nommées
\&\f(CW\*(C`multiply_off\*(C'\fR, \f(CW\*(C`divide_off\*(C'\fR, \f(CW\*(C`add_off\*(C'\fR, \f(CW\*(C`subtract_off\*(C'\fR. On peut
alors utiliser
.PP
.Vb 4
\&    #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \e
\&        ((XSINTERFACE_CVT(ret,))fp[CvXSUBANY(cv).any_i32])
\&    #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \e
\&        CvXSUBANY(cv).any_i32 = CAT2( f, _off )
.Ve
.PP
dans la section C, et
.PP
.Vb 10
\&    symbolic
\&    interface_s_ss(arg1, arg2)
\&        symbolic        arg1
\&        symbolic        arg2
\&    INTERFACE_MACRO:
\&        XSINTERFACE_FUNC_BYOFFSET
\&        XSINTERFACE_FUNC_BYOFFSET_set
\&    INTERFACE:
\&        multiply divide
\&        add subtract
.Ve
.PP
dans la section \s-1XSUB\s0.
.Sh "Le mot\-clé \s-1INCLUDE\s0"
.IX Subsection "Le mot-clé INCLUDE"
Ce mot\-clé peut être utilisé pour insérer d'autres fichiers dans le
module \s-1XS\s0. Les autres fichiers peuvent contenir du code \s-1XS\s0. \s-1INCLUDE:\s0
peut aussi être utilisé pour exécuter une commande générant du code \s-1XS\s0
à insérer dans le module.
.PP
Le fichier \fIRpcb1.xsh\fR contient notre fonction \f(CW\*(C`rpcb_gettime()\*(C'\fR :
.PP
.Vb 6
\&    bool_t
\&    rpcb_gettime(host,timep)
\&          char *host
\&          time_t &timep
\&          OUTPUT:
\&          timep
.Ve
.PP
Le module \s-1XS\s0 peut utiliser \s-1INCLUDE:\s0 pour insérer ce fichier.
.PP
.Vb 1
\&    INCLUDE: Rpcb1.xsh
.Ve
.PP
Si les paramètres du mot\-clé \s-1INCLUDE:\s0 sont suivis d'un trait vertical
(\f(CW\*(C`|\*(C'\fR), alors le compilateur interprétera les paramètres comme une
commande.
.PP
.Vb 1
\&    INCLUDE: cat Rpcb1.xsh |
.Ve
.Sh "Le mot\-clé \s-1CASE\s0"
.IX Subsection "Le mot-clé CASE"
Le mot\-clé \s-1CASE\s0 permet à une \s-1XSUB\s0 de se subdiviser en plusieurs
parties distinctes, chacune se comportant comme une \s-1XSUB\s0
virtuelle. \s-1CASE:\s0 est global à la \s-1XSUB\s0 : quand on l'utilise, il faut
mettre tous les autres mots\-clés \s-1XS\s0 à l'intérieur d'un \s-1CASE:\s0. Cela
signifie que rien ne peut précéder le premier \s-1CASE:\s0 dans la \s-1XSUB\s0, et
que tout code suivant le dernier \s-1CASE:\s0 y est incorporé.
.PP
Un \s-1CASE:\s0 peut être associé à une condition sur un paramètre de la \s-1XSUB\s0
en utilisant la variable-alias \f(CW\*(C`ix\*(C'\fR (voir \*(L"Le mot\-clé \s-1ALIAS:\s0\*(R"), ou
éventuellement la variable \f(CW\*(C`items\*(C'\fR (voir \*(L"Listes de paramètres de longueur variable\*(R"). Le dernier \s-1CASE\s0 correspond au mot\-clé \fBdefault\fR
en C s'il n'est associé à aucune condition. L'exemple suivant montre
un \s-1CASE\s0 dépendant de \f(CW\*(C`ix\*(C'\fR dans la fonction \f(CW\*(C`rpcb_gettime()\*(C'\fR,
laquelle a pour alias \f(CW\*(C`x_gettime()\*(C'\fR. Lorsque la fonction est invoquée
sous le nom \f(CW\*(C`rpcb_gettime()\*(C'\fR, elle reçoit les paramètres habituels
\&\f(CW\*(C`(char *host, time_t *timep)\*(C'\fR, tandis que, lorsque elle est invoquée
en tant que \f(CW\*(C`x_gettime()\*(C'\fR, ses paramètres sont inversés, \f(CW\*(C`(time_t
*timep, char *host)\*(C'\fR.
.PP
.Vb 21
\&    long
\&    rpcb_gettime(a,b)
\&      CASE: ix == 1
\&          ALIAS:
\&          x_gettime = 1
\&          INPUT:
\&          # 'a' est timep, 'b' est host
\&          char *b
\&          time_t a = NO_INIT
\&          CODE:
\&               RETVAL = rpcb_gettime( b, &a );
\&          OUTPUT:
\&          a
\&          RETVAL
\&      CASE:
\&          # 'a' est host, 'b' est timep
\&          char *a
\&          time_t &b = NO_INIT
\&          OUTPUT:
\&          b
\&          RETVAL
.Ve
.PP
Cette fonction peut être appelée avec chacune des instructions
suivantes. Notez la différence dans l'ordre des arguments.
.PP
.Vb 1
\&        $status = rpcb_gettime( $host, $timep );
.Ve
.PP
.Vb 1
\&        $status = x_gettime( $timep, $host );
.Ve
.Sh "L'opérateur unaire &"
.IX Subsection "L'opérateur unaire &"
L'opérateur unaire & est utilisé pour dire au compilateur qu'il doit
déréférencer l'objet lors de l'appel à la fonction C. On utilise ce
procédé lorsqu'on n'a pas mis de bloc \s-1CODE:\s0 et que l'objet n'est pas
de type pointeur (l'objet est un \f(CW\*(C`int\*(C'\fR ou un \f(CW\*(C`long\*(C'\fR, mais pas un
\&\f(CW\*(C`int*\*(C'\fR ni un \f(CW\*(C`long*\*(C'\fR).
.PP
La \s-1XSUB\s0 suivante génère du code C incorrect. Le code généré par
\&\fBxsubpp\fR appellera \f(CW\*(C`rpcb_gettime()\*(C'\fR avec les paramètres \f(CW\*(C`(char
*host, time_t timep)\*(C'\fR, mais le vrai \f(CW\*(C`rpcb_gettime()\*(C'\fR attend un
paramètre \f(CW\*(C`timep\*(C'\fR de type \f(CW\*(C`time_t *\*(C'\fR et non \f(CW\*(C`time_t\*(C'\fR.
.PP
.Vb 6
\&    bool_t
\&    rpcb_gettime(host,timep)
\&          char *host
\&          time_t timep
\&          OUTPUT:
\&          timep
.Ve
.PP
On résout ce problème en utilisant l'opérateur \f(CW\*(C`&\*(C'\fR. Le compilateur
\&\fBxsubpp\fR, à présent, traduira la \s-1XSUB\s0 en code qui appellera
\&\f(CW\*(C`rpcb_gettime()\*(C'\fR de manière correcte, avec les paramètres \f(CW\*(C`(char
*host, time_t *timep)\*(C'\fR. Il le fait en conservant le \f(CW\*(C`&\*(C'\fR tel quel, de
sorte que l'appel de fonction est \f(CW\*(C`rpcb_gettime(host, &timep)\*(C'\fR.
.PP
.Vb 6
\&    bool_t
\&    rpcb_gettime(host,timep)
\&          char *host
\&          time_t &timep
\&          OUTPUT:
\&          timep
.Ve
.Sh "Insérer des commentaires et des directives de pré\-processeur C"
.IX Subsection "Insérer des commentaires et des directives de pré-processeur C"
Des directives de pré\-processeur C peuvent prendre place à l'intérieur
des blocs \s-1BOOT:\s0, \s-1PREINIT:\s0, \s-1INIT:\s0, \s-1CODE:\s0, \s-1PPCODE:\s0 et \s-1CLEANUP:\s0, de même
qu'en dehors des fonctions. Les commentaires sont autorisés partout
après le mot\-clé \s-1MODULE\s0. Le compilateur transmet les directives de
pré\-processeur sans modification et supprime les lignes commentées.
.PP
On peut rajouter des commentaires dans les \s-1XSUB\s0 en mettant un \f(CW\*(C`#\*(C'\fR sur
une ligne comme premier caractère non blanc. Attention, le commentaire
ne doit pas ressembler à une directive de pré\-processeur C, sinon il
sera interprété comme tel. Le moyen le plus simple d'éviter cela
consiste à mettre des caractères blancs devant le \f(CW\*(C`#\*(C'\fR.
.PP
Si vous utilisez des directives de pré\-processeur pour choisir entre
deux versions d'une fonction, utilisez
.PP
.Vb 3
\&    #if ... version1
\&    #else /* ... version2  */
\&    #endif
.Ve
.PP
et non pas
.PP
.Vb 4
\&    #if ... version1
\&    #endif
\&    #if ... version2
\&    #endif
.Ve
.PP
car, dans le second cas, xsubpp croira que vous avez défini la
fonction deux fois. Par ailleurs, insérez une ligne blanche avant le
\&\f(CW\*(C`#else\*(C'\fR et le \f(CW\*(C`#endif\*(C'\fR afin qu'ils ne soient pas considérés comme une
partie intégrante du corps de la fonction.
.Sh "Utiliser \s-1XS\s0 avec \*(C+"
.IX Subsection "Utiliser XS avec "
Si une fonction est définie comme une méthode \*(C+, alors elle
considère son premier argument comme un pointeur vers un objet. Le
pointeur vers l'objet est stocké dans une variable nommée
\&\s-1THIS\s0. L'objet doit avoir été créé en \*(C+ avec la fonction \fInew()\fR, et il
doit être béni par Perl (comme avec la fonction \fIbless()\fR en Perl pur)
avec la macro \fIsv_setref_pv()\fR. La \fIbénédiction\fR d'un objet par Perl
peut être effectuée par le typemap. Un exemple de typemap est donné à
la fin de cette section.
.PP
Si la méthode est définie comme statique, elle appellera la fonction \*(C+
en utilisant la syntaxe \fIclasse::methode()\fR. Si la méthode n'est pas
statique, la fonction sera appelée avec la syntaxe \s-1THIS\-\s0>\fImethod()\fR.
.PP
Les exemples qui suivent utiliseront la classe \*(C+ que voici :
.PP
.Vb 6
\&     class color {
\&          public:
\&          color();
\&          ~color();
\&          int blue();
\&          void set_blue( int );
.Ve
.PP
.Vb 3
\&          private:
\&          int c_blue;
\&     };
.Ve
.PP
Les \s-1XSUB\s0 pour les méthodes \fIblue()\fR et \fIset_blue()\fR sont définies avec le
nom de la classe, mais le paramètre pour l'objet (\s-1THIS\s0, ou \*(L"self\*(R") est
implicite et il n'est pas mentionné dans la liste.
.PP
.Vb 2
\&     int
\&     color::blue()
.Ve
.PP
.Vb 3
\&     void
\&     color::set_blue( val )
\&          int val
.Ve
.PP
Les deux fonctions attendent un objet en premier paramètre. Le
compilateur xsubpp donne à cet objet le nom \f(CW\*(C`THIS\*(C'\fR, et l'utilise pour
appeler la méthode spécifiée. Ainsi, dans le code \*(C+ généré, les
méthodes \fIblue()\fR et \fIset_blue()\fR seront appelées de la façon suivante :
.PP
.Vb 1
\&     RETVAL = THIS->blue();
.Ve
.PP
.Vb 1
\&     THIS->set_blue( val );
.Ve
.PP
Si le nom de la fonction est \fB\s-1DESTROY\s0\fR, alors la fonction \*(C+
\&\f(CW\*(C`delete\*(C'\fR sera appelée avec \f(CW\*(C`THIS\*(C'\fR comme paramètre.
.PP
.Vb 2
\&     void
\&     color::DESTROY()
.Ve
.PP
Le code \*(C+ appellera \f(CW\*(C`delete\*(C'\fR.
.PP
.Vb 1
\&     delete THIS;
.Ve
.PP
Si le nom de la fonction est \fBnew\fR, la fonction \*(C+ \f(CW\*(C`new\*(C'\fR sera
appelée pour créer un objet \*(C+ dynamique. La \s-1XSUB\s0 s'attendra à
recevoir comme premier argument le nom de la classe, qui sera stocké
dans une variable nommée \f(CW\*(C`CLASS\*(C'\fR.
.PP
.Vb 2
\&     color *
\&     color::new()
.Ve
.PP
Le code \*(C+ appellera \f(CW\*(C`new\*(C'\fR :
.PP
.Vb 1
\&        RETVAL = new color();
.Ve
.PP
Voici maintenant un exemple de typemap qui pourrait être utilisé dans
cet exemple \*(C+.
.PP
.Vb 2
\&    TYPEMAP
\&    color *             O_OBJECT
.Ve
.PP
.Vb 5
\&    OUTPUT
\&    # L'objet Perl est beni dans 'CLASS', qui devrait etre un char*
\&    # contenant le nom du paquetage servant a le benir.
\&    O_OBJECT
\&        sv_setref_pv( $arg, CLASS, (void*)$var );
.Ve
.PP
.Vb 8
\&    INPUT
\&    O_OBJECT
\&        if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
\&                $var = ($type)SvIV((SV*)SvRV( $arg ));
\&        else{
\&                warn( \e"${Package}::$func_name() -- $var n'est pas une reference de SV benie\e" );
\&                XSRETURN_UNDEF;
\&        }
.Ve
.Sh "Méthode de construction d'interfaces"
.IX Subsection "Méthode de construction d'interfaces"
Lorsque vous concevez une interface entre Perl et une librairie C,
dans de nombreux cas une traduction directe de C vers \s-1XS\s0 est
suffisante. L'interface sera souvent très proche de C et parfois non
intuitive, surtout lorsque la fonction C modifie l'un de ses
paramètres. Si le programmeur souhaite réaliser une interface de style
plus proche de Perl, la méthode suivante peut l'aider à repérer les
parties les plus importantes de l'interface.
.PP
Repérez les fonctions C qui modifient leurs paramètres. Les \s-1XSUB\s0 de
ces fonctions peuvent retourner à Perl des listes, ou bien, en cas
d'échec, undef ou une liste vide.
.PP
Repérez les valeurs qui sont utilisées uniquement par les fonctions C
et les \s-1XSUB\s0. Si le code Perl lui\-même n'a pas besoin d'accéder au
contenu d'une valeur, alors il n'est peut\-être pas nécessaire de
fournir une traduction de cette valeur de C en Perl.
.PP
Repérez les pointeurs dans la liste de paramètres de la fonction C et
dans les valeurs de retour. Certains pointeurs peuvent être traités en
\&\s-1XS\s0 avec l'opérateur unaire & sur le nom de la variable, tandis que
d'autres nécessitent l'utilisation de l'opérateur * sur le nom du
type. En général, il est plus facile de travailler avec l'opérateur &.
.PP
Repérez les structures utilisées par les fonctions C. On peut souvent
utiliser le typemap T_PTROBJ pour faire en sorte que ces structures
puissent être manipulées par Perl comme des objets bénis.
.Sh "Objets Perl et structures C"
.IX Subsection "Objets Perl et structures C"
Lorsqu'on a affaire à des structures C, il faut choisir soit
\&\fBT_PTROBJ\fR, soit \fBT_PTRREF\fR pour le type \s-1XS\s0. Ces deux types sont
conçus pour manipuler des pointeurs vers des objets complexes. Le type
T_PTRREF peut être utilisé avec un objet Perl non béni, tandis que le
type T_PTROBJ impose que l'objet soit béni. En utilisant T_PTROBJ, on
peut obtenir une sorte de vérification de type, car la \s-1XSUB\s0 essaiera
de vérifier que l'objet Perl possède le type attendu.
.PP
Le code \s-1XS\s0 qui suit montre la fonction \fIgetnetconfigent()\fR utilisée avec
\&\s-1ONC+\s0 \s-1TIRPC\s0. Cette fonction retourne un pointeur vers une structure C,
et son prototype C est donné plus bas. Cet exemple montrera comment le
pointeur C devient une référence Perl. Perl considérera cette
référence comme un pointeur sur l'objet béni, et cherchera à appeler
un destructeur pour cet objet. Un destructeur sera fourni dans le code
\&\s-1XS\s0 pour libérer la mémoire utilisée par \fIgetnetconfigent()\fR. En
\&\s-1XS\s0, les destructeurs peuvent être créés en spécifiant une fonction
\&\s-1XSUB\s0 dont le nom se termine avec le mot \fB\s-1DESTROY\s0\fR. Les destructeurs
\&\s-1XS\s0 peuvent être utilisés pour libérer de la mémoire qui aurait été
allouée par \fImalloc()\fR dans une autre \s-1XSUB\s0.
.PP
.Vb 1
\&     struct netconfig *getnetconfigent(const char *netid);
.Ve
.PP
Un \f(CW\*(C`typedef\*(C'\fR peut être créé pour \f(CW\*(C`struct netconfig\*(C'\fR. L'objet Perl
sera béni dans une classe dont le nom correspondra au type C, avec un
suffixe \f(CW\*(C`Ptr\*(C'\fR ; le nom ne doit pas contenir de blanc s'il doit
devenir un nom de paquetage Perl. Le destructeur de l'objet sera mis
dans une classe correspondant à la classe de l'objet, et le mot\-clé
\&\s-1PREFIX\s0 sera utilisé pour réduire le nom au seul mot \s-1DESTROY\s0, comme
prévu dans Perl.
.PP
.Vb 1
\&     typedef struct netconfig Netconfig;
.Ve
.PP
.Vb 1
\&     MODULE = RPC  PACKAGE = RPC
.Ve
.PP
.Vb 3
\&     Netconfig *
\&     getnetconfigent(netid)
\&          char *netid
.Ve
.PP
.Vb 1
\&     MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
.Ve
.PP
.Vb 6
\&     void
\&     rpcb_DESTROY(netconf)
\&          Netconfig *netconf
\&          CODE:
\&          printf("Maintenant dans NetconfigPtr::DESTROY\en");
\&          free( netconf );
.Ve
.PP
Cet exemple requiert l'entrée de typemap suivante. Consultez la
section sur les typemaps pour plus d'informations sur l'ajout de
nouveaux typemaps dans une extension.
.PP
.Vb 2
\&     TYPEMAP
\&     Netconfig *  T_PTROBJ
.Ve
.PP
Cet exemple sera utilisé avec l'instruction Perl suivante.
.PP
.Vb 2
\&     use RPC;
\&     $netconf = getnetconfigent("udp");
.Ve
.PP
Lorsque Perl détruit l'objet référencé par \f(CW$netconf\fR, il envoie l'objet
à la fonction \s-1XSUB\s0 \s-1DESTROY\s0 fournie. Perl ne peut pas déterminer, et
ça ne l'intéresse pas, que cet objet est une structure C et non un
objet Perl. En ce sens, il n'y a pas de différence entre l'objet créé
par la \s-1XSUB\s0 \fIgetnetconfigent()\fR et un objet créé par une sous-routine
Perl normale.
.Sh "Le typemap"
.IX Subsection "Le typemap"
Le typemap est un ensemble de fragments de code utilisés par le
compilateur \fBxsubpp\fR pour relier les paramètres de fonction et les
valeurs C à des valeurs Perl. Le fichier typemap peut contenir trois
sections dénommées \f(CW\*(C`TYPEMAP\*(C'\fR, \f(CW\*(C`INPUT\*(C'\fR et \f(CW\*(C`OUTPUT\*(C'\fR. La section
\&\f(CW\*(C`INPUT\*(C'\fR indique au compilateur comment convertir des valeurs Perl en
valeurs de certains types C. La section \s-1OUTPUT\s0 indique au compilateur
comment traduire les valeurs de certains types C en des valeurs
accessibles à Perl. La section \s-1TYPEMAP\s0 indique au compilateur quels
fragments de code, dans les sections \s-1INPUT\s0 et \s-1OUTPUT\s0, doivent être
utilisés pour faire correspondre un type C donné à une valeur
Perl. Chacune des sections du typemap doit être précédée de l'un des
mots\-clés \s-1TYPEMAP\s0, \s-1INPUT\s0 et \s-1OUTPUT\s0.
.PP
Le typemap par défaut, dans le répertoire \f(CW\*(C`ext\*(C'\fR du code source Perl,
contient un grand nombre de types utiles qui sont mis à disposition
des extensions Perl. Certaines extensions définissent des typemaps
supplémentaires qu'elles peuvent conserver dans leur propre
répertoire. Ces typemaps supplémentaires peuvent se référer aux tables
de correspondance \s-1INPUT\s0 et \s-1OUTPUT\s0 du typemap principal. Le compilateur
\&\fBxsubpp\fR permet au typemap d'une extension de redéfinir des
correspondances présentes dans le typemap par défaut.
.PP
La plupart des extensions qui nécessitent un typemap personnalisé
n'ont besoin que de la section \s-1TYPEMAP\s0 du fichier typemap. Le typemap
personnalisé utilisé dans l'exemple \fIgetnetconfigent()\fR présenté
précédemment montre ce qui est peut\-être l'utilisation typique des
typemaps dans les extensions. Ce typemap est utilisé pour faire
correspondre une structure C au typemap T_PTROBJ. Le typemap utilisé
par \fIgetnetconfigent()\fR est présenté ici. Remarquez que le type C est
séparé du type \s-1XS\s0 avec une tabulation, et que l'opérateur unaire \f(CW\*(C`*\*(C'\fR
de C est considéré comme une partie du nom du type C.
.PP
.Vb 2
\&     TYPEMAP
\&     Netconfig *<tab>T_PTROBJ
.Ve
.PP
Voici un exemple plus compliqué. Supposons que vous vouliez que
\&\f(CW\*(C`struct netconfig\*(C'\fR soit béni dans la classe \f(CW\*(C`Net::Config\*(C'\fR. Une
manière de le faire est d'utiliser de la manière suivante le caractère
souligné (_) pour séparer les noms de paquetage :
.PP
.Vb 1
\&        typedef struct netconfig * Net_Config;
.Ve
.PP
et de fournir ensuite une entrée de typemap \f(CW\*(C`T_PTROBJ_SPECIAL\*(C'\fR qui
relie le souligné au quadruple point (::), puis de déclarer
\&\f(CW\*(C`Net_Config\*(C'\fR avec ce type :
.PP
.Vb 2
\&        TYPEMAP
\&        Net_Config      T_PTROBJ_SPECIAL
.Ve
.PP
.Vb 8
\&        INPUT
\&        T_PTROBJ_SPECIAL
\&                if (sv_derived_from($arg, \e"${(my $ntt=$ntype)=~s/_/::/g;\e$ntt}\e")) {
\&                        IV tmp = SvIV((SV*)SvRV($arg));
\&                $var = ($type) tmp;
\&                }
\&                else
\&                        croak(\e"$var n'est pas de type ${(my $ntt=$ntype)=~s/_/::/g;\e$ntt}\e")
.Ve
.PP
.Vb 4
\&        OUTPUT
\&        T_PTROBJ_SPECIAL
\&                sv_setref_pv($arg, \e"${(my $ntt=$ntype)=~s/_/::/g;\e$ntt}\e",
\&                (void*)$var);
.Ve
.PP
Les sections \s-1INPUT\s0 et \s-1OUTPUT\s0 substituent à la volée le souligné au
quadruple point, ce qui produit l'effet désiré. Cet exemple donne une
idée du pouvoir et de la souplesse du mécanisme des typemaps.
.SH "EXEMPLES"
.IX Header "EXEMPLES"
Fichier \f(CW\*(C`RPC.xs\*(C'\fR : interface avec certaines fonctions de la librairie
de connexion \s-1ONC+\s0 \s-1RPC\s0.
.PP
.Vb 3
\&     #include "EXTERN.h"
\&     #include "perl.h"
\&     #include "XSUB.h"
.Ve
.PP
.Vb 1
\&     #include <rpc/rpc.h>
.Ve
.PP
.Vb 1
\&     typedef struct netconfig Netconfig;
.Ve
.PP
.Vb 1
\&     MODULE = RPC  PACKAGE = RPC
.Ve
.PP
.Vb 9
\&     SV *
\&     rpcb_gettime(host="localhost")
\&          char *host
\&          PREINIT:
\&          time_t  timep;
\&          CODE:
\&          ST(0) = sv_newmortal();
\&          if( rpcb_gettime( host, &timep ) )
\&               sv_setnv( ST(0), (double)timep );
.Ve
.PP
.Vb 3
\&     Netconfig *
\&     getnetconfigent(netid="udp")
\&          char *netid
.Ve
.PP
.Vb 1
\&     MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
.Ve
.PP
.Vb 6
\&     void
\&     rpcb_DESTROY(netconf)
\&          Netconfig *netconf
\&          CODE:
\&          printf("NetconfigPtr::DESTROY\en");
\&          free( netconf );
.Ve
.PP
Fichier \f(CW\*(C`typemap\*(C'\fR : typemap personnalisé pour \s-1RPC\s0.xs.
.PP
.Vb 2
\&     TYPEMAP
\&     Netconfig *  T_PTROBJ
.Ve
.PP
Fichier \f(CW\*(C`RPC.pm\*(C'\fR : module Perl pour l'extension \s-1RPC\s0.
.PP
.Vb 1
\&     package RPC;
.Ve
.PP
.Vb 4
\&     require Exporter;
\&     require DynaLoader;
\&     @ISA = qw(Exporter DynaLoader);
\&     @EXPORT = qw(rpcb_gettime getnetconfigent);
.Ve
.PP
.Vb 2
\&     bootstrap RPC;
\&     1;
.Ve
.PP
Fichier \f(CW\*(C`rpctest.pl\*(C'\fR : programme de test Perl pour l'extension \s-1RPC\s0.
.PP
.Vb 1
\&     use RPC;
.Ve
.PP
.Vb 4
\&     $netconf = getnetconfigent();
\&     $a = rpcb_gettime();
\&     print "time = $a\en";
\&     print "netconf = $netconf\en";
.Ve
.PP
.Vb 4
\&     $netconf = getnetconfigent("tcp");
\&     $a = rpcb_gettime("poplar");
\&     print "time = $a\en";
\&     print "netconf = $netconf\en";
.Ve
.SH "VERSION DE XS"
.IX Header "VERSION DE XS"
Ce document couvre les fonctionnalités supportées par \f(CW\*(C`xsubpp\*(C'\fR 1.935.
.SH "AUTEUR"
.IX Header "AUTEUR"
Dean Roehrich <\fIroehrich@cray.com\fR>
Jul 8, 1996.
.SH "TRADUCTION"
.IX Header "TRADUCTION"
.Sh "Version"
.IX Subsection "Version"
Cette traduction française correspond à la version anglaise distribuée avec
perl 5.005_02.  Pour en savoir plus concernant ces traductions, consultez
<http://perl.enstimac.fr/>.
.Sh "Traducteur"
.IX Subsection "Traducteur"
Thierry Bézecourt <\fIthbz@worldnet.fr\fR>
.Sh "Relecture"
.IX Subsection "Relecture"
Régis Julié <\fIRegis.Julie@cetelem.fr\fR>