.\" @(#)xdr.3n	2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
.\" Translated Sat Apr 29 2000 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH XDR 3N "16 febrero 1988"
.SH NOMBRE
xdr \- rutinas de biblioteca para la representacin externa de datos
.SH SINOPSIS Y DESCRIPCIN
.LP
Estas rutinas permiten a los programadores de C describir estructuras de
datos arbitrarias de una forma independiente de la mquina. Los datos para
las llamadas a procedimientos remotos se transmiten usando estas rutinas.
.LP
.ft B
.nf
.sp .5
xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)
\s-1XDR\s0 *xdrs;
char **arrp;
u_int *sizep, maxsize, elsize;
xdrproc_t elproc;
.fi
.ft R
.IP
Una primitiva de filtro que convierte arrays de longitud variable a sus
correspondientes representaciones externas y viceversa. El parmetro
.I arrp
es la direccin del puntero al array, mientras que
.I sizep
es la direccin del contador de elementos del array. Este contador de
elementos no puede exceder
.IR maxsize .
El parmetro
.I elsize
es el
.I sizeof
de cada uno de los elementos del array, y
.I elproc
es un filtro
.SM XDR
que convierte entre el formato en C de los elementos del array y su
representacin externa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdr_bool(xdrs, bp)
\s-1XDR\s0 *xdrs;
bool_t *bp;
.fi
.ft R
.IP
Una primitiva de filtro que convierte booleanos (enteros de C) a sus
representaciones externas y viceversa. Cuando se condifican datos, este
filtro produce valores de uno o de cero.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_bytes(xdrs, sp, sizep, maxsize)
\s-1XDR\s0 *xdrs;
char **sp;
u_int *sizep, maxsize;
.fi
.ft R
.IP
Una primitiva de filtro que convierte cadenas de bytes contadas a sus
representaciones externas y viceversa.
El parmetro
.I sp
es la direccin del puntero a la cadena. La longitud de la cadena se
encuentra en la direccin
.IR sizep .
Las cadenas no pueden ser ms largas que
.IR maxsize .
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_char(xdrs, cp)
\s-1XDR\s0 *xdrs;
char *cp;
.fi
.ft R
.IP
Una primitiva de filtro que convierte caracteres de C a sus representaciones
externas y viceversa. Esta rutina devuelve uno si tiene xito y cero en caso
contrario. Nota: los caracteres codificados no se empaquetan y cada uno
ocupa 4 bytes. Para arrays de caracteres, vale la pena considerar
.BR xdr_bytes(\|) ,
.B xdr_opaque(\|)
o
.BR xdr_string(\|) .
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
void
xdr_destroy(xdrs)
\s-1XDR\s0 *xdrs;
.fi
.ft R
.IP
Una macro que invoca a la rutina de destruccin asociada con el flujo
.SM XDR\s0,
.IR xdrs .
Usualmente, la destruccin implica la liberacin de estructuras de datos
privadas asociadas con el flujo. El uso de
.I xdrs
despus de llamar a
.B xdr_destroy(\|)
es indefinido.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_double(xdrs, dp)
\s-1XDR\s0 *xdrs;
double *dp;
.fi
.ft R
.IP
Una primitiva de filtro que convierte nmeros de precisin doble de C
.RB ( double )
a sus representaciones externas y viceversa. Esta rutina devuelve uno si
tiene xito y cero en caso contrario.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_enum(xdrs, ep)
\s-1XDR\s0 *xdrs;
enum_t *ep;
.fi
.ft R
.IP
Una primitiva de filtro que convierte enumerados de C
.RB ( enum s)
(enteros en realidad) a sus representaciones externas y viceversa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdr_float(xdrs, fp)
\s-1XDR\s0 *xdrs;
float *fp;
.fi
.ft R
.IP
Una primitiva de filtro que convierte nmeros flotantes de C
.RB ( float s)
a sus representaciones externas y viceversa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
void
xdr_free(proc, objp)
xdrproc_t proc;
char *objp;
.fi
.ft R
.IP
Rutina genrica de liberacin. El primer argumento es la rutina
.SM XDR
para que libera el objeto. El segundo argumento es un puntero al propio
objeto. Nota:
.I no
se libera el puntero pasado a esta rutina, sino
.I a lo que l apunta
(de forma recursiva).
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
u_int
xdr_getpos(xdrs)
\s-1XDR\s0 *xdrs;
.fi
.ft R
.IP
Una macro que llama a la rutina "obtener posicin" asociada con el flujo
.SM XDR\s0,
.IR xdrs .
La rutina devuelve un entero sin signo que indica la posicin en el flujo de
bytes
.SM XDR\s0.
Una caractersitica deseable de los flujos
.SM XDR
es que la aritmtica simple funcione con este nmero, aunque las instancias
de flujos
.SM XDR
no necesitan garantizar esto.
.br
.if t .ne 4
.LP
.ft B
.nf
.sp .5
.br
long *
xdr_inline(xdrs, len)
\s-1XDR\s0 *xdrs;
int len;
.fi
.ft R
.IP
Una macro que llama a la rutina "en lnea" asociada con el flujo
.SM XDR\s0,
.IR xdrs .
La rutina devuelve un puntero a una porcin contigua del buffer del flujo.
.I len
es la longitud en bytes del buffer deseado.
Nota: el puntero se convierte al tipo
.BR "long *" .
.IP
Cuidado:
.B xdr_inline(\|)
puede devolver
.SM NULL
(0)
si no puede reservar una porcin contigua de buffer. Por lo tanto, el
comportamiento puede varias entre instancias de flujo.
Existe por el bien de la eficiencia.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_int(xdrs, ip)
\s-1XDR\s0 *xdrs;
int *ip;
.fi
.ft R
.IP
Una primitiva de filtro que convierte enteros de C a sus representaciones
externas y viceversa. Esta rutina devuelve uno si tiene xito y cero en caso
contrario.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_long(xdrs, lp)
\s-1XDR\s0 *xdrs;
long *lp;
.fi
.ft R
.IP
Una primitiva de filtro que convierte enteros largos de C
.RB ( long )
a sus representaciones externas y viceversa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 12
.LP
.ft B
.nf
.sp .5
void
xdrmem_create(xdrs, addr, size, op)
\s-1XDR\s0 *xdrs;
char *addr;
u_int size;
enum xdr_op op;
.fi
.ft R
.IP
Esta rutina inicializa el objeto de flujo
.SM XDR
apuntado por
.IR xdrs .
Los datos del flujo se escriben en, o se leen de, una porcin de memoria en
la posicin
.I addr
cuya longitud no es mayor que
.I size
bytes.  El
.I op
determina la direccin del flujo
.SM XDR
(bien
.BR \s-1XDR_ENCODE\s0 ,
.B \s-1XDR_DECODE\s0
o
.BR \s-1XDR_FREE\s0 ).
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_opaque(xdrs, cp, cnt)
\s-1XDR\s0 *xdrs;
char *cp;
u_int cnt;
.fi
.ft R
.IP
Una primitiva de filtro que convierte datos opacos de tamao fijo a sus
representaciones externas y viceversa.
El parmetro
.I cp
es la direccin del objeto opaco y
.I cnt
es su tamao en bytes.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_pointer(xdrs, objpp, objsize, xdrobj)
\s-1XDR\s0 *xdrs;
char **objpp;
u_int objsize;
xdrproc_t xdrobj;
.fi
.ft R
.IP
Como
.B xdr_reference(\|)
salvo que serializa punteros
.SM NULL\s0,
mientras que
.B xdr_reference(\|)
no lo hace. Por tanto,
.B xdr_pointer(\|)
puede representar estructuras de datos recursivas, tales como rboles
binarios o listas enlazadas.
.br
.if t .ne 15
.LP
.ft B
.nf
.sp .5
void
xdrrec_create(xdrs, sendsize, recvsize, handle, readit, writeit)
\s-1XDR\s0 *xdrs;
u_int sendsize, recvsize;
char *handle;
int (*readit) (\|), (*writeit) (\|);
.fi
.ft R
.IP
Esta rutina inicializa el objeto de flujo
.SM XDR
apuntado por
.IR xdrs .
Los datos del flujo se escriben en un buffer de tamao
.IR sendsize .
Un valor cero indica que el sistema debera usar un valor por omisin
adecuado. Los datos del flujo se leen de un buffer de tamao
.IR recvsize .
Un valor cero tambin indica que se le asigne un valor por omisin adecuado.
Cuando un buffer de salida de un flujo se llena, se llama a
.IR writeit .
De igual forma, cuando un buffer de entrada de un flujo est vaco, se llama
a
.IR readit .
El comportamiento de estas rutinas es similar al de las llamadas al sistema
.B read
y
.BR write ,
excepto que
.I handle
se pasa a las rutinas anteriores como primer parmetro.
Nota: el campo
.I op
del flujo
.SM XDR
debe ser asignado por el invocador.
.IP
Cuidado: este flujo
.SM XDR
implanta un flujo de registros intermedio. Por lo tanto, existen bytes
adicionales en el flujo para proporcionar informacin sobre lmites de
registros.
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
xdrrec_endofrecord(xdrs, sendnow)
\s-1XDR\s0 *xdrs;
int sendnow;
.fi
.ft R
.IP
Esta rutina slo puede llamarse sobre flujos creados por
.BR xdrrec_create(\|) .
Los datos del buffer de salida se marcan como un registro terminado y,
opcionalmente, se escribe el buffer de salida si
.I sendnow
no es cero. Esta rutina devuelve uno si tiene xito y cero en caso
contrario.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdrrec_eof(xdrs)
\s-1XDR\s0 *xdrs;
int empty;
.fi
.ft R
.IP
Slo pueda llamarse a esta rutina sobre flujos creados por
.BR xdrrec_create(\|) .
Despus de consumir el resto del registro actual en el flujo, esta rutina
devuelve uno si el flujo no tiene ms datos de entrada y cero en caso
contrario.
.br
.if t .ne 3
.LP
.ft B
.nf
.sp .5
xdrrec_skiprecord(xdrs)
\s-1XDR\s0 *xdrs;
.fi
.ft R
.IP
Slo pueda llamarse a esta rutina sobre flujos creados por
.BR xdrrec_create(\|) .
Le dice a la implementacin
.SM XDR
que se debera descartar el resto del registro actual en el buffer de
entrada del flujo. Esta rutina devuelve uno si tiene xito y cero en caso
contrario.
.br
.if t .ne 11
.LP
.ft B
.nf
.sp .5
xdr_reference(xdrs, pp, size, proc)
\s-1XDR\s0 *xdrs;
char **pp;
u_int size;
xdrproc_t proc;
.fi
.ft R
.IP
Una primitiva que proporciona un seguimiento de punteros dentro de estructuras.
El parmetro
.I pp
es la direccin del puntero.
.I size
es el
.I sizeof
de la estructura a la que apunta
.IR *pp ,
y
.I proc
es un procedimiento
.SM XDR
que filtra la estructura entre su formato en C y su representacin externa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.IP
Cuidado: esta rutina no entiende punteros
.SM NULL\s0.
Use
.B xdr_pointer(\|)
en su lugar.
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_setpos(xdrs, pos)
\s-1XDR\s0 *xdrs;
u_int pos;
.fi
.ft R
.IP
Una macro que llama a la rutina de establecimiento de posicin con el flujo
.SM XDR
.IR xdrs .
El parmetro
.I pos
es el valor de posicin obtenido de
.BR xdr_getpos(\|) .
Esta rutina devuelve uno si se podra reposicionar el flujo
.SM XDR
y cero en caso contrario.
.IP
Cuidado: es difcil reposicionar algunos tipos de flujos
.SM XDR\s0,
por lo que esta rutina puede fallar con un tipo de flujo y tener xito con
otro.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdr_short(xdrs, sp)
\s-1XDR\s0 *xdrs;
short *sp;
.fi
.ft R
.IP
Una primitiva de filtro que convierte enteros cortos de C
.RB ( short )
a sus representaciones externas y viceversa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
void
xdrstdio_create(xdrs, file, op)
\s-1XDR\s0 *xdrs;
\s-1FILE\s0 *file;
enum xdr_op op;
.fi
.ft R
.IP
Esta rutina inicializa el flujo
.SM XDR
apuntado por
.IR xdrs .
Los datos del flujo
.SM XDR
se escriben en, o se leen de, el flujo de
.B E/S
estndar
.IR file .
El parmetro
.I op
determina la direccin del flujo
.SM XDR
(bien
.BR \s-1XDR_ENCODE\s0 ,
.B \s-1XDR_DECODE\s0
o
.BR \s-1XDR_FREE\s0 ).
.IP
Cuidado: la rutina de destruccin asociada con tales flujos
.SM XDR
llama a
.B fflush(\|)
sobre el flujo
.IR file ,
pero nunca a
.BR fclose(\|) .
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
xdr_string(xdrs, sp, maxsize)
\s-1XDR\s0
*xdrs;
char **sp;
u_int maxsize;
.fi
.ft R
.IP
Una primitiva de filtro que convierte cadenas de C en sus correspondientes
representaciones externas y viceversa.
Las candenas no pueden ser ms largas de
.IR maxsize .
Nota: 
.I sp
es la direccin del puntero a la cadena.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdr_u_char(xdrs, ucp)
\s-1XDR\s0 *xdrs;
unsigned char *ucp;
.fi
.ft R
.IP
Una primitiva de filtro que convierte caracteres sin signo de C
.RB ( "unsigned char" )
a sus representaciones externas y viceversa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
xdr_u_int(xdrs, up)
\s-1XDR\s0 *xdrs;
unsigned *up;
.fi
.ft R
.IP
Una primitiva de filtro que convierte enteros sin signo de C
.RB ( unsigned )
a sus representaciones externas y viceversa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_u_long(xdrs, ulp)
\s-1XDR\s0 *xdrs;
unsigned long *ulp;
.fi
.ft R
.IP
Una primitiva de filtro que convierte enteros largos sin signo de C
.RB ( "unsigned long" )
a sus representaciones externas y viceversa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_u_short(xdrs, usp)
\s-1XDR\s0 *xdrs;
unsigned short *usp;
.fi
.ft R
.IP
Una primitiva de filtro que convierte enteros cortos sin signo de C
.RB ( "unsigned short" )
a sus representaciones externas y viceversa.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 16
.LP
.ft B
.nf
.sp .5
xdr_union(xdrs, dscmp, unp, choices, dfault)
\s-1XDR\s0 *xdrs;
int *dscmp;
char *unp;
struct xdr_discrim *choices;
bool_t (*defaultarm) (\|);  /* may equal \s-1NULL\s0 */
.fi
.ft R
.IP
Una primitiva de filtro que convierte una
.B union
discriminada de C a su correspondiente representacin externa y viceversa.
Primero, convierte el discriminante de la unin localizado en
.IR dscmp .
Este discriminante siempre es un
.BR enum_t .
A continuacin, se convierte la unin localizada en
.IR unp .
El parmetro
.I choices
es un puntero a un array de estructuras
.BR xdr_discrim(\|) .
Cada estructura contiene un par ordenado
.RI [ value , proc ].
Si el discriminante de la unin es igual al
.IR value
asociado, se llama a
.I proc
para convertir la unin. El final del array de estructuras
.B xdr_discrim(\|)
se denota con una rutina de valor
.SM NULL\s0.
Si no se encuentra el discriminante en el array
.IR choices ,
se llama al procedimiento
.I defaultarm
(si no es
.SM NULL\s0).
Devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 6
.LP
.ft B
.nf
.sp .5
xdr_vector(xdrs, arrp, size, elsize, elproc)
\s-1XDR\s0 *xdrs;
char *arrp;
u_int size, elsize;
xdrproc_t elproc;
.fi
.ft R
.IP
Una primitiva de filtro que convierte arrays de longitud fija a sus
correspondientes representaciones externas y viceversa. El parmetro
.I arrp
es la direccin del puntero al array, mientras que
.I size
es el nmero de elementos del array. El parmetro
.I elsize
es el
.I sizeof
de cada uno de los elementos del array y
.I elproc
es un flitro
.SM XDR
que traduce entre el formato en C de los elementos del array y sus
representaciones externas.
Esta rutina devuelve uno si tiene xito y cero en caso contrario.
.br
.if t .ne 5
.LP
.ft B
.nf
.sp .5
xdr_void(\|)
.fi
.ft R
.IP
Esta rutina siempre devuelve uno. Se puede pasar a rutinas
.SM RPC
que necesitan una parmetro funcin donde no se va a hacer nada.
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_wrapstring(xdrs, sp)
\s-1XDR\s0 *xdrs;
char **sp;
.fi
.ft R
.IP
Una primitiva que llama a
.B "xdr_string(xdrs, sp,\s-1MAXUN.UNSIGNED\s0);"
donde
.B
.SM MAXUN.UNSIGNED
es el valor mximo de un entero sin signo.
.B xdr_wrapstring(\|)
es adecuada porque el paquete
.SM RPC
pasa un mximo de dos rutinas
.SM XDR
como parmetros y
.BR xdr_string(\|) ,
una de las primitivas usadas con ms frecuencia, necesita tres.
Devuelve uno si tiene xito y cero en caso contrario.
.SH "VASE TAMBIN"
.BR rpc (3N)
.LP
Los siguientes manuales:
.RS
.ft I
eXternal Data Representation Standard: Protocol Specification
.br
eXternal Data Representation: Sun Technical Notes
.ft R
.br
.IR "\s-1XDR\s0: External Data Representation Standard" ,
.SM RFC1014, Sun Microsystems, Inc.,
.SM USC-ISI\s0.