Provided by: manpages-fr-dev_4.19.0-7_all 
NOM
xdr - Bibliothèque de fonctions pour transmission externe de données
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS ET DESCRIPTION
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ésentation externe correspondante. 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 chaînes d'un certain
nombre d'octets 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ée. 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 défini par l'appelant.
Attention : pour lire depuis un flux XDR créé par cette API, il est nécessaire
d'appeler d'abord xdrrec_skiprecord() avant d'appeler d'autres API XDR. Cela insère
des octets additionnels dans le flux pour fournir des informations de limites
d'enregistrement. De plus des flux XDR créés par des API xdr*_create différentes ne
sont pas compatibles pour la même raison.
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 C 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 int *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, enum_t *dscmp, char *unp,
const struct xdr_discrim *choices,
xdrproc_t defaultarm); /* peut être NULL */
Une primitive de filtrage assurant la traduction entre une union C avec
discriminant et sa 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, procédure]. Si le discriminant de l'union est égal à la
valeur associée, alors la procédure 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.
ATTRIBUTS
Pour une explication des termes utilisés dans cette section, consulter attributes(7).
┌────────────────────────────────────────────────────────┬──────────────────────┬─────────┐
│Interface │ Attribut │ Valeur │
├────────────────────────────────────────────────────────┼──────────────────────┼─────────┤
│xdr_array(), xdr_bool(), xdr_bytes(), xdr_char(), │ Sécurité des threads │ MT-Safe │
│xdr_destroy(), xdr_double(), xdr_enum(), xdr_float(), │ │ │
│xdr_free(), xdr_getpos(), xdr_inline(), xdr_int(), │ │ │
│xdr_long(), xdrmem_create(), xdr_opaque(), │ │ │
│xdr_pointer(), xdrrec_create(), xdrrec_eof(), │ │ │
│xdrrec_endofrecord(), xdrrec_skiprecord(), │ │ │
│xdr_reference(), xdr_setpos(), xdr_short(), │ │ │
│xdrstdio_create(), xdr_string(), xdr_u_char(), │ │ │
│xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_union(), │ │ │
│xdr_vector(), xdr_void(), xdr_wrapstring() │ │ │
└────────────────────────────────────────────────────────┴──────────────────────┴─────────┘
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.
TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess
<https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry
Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>,
Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-
luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis
Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Pierre Giraud
<jean-pierregiraud@neuf.fr>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General
Public License version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ concernant les
conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
message à ⟨debian-l10n-french@lists.debian.org⟩.