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);
où 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