Loading

NOM

       xdr - Bibliothèque de fonctions pour transmission externe de données

       Ces routines permettent aux programmeurs C de décrire des structures de
       données arbitraires de manière indépendante de la machine. Les  données
       pour  les  appels  de routines distantes (RPC) sont transmises de cette
       manière.

       Les prototypes ci-dessous sont déclarés dans <rpc/xdr.h>  et  utilisent
       les types suivants :

           typedef int bool_t;

           typedef bool_t (*xdrproc_t) (XDR *, void *,...);

       Pour la déclaration du type XDR, consultez <rpc/xdr.h>.

       bool_t xdr_array(XDR *xdrs, char **arrp, unsigned int *sizep,
                        unsigned int maxsize, unsigned int elsize,
                        xdrproc_t elproc);

              Une  primitive  de  filtrage  qui traduit les tables de longueur
              variable en leur représentations  externes  correspondantes.  Le
              paramètre arrp est l’adresse d’un pointeur sur la chaîne, tandis
              que sizep est l’adresse du nombre d’éléments dans la  table.  Ce
              nombre  d’éléments  ne  peut  pas  excéder maxsize. Le paramètre
              elsize est la taille (sizeof) de chaque élément de la table,  et
              elproc  est  un  filtre  XDR  de traduction entre la forme C des
              éléments de  la  table,  et  sa  représentation  externe.  Cette
              routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_bool(XDR *xdrs, bool_t *bp);

              Une  primitive  de  filtrage  assurant  la  traduction entre les
              booléens (entiers C)  et  leur  représentation  externe.  Durant
              l’encodage  des  données, ce filtre produit soit un 1 soit un 0.
              Cette routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_bytes(XDR *xdrs, char **sp, unsigned int *sizep,
                        unsigned int maxsize);

              Une primitive de  filtrage  assurant  la  traduction  entre  des
              tables  caractères  de  longueurs données et leur représentation
              externe. Le paramètre  sp  est  l’adresse  du  pointeur  sur  la
              chaîne.  La  longueur de la chaîne est située à l’adresse sizep.
              Les chaînes ne peuvent pas être plus longues que maxsize.  Cette
              routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_char(XDR *xdrs, char *cp);

              Une  primitive  de  filtrage  assurant  la  traduction entre les
              caractères C  et  leur  représentation  externe.  Cette  routine
              renvoie  1  si  elle  réussit,  0  sinon.  Note : les caractères
              encodés ne sont pas accolés, et occupent quatre  octets  chacun.
              Pour  les  tables  de  caractères, il vaut mieux se tourner vers
              xdr_bytes(), xdr_opaque() ou xdr_string().

       void xdr_destroy(XDR *xdrs);

              Une macro invoquant la routine de destruction associée  avec  le
              flux  XDR,  xdrs.  La  destruction  entraîne  habituellement  la
              libération de structures de données privées  associées  avec  le
              flux.  Le comportement est indéfini si on essaye d’utiliser xdrs
              après avoir invoqué xdr_destroy().

       bool_t xdr_double(XDR *xdrs, double *dp);

              Une primitive de  filtrage  assurant  la  traduction  entre  les
              nombres  C  en  double précision et leur représentation externe.
              Cette routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_enum(XDR *xdrs, enum_t *ep);

              Une primitive de  filtrage  assurant  la  traduction  entre  les
              énumérés  C enum (en réalité des entiers) et leur représentation
              externe. Cette routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_float(XDR *xdrs, float *fp);

              Une primitive de  filtrage  assurant  la  traduction  entre  les
              nombres  float  C  et leur représentation externe. Cette routine
              renvoie 1 si elle réussit, 0 sinon.

       void xdr_free(xdrproc_t proc, char *objp);

              Routine générique de libération.  Le  premier  argument  est  la
              routine  XDR  de  l’objet  à  libérer. Le second argument est un
              pointeur vers l’objet lui-même. Note : le  pointeur  transmis  à
              cette  routine n’est pas libéré, mais l’endroit où il pointe est
              libéré (récursivement).

       unsigned int xdr_getpos(XDR *xdrs);

              Une macro invoquant la routine de lecture de  position  associée
              avec  le  flux  XDR,  xdrs. Cette fonction renvoie un entier non
              signé,  qui  indique  la  position  dans  le   flux   XDR.   Une
              fonctionnalité  appréciable  serait  que  l’arithmétique usuelle
              fonctionne avec  ce  nombre,  mais  tous  les  flux  XDR  ne  le
              garantissent pas.

       long *xdr_inline(XDR *xdrs, int len);

              Une  macro qui invoque la routine en-ligne associée avec le flux
              XDR xdrs. Cette routine renvoie un  pointeur  vers  une  portion
              continue  du  tampon  du  flux. len est la longueur en octets du
              tampon désiré. Note : le pointeur est converti en long *.

              Attention : xdr_inline() peut renvoyer NULL (0) si elle ne  peut
              allouer une portion continue de tampon de la taille réclamée. Ce
              comportement peut néanmoins varier  d’une  instance  de  flux  à
              l’autre ; elle existe par souci d’efficacité.

       bool_t xdr_int(XDR *xdrs, int *ip);

              Une  primitive  de  filtrage  assurant  la  traduction entre les
              entiers C et leur représentation externe. Cette routine  renvoie
              1 si elle réussit, 0 sinon.

       bool_t xdr_long(XDR *xdrs, long *lp);

              Une  primitive  de  filtrage  assurant  la  traduction entre les
              entiers long C et leur  représentation  externe.  Cette  routine
              renvoie 1 si elle réussit, 0 sinon.

       void xdrmem_create(XDR *xdrs, char *addr, unsigned int size,
                          enum xdr_op op);

              Cette  routine  initialise l’objet flux XDR pointé par xdrs. Les
              données du flux sont lues ou écrites dans le bloc mémoire  situé
              en  addr  et  dont  la  longueur  ne  dépasse  pas  size octets.
              L’argument op détermine la direction du  flux  XDR  (XDR_ENCODE,
              XDR_DECODE ou XDR_FREE).

       bool_t xdr_opaque(XDR *xdrs, char *cp, unsigned int cnt);

              Une  primitive  de  filtrage  assurant  la  traduction entre des
              données opaques de taille fixe et leur  représentation  externe.
              Le  paramètre  cp est l’adresse de l’objet opaque, et cnt est sa
              taille en octets. Cette routine renvoie 1  si  elle  réussit,  0
              sinon.

       bool_t xdr_pointer(XDR *xdrs, char **objpp,
                          unsigned int objsize, xdrproc_t xdrobj);

              Comme xdr_reference() sauf qu’elle met bout à bout les pointeurs
              NULL  alors  que  xdr_reference()  ne   le   fait   pas.   Ainsi
              xdr_pointer()   peut   représenter  des  structures  de  données
              récursives, comme les arbres binaires ou les listes chaînées.

       void xdrrec_create(XDR *xdrs, unsigned int sendsize,
                          unsigned int recvsize, char *handle,
                          int (*readit) (char *, char *, int),
                          int (*writeit) (char *, char *, int));

              Cette routine initialise  le  flux  XDR  pointé  par  xdrs.  Les
              données  du flux sont écrites dans un tampon de taille sendsize.
              Une valeur nulle indique que  le  système  choisira  une  taille
              adéquate.  Les  données  du  flux  sont lues depuis un tampon de
              taille recvsize. De même le système choisira une taille adéquate
              en transmettant une valeur nulle. Lorsque le tampon de sortie du
              flux est plein, la fonction writeit est appelé.  Symétriquement,
              lorsque  le  tampon  d’entrée  est  vide, la fonction readit est
              invoquée. Le comportement de ces routines est similaire aux deux
              appels  système  read(2)  et  write(2),  sauf que le descripteur
              handle est passé aux routines en  tant  que  premier  paramètre.
              Note :  l’attribut op du flux XDR doit être fixé par l’appelant.

              Attention : ce flux  XDR  implémente  un  flux  d’enregistrement
              intermédiaire.  Il  y  a donc des octets supplémentaires dans le
              flux afin de séparer les enregistrements.

       bool_t xdrrec_endofrecord(XDR *xdrs, int sendnow);

              Cette routine ne peut être invoquée que sur des  flux  créé  par
              xdrrec_create().  Les  données  dans  le  tampon  de sortie sont
              considérées comme un enregistrement complet,  et  le  tampon  de
              sortie  est  éventuellement  écrit si sendnow est non nul. Cette
              routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdrrec_eof(XDR *xdrs);

              Cette routine ne peut être invoqué que sur des  flux  créés  par
              xdrrec_create(). Après avoir rempli le reste de l’enregistrement
              avec les données du flux, cette routine renvoie 1 si le flux n’a
              plus de données d’entrée, et 0 sinon.

       bool_t xdrrec_skiprecord(XDR *xdrs);

              Cette  routine  ne  peut être invoqué que sur des flux créés par
              xdrrec_create(). Elle indique  à  l’implémentation  XDR  que  le
              reste  de l’enregistrement en cours dans le tampon d’entrée doit
              être éliminé. Cette routine renvoie 1 si elle réussit, 0  sinon.

       bool_t xdr_reference(XDR *xdrs, char **pp, unsigned int size,
                            xdrproc_t proc);

              Une  primitive  qui  gère  les  pointeurs sur les structures. Le
              paramètre pp est l’adresse  du  pointeur,  size  est  la  taille
              (sizeof)  de  la  structure  pointée  par  *pp,  et  proc est la
              procédure XDR qui filtre la structure entre sa  forme  C  et  sa
              représentation externe. Cette routine renvoie 1 si elle réussit,
              et 0 sinon.

              Attention : cette routine ne comprend pas  les  pointeurs  NULL.
              Utilisez xdr_pointer() à sa place.

       xdr_setpos(XDR *xdrs, unsigned int pos);

              Une  macro  qui invoque la routine de positionnement associée au
              flux XDR xdrs. Le paramètre  pos  est  une  valeur  de  position
              obtenue  avec  xdr_getpos().  Cette routine renvoie 1 si le flux
              XDR peut être repositionné, et zéro sinon.

              Attention : il est difficile de repositionner certains types  de
              flux  XDR  ce qui peut faire échouer cette routine avec certains
              flux, et réussir avec d’autres.

       bool_t xdr_short(XDR *xdrs, short *sp);

              Une primitive de  filtrage  assurant  la  traduction  entre  les
              entiers  short  et  leur  représentation  externe. Cette routine
              renvoie 1 si elle réussit, 0 sinon.

       void xdrstdio_create(XDR *xdrs, FILE *file, enum xdr_op op);

              Cette routine initialise l’objet flux XDR pointé par  xdrs.  Les
              données du flux XDR sont écrites dans - ou lues depuis - le flux
              d’entrée-sortie standard file.  Le  paramètre  op  détermine  la
              direction du flux XDR (XDR_ENCODE, XDR_DECODE ou XDR_FREE).

              Attention :  la routine de destruction associée avec un tel flux
              XDR appelle fflush(3) sur le flux file, mais pas fclose(3).

       bool_t xdr_string(XDR *xdrs, char **sp, unsigned int maxsize);

              Une primitive de  filtrage  assurant  la  traduction  entre  les
              chaînes  de  caractères  C  et  leur représentation externe. Les
              chaînes ne peuvent pas être plus longues que maxsize. Note :  sp
              est l’adresse du pointeur sur la chaîne. Cette routine renvoie 1
              si elle réussit, 0 sinon.

       bool_t xdr_u_char(XDR *xdrs, unsigned char *ucp);

              Une primitive de  filtrage  assurant  la  traduction  entre  les
              caractères  unsigned  du C et leur représentation externe. Cette
              routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_u_int(XDR *xdrs, unsigned *up);

              Une primitive de  filtrage  assurant  la  traduction  entre  les
              entiers  unsigned  du  C  et  leur représentation externe. Cette
              routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp);

              Une primitive de  filtrage  assurant  la  traduction  entre  les
              entiers unsigned long du C et leur représentation externe. Cette
              routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_u_short(XDR *xdrs, unsigned short *usp);

              Une primitive de  filtrage  assurant  la  traduction  entre  les
              entiers  unsigned  short  du  C  et leur représentation externe.
              Cette routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_union(XDR *xdrs, int *dscmp, char *unp,
                        struct xdr_discrim *choices,
                        xdrproc_t defaultarm);     /* peut être NULL */

              Une primitive de filtrage assurant la traduction entre une union
              C avec discriminant et la représentation externe correspondante.
              Elle traduit d’abord le discriminant de l’union, situé en dscmp.
              Le  discriminant  doit  toujours  être  du type enum_t. Ensuite,
              l’union située en unp est traduite. Le paramètre choices est  un
              pointeur  sur  une  table  de  structures  xdr_discrim(). Chaque
              structure contient une paire ordonnée [valeur, procdure]. Si le
              discriminant  de  l’union  est  égal  à  une  valeur,  alors  la
              procdure associée est invoquée pour traduire l’union. La fin de
              la  table  de  structures  xdr_discrim()  est  indiquée  par une
              routine de valeur NULL. Si le discriminant n’est pas trouvé dans
              la table choices, alors la procédure defaultarm est invoquée (si
              elle ne vaut pas NULL). Cette routine renvoie 1 si elle réussit,
              0 sinon.

       bool_t xdr_vector(XDR *xdrs, char *arrp, unsigned int size,
                         unsigned int elsize, xdrproc_t elproc);

              Une  primitive  de  filtrage  assurant  la  traduction entre les
              tables de longueur fixe,  et  leur  représentation  externe.  Le
              paramètre  arrp  est  l’adresse du pointeur sur la table, tandis
              que size est le nombre d’éléments dans la  table.  Le  paramètre
              elsize  est  la  taille  (sizeof)  d’un  élément de la table, et
              elproc est un filtre XDR assurant la traduction entre la forme C
              des  éléments  de la table et leur représentation externe. Cette
              routine renvoie 1 si elle réussit, 0 sinon.

       bool_t xdr_void(void);

              Cette routine renvoie toujours 1.  Elle  peut  être  passée  aux
              routines  RPC  qui  ont besoin d’une fonction en paramètre alors
              que rien ne doit être fait.

       bool_t xdr_wrapstring(XDR *xdrs, char **sp);

              Une primitive qui appelle xdr_string(xdrs, sp,  MAXUN.UNSIGNED);MAXUN.UNSIGNED est la valeur maximale d’un entier non signé.
              xdr_wrapstring() est pratique car la bibliothèque RPC  passe  un
              maximum  de deux routines XDR comme paramètres, et xdr_string(),
              l’une des primitives les plus fréquemment utilisées en  requiert
              trois. Cette routine renvoie 1 si elle réussit, 0 sinon.

VOIR AUSSI

       rpc(3)

       Les manuels suivants :
              eXternal Data Representation Standard: Protocol Specification
              eXternal Data Representation: Sun Technical Notes
              XDR:   External  Data  Representation  Standard,  RFC 1014,  Sun
              Microsystems, Inc., USC-ISI.

COLOPHON

       Cette page fait partie de  la  publication  3.23  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      être       trouvées       à       l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Cette  page  de  manuel  a  été  traduite et mise à jour par Christophe
       Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis  par
       Alain  Portal  <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement         gérées         par         Nicolas         François
       <nicolas.francois@centraliens.net>   et   l’équipe    francophone    de
       traduction de Debian.

       Veuillez   signaler   toute   erreur   de   traduction  en  écrivant  à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous  pouvez  toujours avoir accès à la version anglaise de ce document
       en utilisant la commande « man -L C <section> <page_de_man> ».

                               30 décembre 2007