XDR
Section : Manuel du programmeur Linux (
3)
Mise à jour de la version anglaise : 30 décembre 2007
Index
Menu principal
NOM
xdr - Bibliothèque de fonctions pour transmission externe de données
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 utiliser les types suivants :
typedef int bool_t;
typedef bool_t (*xdrproc_t) (XDR *, void *,...);
Pour la déclaration du type
XDR,
voir
<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 C
de type
float
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éés 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
n'est pas nul.
Cette routine renvoie 1 si elle réussit, 0 sinon.
bool_t xdrrec_eof(XDR *xdrs);
-
Cette routine ne peut être invoquée 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ée 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, procédure].
Si le discriminant de l'union est égal à une
valeur,
alors la
procédure
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 argument
alors que rien ne doit être fait.
bool_t xdr_wrapstring(XDR *xdrs, char **sp);
-
Une primitive qui appelle
xdr_string(xdrs, sp, 1MAXUN.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.
TRADUCTION
Ce document est une traduction réalisée par Christophe Blaess
<http://www.blaess.fr/christophe/> le 4 septembre 2000
et révisée le 17 juillet 2008.
L'équipe de traduction a fait le maximum pour réaliser une adaptation
française de qualité. La version anglaise la plus à jour de ce document est
toujours consultable via la commande : « LANG=C man 3 xdr ».
N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute
erreur dans cette page de manuel.
Index
- NOM
-
- SYNOPSIS ET DESCRIPTION
-
- VOIR AUSSI
-
- TRADUCTION
-
Dernière mise à jour : 17 juillet 2008