.\" @(#)xdr.3n	2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
.TH XDR 3 "16 de fevereiro de 1988"
.SH NOME
xdr \- rotinas de biblioteca para representao externa de dados
.SH SINOPSE E DESCRIO
.LP
Estas rotinas permitem que programadores C descrevam estruturas de dados
arbitrariamente em um modelo independente de mquina. Dados para chamadas 
de procedimento remoto so transmitidos usando estas rotinas.
.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
Uma primitiva de filtro que traduz entre matrizes de comprimento varivel e suas
representaes externas correspondentes. O parmetro
.I arrp
 o endereo do ponteiro para a matriz, enquanto
.I sizep
 o endereo do elemento 'count' da matriz;
este elemento 'count' no pode exceder
.IR maxsize .
O parmetro
.I elsize
 o
.I sizeof
de cada um dos elementos da matriz, e 
.I elproc
 um filtro
.SM XDR
que traduz entre o formato C dos elementos da matriz e suas representaes externas.
Esta rotina retorna um se for bem-sucedida, e zero caso contrrio.
.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
Uma primitiva de filtro que traduz entre booleanos (inteiros C)
e suas representaes externas. Quando codifica dados, este filtro
produz valores 'um' ou 'zero'. Esta rotina retorna 'um' se for bem-sucedida, 
e 'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre strings de bytes contados e suas 
representaes externas.
O parmetro
.I sp
 o endereo do ponteiro de string. O comprimento da string  localizado
no endereo
.IR sizep ;
strings no podem ser maiores que 
.IR maxsize .
Esta rotina retorna 'um' se for bem-sucedida, 'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre caracteres C e suas representaes externas. 
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
Nota: caracteres codificados no so empacotados, e ocupam 4 bytes cada. Para
matrizes de caracteres, vale a pena considerar
.BR xdr_bytes(\|) ,
.B xdr_opaque(\|)
ou
.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
Uma macro que invoca a rotina destrutiva associada com o fluxo
.SM XDR,
.IR xdrs .
Destruio geralmente envolve a liberao de estruturas de dados
privativas associadas com o fluxo. O uso de
.I xdrs
depois de invocar
.B xdr_destroy(\|)
 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
Uma primitiva de filtro que traduz entre nmeros de preciso
.B dupla
do C e suas representaes externas. Esta rotina retorna 'um' se
for bem-sucedida, e 'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre 
.BR enum s
da linguagem C (atualmente inteiros) e suas representaes externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre 
.BR float s
da linguagem C e suas representaes externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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
Rotina de liberao genrica. O primeiro argumento  a rotina
.SM XDR
para o objeto sendo liberado. O segundo argumento  um ponteiro para o
prprio objeto. Nota: o ponteiro passado para esta rotina 
.I no
 liberado, mas aquele para o qual ele aponta 
.I 
liberado (recursivamente).
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
u_int
xdr_getpos(xdrs)
\s-1XDR\s0 *xdrs;
.fi
.ft R
.IP
Uma macro que invoca a rotina 'pega-posio' associada com o fluxo
.SM XDR
,
.IR xdrs .
A rotina retorna um inteiro sem sinal,
que indica a posio do fluxo de bytes
.SM XDR.
Uma implementao desejvel do fluxo
.SM XDR
 que aritmtica simples funcione com este nmero,
apesar de que instncias do fluxo
.SM XDR
no precisam garantir isso.
.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
Uma macro que invoca a rotina 'em-linha' associada com o fluxo
.SM XDR
,
.IR xdrs .
A rotina retorna um ponteiro para uma parte contgua do buffer do fluxo;
.I len
 o comprimento em bytes do buffer desejado.
Nota: o ponteiro  um 'cast' para
.BR "long *" .
.IP
Ateno:
.B xdr_inline(\|)
pode retornar
.SM NULL
(0)
se ele no puder alocar uma parte contgua de um buffer. Portanto o 
comportamento pode variar entre instncias do fluxo; ele existe em
considerao  eficincia.
.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
Uma primitiva de filtro que traduz entre inteiros do C e suas representaes 
externas. Estas rotinas retornam 'um' se forem bem-sucedidas, e 'zero' em caso
contrrio.
.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
Uma primitiva de filtro que traduz entre inteiros
.B longos
do C e suas representaes externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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 rotina inicializa o objeto de fluxo
.SM XDR
apontado por
.IR xdrs .
Os dados do fluxo so escritos ou lidos de um pedao
de memria na posio
.I addr
, cujo comprimento no  maior que 
.I size
bytes. O
.I op
determina a direo do fluxo
.SM XDR
(
.BR \s-1XDR_ENCODE\s0 ,
.BR \s-1XDR_DECODE\s0 ,
ou
.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
Uma primitiva de filtro que traduz entre dados opacos de tamanho fixo
e sua representao externa.
O parmetro
.I cp
 o endereo do objeto opaco, e
.I cnt
 o seu tamanho em bytes.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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(\|)
se excetua pelo fato de serializar ponteiros
.SM NULL,
uma vez que 
.B xdr_reference(\|)
no o faz. Portanto,
.B xdr_pointer(\|)
pode representar estruturas de dados recursivos, como rvores binrias
ou listas ligadas.
.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 rotina inicializa o objeto de fluxo
.SM XDR
apontado por
.IR xdrs .
Os dados do fluxo so escritos em um buffer de tamanho
.IR sendsize ;
um valor 'zero' indica que o sistema deve usar um padro conveniente.
Os dados do fluxo so lidos de um buffer de tamanho. 
.IR recvsize ;
ele tambm pode ser setado para um padro conveniente pela passagem de 
um valor igual a zero.
Quando um buffer de sada do fluxo est cheio,
.I writeit
 chamado. Similarmente, quando um buffer de entrada do fluxo est vazio,
.I readit
 chamado. O comportamento destas duas rotinas  similar s chamadas 
de sistema
.B read
e
.BR write ,
exceto pelo fato de que 
.I handle
 passado para a antiga rotina como o primeiro parmetro.
Nota: o campo
.I op
do fluxo
.SM XDR
precisa ser setado pelo chamador.
.IP
Ateno: este fluxo
.SM XDR
implementa um fluxo de registro intermedirio. Portanto, h bytes
adicionais no fluxo para prover informaes de limite de registro.
.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 rotina pode ser invocada somente em fluxos criados por
.BR xdrrec_create(\|) .
Os dados no buffer de sada so marcados como um registro completo, e o
buffer de sada  enviado opcionalmente se
.I sendnow
no  zero. Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdrrec_eof(xdrs)
\s-1XDR\s0 *xdrs;
int empty;
.fi
.ft R
.IP
Esta rotina pode ser invocada somente em fluxos criados por
.BR xdrrec_create(\|) .
Depois de consumir o resto do registro corrente no fluxo, esta rotina retorna
'um' se o fluxo no tiver mais entradas, e 'zero' em caso contrrio.
.br
.if t .ne 3
.LP
.ft B
.nf
.sp .5
xdrrec_skiprecord(xdrs)
\s-1XDR\s0 *xdrs;
.fi
.ft R
.IP
Esta rotina pode ser invocada somente em fluxos criados por
.BR xdrrec_create(\|) .
Ele diz  implementao
.SM XDR
que o resto do registro corrente no buffer de entrada do fluxo deve ser descartado.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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
Uma primitiva que fornece perseguio a ponteiros dentro de estruturas.
O parmetro
.I pp
 o endereo do ponteiro;
.I size
 a estrutura
.I sizeof
para o qual
.I *pp
aponta; e
.I proc
 um procedimento
.SM XDR
que filtra a estrutura entre sua forma C e sua representao externa.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.IP
Ateno: esta rotina no entende ponteiros do tipo
.SM NULL.
Use
.B xdr_pointer(\|)
no 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
Uma macro que invoca a rotina de posio setada associada com o fluxo
.SM XDR
.IR xdrs.
O parmetro
.I pos
 um valor de posio obtido de
.BR xdr_getpos(\|) .
Esta rotina retorna 'um' se o fluxo
.SM XDR
no pode ser reposicionado, e 'zero' em caso contrrio.
.IP
Ateno:  difcil reposicionar alguns tipos de fluxos
.SM XDR
, assim esta rotina pode falhar com um tipo de fluxo e funcionar com outro.
.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
Uma primitiva de filtro que traduz entre inteiros 
.B curtos
do C e suas representaes externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' e caso contrrio.
.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 rotina inicializa o objeto de fluxo
.SM XDR
apontado por
.IR xdrs .
Os dados do fluxo
.SM XDR
so escritos ou lidos do 
.IR arquivo
de fluxo padro de
.B I/O.
O parmetro
.I op
determina a direo do fluxo
.SM XDR
(
.BR \s-1XDR_ENCODE\s0 ,
.BR \s-1XDR_DECODE\s0 ,
ou
.BR \s-1XDR_FREE\s0 ).
.IP
Ateno: a rotina de destruio associada com tais rotinas de chamada de fluxo
.SM XDR
.B fflush(\|)
sobre o fluxo de
.I arquivo
, mas nunca
.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
Uma primitiva de filtro que traduz entre strings C e suas representaes externas
correspondentes. Strings no podem ser maiores que 
.IR maxsize .
Nota: 
.I sp
 o endereo do ponteiro da string. Esta rotina retorna 'um' se for bem-sucedida, e 
'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre caracteres C
.B sem sinal
e suas representaes externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre inteiros
.B sem sinal
do C e suas representaes externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre inteiros
.B "longos sem sinal"
do C e suas representaes externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre inteiros
.B "curtos sem sinal"
do C e suas representaes externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre uma 
.B union
discriminada do C e sua representao externa correspondente. Ela
primeiro traduz o discriminante da unio localizado em 
.IR dscmp .
Este discriminante  sempre um
.BR enum_t .
A seguir, a unio localizada em
.I unp
 traduzida. O parmetro
.I choices
 um ponteiro para uma matriz de estruturas
.B xdr_discrim(\|).
Cada estrutura contm um par ordenado de 
.RI [ value , proc ].
Se o discriminante da unio  igual ao
.IR valor 
associado, ento 
.I proc
 chamado para traduzir a unio. O fim da matriz de estrutura
.B xdr_discrim(\|)
 denotada por uma rotina de valor
.SM NULL\s0.
Se o discriminante no  encontrado na matriz
.I choices
, ento o procedimento
.I defaultarm
 chamado (se ele no for
.SM NULL\s0).
Retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.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
Uma primitiva de filtro que traduz entre matrizes de comprimento fixo
e suas representaes externas correspondentes. O parmetro
.I arrp
 o endereo do ponteiro para a matriz, enquanto
.I size
 o elemento 'count' da matriz. O parmetro
.I elsize
 o
.I sizeof
de cada um dos elementos da matriz, e 
.I elproc
 um filtro
.SM XDR
que traduz entre o formato dos elementos da matriz em C e suas 
representaes externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.br
.if t .ne 5
.LP
.ft B
.nf
.sp .5
xdr_void(\|)
.fi
.ft R
.IP
Esta rotina sempre retorna 'um'.
Ela pode ser passada para rotinas
.SM RPC
que requerem um parmetro de funo,
onde nada vai ser feito.
.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
Uma primitiva que chama
.B "xdr_string(xdrs, sp,\s-1MAXUN.UNSIGNED\s0 );"
onde
.B
.SM MAXUN.UNSIGNED
 o valor mximo de um inteiro sem sinal.
.B xdr_wrapstring(\|)
est  mo porque o pacote
.SM RPC
passa um mximo de duas rotinas
.SM XDR
como parmetros, e 
.BR xdr_string(\|) ,
uma das primitivas mais frequentemente usadas, requer trs.
Retorna 'um' se for bem-sucedida, e 'zero' em caso contrrio.
.SH VEJA TAMBM
.BR rpc (3N)
.LP
Os seguintes manuais:
.RS
.ft I
eXternal Data Representation Standard: Especificao do Protocolo
.br
eXternal Data Representation: Notas Tcnicas da Sun
.ft R
.br
.IR "\s-1XDR\s0: Padro de Representao Externa de Dados" ,
.SM RFC1014, Sun Microsystems, Inc.,
.SM USC-ISI\s0.
.SH TRADUO PARA A LNGUA PORTUGUESA
\&\fR\&\f(CWRUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (traduo)\fR
\&\fR\&\f(CWXXXXXX XX XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (reviso)\fR