.\" @(#)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 representação externa de dados
.SH SINOPSE E DESCRIÇÃO
.LP
Estas rotinas permitem que programadores C descrevam estruturas de dados
arbitrariamente em um modelo independente de máquina. Dados para chamadas 
de procedimento remoto são 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 variável e suas
representações externas correspondentes. O parâmetro
.I arrp
é o endereço do ponteiro para a matriz, enquanto
.I sizep
é o endereço do elemento 'count' da matriz;
este elemento 'count' não pode exceder
.IR maxsize .
O parâmetro
.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 representações externas.
Esta rotina retorna um se for bem-sucedida, e zero caso contrário.
.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 representações externas. Quando codifica dados, este filtro
produz valores 'um' ou 'zero'. Esta rotina retorna 'um' se for bem-sucedida, 
e 'zero' em caso contrário.
.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 
representações externas.
O parâmetro
.I sp
é o endereço do ponteiro de string. O comprimento da string é localizado
no endereço
.IR sizep ;
strings não podem ser maiores que 
.IR maxsize .
Esta rotina retorna 'um' se for bem-sucedida, 'zero' em caso contrário.
.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 representações externas. 
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
Nota: caracteres codificados não são 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 .
Destruição geralmente envolve a liberação 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 números de precisão
.B dupla
do C e suas representações externas. Esta rotina retorna 'um' se
for bem-sucedida, e 'zero' em caso contrário.
.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 representações externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 representações externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 liberação genérica. O primeiro argumento é a rotina
.SM XDR
para o objeto sendo liberado. O segundo argumento é um ponteiro para o
próprio objeto. Nota: o ponteiro passado para esta rotina 
.I não
é 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-posição' associada com o fluxo
.SM XDR
,
.IR xdrs .
A rotina retorna um inteiro sem sinal,
que indica a posição do fluxo de bytes
.SM XDR.
Uma implementação desejável do fluxo
.SM XDR
é que aritmética simples funcione com este número,
apesar de que instâncias do fluxo
.SM XDR
não 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 contígua do buffer do fluxo;
.I len
é o comprimento em bytes do buffer desejado.
Nota: o ponteiro é um 'cast' para
.BR "long *" .
.IP
Atenção:
.B xdr_inline(\|)
pode retornar
.SM NULL
(0)
se ele não puder alocar uma parte contígua de um buffer. Portanto o 
comportamento pode variar entre instâncias do fluxo; ele existe em
consideração à eficiência.
.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 representações 
externas. Estas rotinas retornam 'um' se forem bem-sucedidas, e 'zero' em caso
contrário.
.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 representações externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 são escritos ou lidos de um pedaço
de memória na posição
.I addr
, cujo comprimento não é maior que 
.I size
bytes. O
.I op
determina a direção 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 representação externa.
O parâmetro
.I cp
é o endereço do objeto opaco, e
.I cnt
é o seu tamanho em bytes.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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(\|)
não o faz. Portanto,
.B xdr_pointer(\|)
pode representar estruturas de dados recursivos, como árvores binárias
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 são escritos em um buffer de tamanho
.IR sendsize ;
um valor 'zero' indica que o sistema deve usar um padrão conveniente.
Os dados do fluxo são lidos de um buffer de tamanho. 
.IR recvsize ;
ele também pode ser setado para um padrão conveniente pela passagem de 
um valor igual a zero.
Quando um buffer de saída 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 parâmetro.
Nota: o campo
.I op
do fluxo
.SM XDR
precisa ser setado pelo chamador.
.IP
Atenção: este fluxo
.SM XDR
implementa um fluxo de registro intermediário. Portanto, há bytes
adicionais no fluxo para prover informações 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 saída são marcados como um registro completo, e o
buffer de saída é enviado opcionalmente se
.I sendnow
não é zero. Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 não tiver mais entradas, e 'zero' em caso contrário.
.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 à implementação
.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 contrário.
.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 perseguição a ponteiros dentro de estruturas.
O parâmetro
.I pp
é o endereço 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 representação externa.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.IP
Atenção: esta rotina não 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 posição setada associada com o fluxo
.SM XDR
.IR xdrs.
O parâmetro
.I pos
é um valor de posição obtido de
.BR xdr_getpos(\|) .
Esta rotina retorna 'um' se o fluxo
.SM XDR
não pode ser reposicionado, e 'zero' em caso contrário.
.IP
Atenção: é difícil 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 representações externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' e caso contrário.
.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
são escritos ou lidos do 
.IR arquivo
de fluxo padrão de
.B I/O.
O parâmetro
.I op
determina a direção do fluxo
.SM XDR
(
.BR \s-1XDR_ENCODE\s0 ,
.BR \s-1XDR_DECODE\s0 ,
ou
.BR \s-1XDR_FREE\s0 ).
.IP
Atenção: a rotina de destruição 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 representações externas
correspondentes. Strings não podem ser maiores que 
.IR maxsize .
Nota: 
.I sp
é o endereço do ponteiro da string. Esta rotina retorna 'um' se for bem-sucedida, e 
'zero' em caso contrário.
.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 representações externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 representações externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 representações externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 representações externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 representação externa correspondente. Ela
primeiro traduz o discriminante da união localizado em 
.IR dscmp .
Este discriminante é sempre um
.BR enum_t .
A seguir, a união localizada em
.I unp
é traduzida. O parâmetro
.I choices
é um ponteiro para uma matriz de estruturas
.B xdr_discrim(\|).
Cada estrutura contém um par ordenado de 
.RI [ value , proc ].
Se o discriminante da união é igual ao
.IR valor 
associado, então 
.I proc
é chamado para traduzir a união. O fim da matriz de estrutura
.B xdr_discrim(\|)
é denotada por uma rotina de valor
.SM NULL\s0.
Se o discriminante não é encontrado na matriz
.I choices
, então o procedimento
.I defaultarm
é chamado (se ele não for
.SM NULL\s0).
Retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 representações externas correspondentes. O parâmetro
.I arrp
é o endereço do ponteiro para a matriz, enquanto
.I size
é o elemento 'count' da matriz. O parâmetro
.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 
representações externas.
Esta rotina retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.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 parâmetro de função,
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 máximo de um inteiro sem sinal.
.B xdr_wrapstring(\|)
está à mão porque o pacote
.SM RPC
passa um máximo de duas rotinas
.SM XDR
como parâmetros, e 
.BR xdr_string(\|) ,
uma das primitivas mais frequentemente usadas, requer três.
Retorna 'um' se for bem-sucedida, e 'zero' em caso contrário.
.SH VEJA TAMBÉM
.BR rpc (3N)
.LP
Os seguintes manuais:
.RS
.ft I
eXternal Data Representation Standard: Especificação do Protocolo
.br
eXternal Data Representation: Notas Técnicas da Sun
.ft R
.br
.IR "\s-1XDR\s0: Padrão de Representação Externa de Dados" ,
.SM RFC1014, Sun Microsystems, Inc.,
.SM USC-ISI\s0.
.SH TRADUÇÃO PARA A LÍNGUA PORTUGUESA
\&\fR\&\f(CWRUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (tradução)\fR
\&\fR\&\f(CWXXXXXX XX XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (revisão)\fR