XDR(3N)

NOME
xdr - rotinas de biblioteca para representação externa de dados

SINÓPSE E DESCRIÇÃO

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.

xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)
XDR *xdrs;
char **arrp;
u_int *sizep, maxsize, elsize;
xdrproc_t elproc;

    Uma primitiva de filtro que traduz entre matrizes de comprimento variável e suas representações externas correspondentes. O parâmetro arrp é o endereço do ponteiro para a matriz, enquanto sizep é o endereço do elemento 'count' da matriz; este elemento 'count' não pode exceder maxsize. O parâmetro elsize é o sizeof de cada um dos elementos da matriz, e elproc é um filtro XDR que traduz entre o formato C dos elementos da matriz e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_bool(xdrs, bp)
XDR *xdrs;
bool_t *bp;

    Uma primitiva de filtro que traduz entre booleanos (inteiros C) e suas representações externas. Quando codifica dados, este filtro produz valores 1 ou 0. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_bytes(xdrs, sp, sizep, maxsize)
XDR *xdrs;
char **sp;
u_int *sizep, maxsize;

    Uma primitiva de filtro que traduz entre strings de bytes contados e suas representações externas. O parâmetro sp é o endereço do ponteiro de string. O comprimento da string é localizado no endereço sizep; strings não podem ser maiores que maxsize. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_char(xdrs, cp)
XDR *xdrs;
char *cp;

    Uma primitiva de filtro que traduz entre caracteres C e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0. Nota: caracteres codificados não são empacotados, e ocupam 4 bytes cada. Para matrizes de caracteres, vale a pena considerar xdr_bytes(), xdr_opaque() ou xdr_string().

void
xdr_destroy(xdrs)
XDR *xdrs;

    Uma macro que invoca a rotina destrutiva associada com o fluxo XDR, xdrs. Destruição geralmente envolve a liberação de estruturas de dados privativas associadas com o fluxo. O uso de xdrs depois de invocar xdr_destroy() é indefinido.

xdr_double(xdrs, dp)
XDR *xdrs;
double *dp;

    Uma primitiva de filtro que traduz entre números de precisão dupla do C e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_enum(xdrs, ep)
XDR *xdrs;
enum_t *ep;

    Uma primitiva de filtro que traduz entre enums da linguagem C (atualmente inteiros) e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_float(xdrs, fp)
XDR *xdrs;
float *fp;

    Uma primitiva de filtro que traduz entre floats da linguagem C e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

void
xdr_free(proc, objp)
xdrproc_t proc;
char *objp;

    Rotina de liberação genérica. O primeiro argumento é a rotina XDR para o objeto sendo liberado. O segundo argumento é um ponteiro para o próprio objeto. Nota: o ponteiro passado para esta rotina não é liberado, mas aquele para o qual ele aponta é liberado (recursivamente).

u_int
xdr_getpos(xdrs)
XDR *xdrs;

    Uma macro que invoca a rotina 'pega-posição' associada com o fluxo XDR, xdrs. A rotina retorna um inteiro sem sinal, que indica a posição do fluxo de bytes XDR. Uma implementação desejável do fluxo XDR é que aritmética simples funcione com este número, apesar de que instâncias do fluxo XDR não precisam garantir isso.

long *
xdr_inline(xdrs, len)
XDR *xdrs;
int len;

    Uma macro que invoca a rotina 'em-linha' associada com o fluxo XDR, xdrs. A rotina retorna um ponteiro para uma parte contígua do 'buffer' do fluxo; len é o comprimento em bytes do 'buffer' desejado. Nota: o ponteiro é um 'cast' para long *.

    Atenção: xdr_inline() pode retornar NULO 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.

xdr_int(xdrs, ip)
XDR *xdrs;
int *ip;

    Uma primitiva de filtro que traduz entre inteiros do C e suas representações externas. Estas rotinas retornam 1 se forem bem sucedidas, e 0 em caso contrário.

xdr_long(xdrs, lp)
XDR *xdrs;
long *lp;

    Uma primitiva de filtro que traduz entre inteiros longos do C e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

void
xdrmem_create(xdrs, addr, size, op)
XDR *xdrs;
char *addr;
u_int size;
enum xdr_op op;

    Esta rotina inicializa o objeto de fluxo XDR apontado por xdrs. Os dados do fluxo são escritos ou lidos de um pedaço de memória na posição addr, cujo comprimento não é maior que size bytes. O op determina a direção do fluxo XDR ( ambas XDR_ENCODE, XDR_DECODE, ou XDR_FREE).

xdr_opaque(xdrs, cp, cnt)
XDR *xdrs;
char *cp;
u_int cnt;

    Uma primitiva de filtro que traduz entre dados opacos de tamanho fixo e sua representação externa. O parâmetro cp é o endereço do objeto opaco, e cnt é o seu tamanho em bytes. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_pointer(xdrs, objpp, objsize, xdrobj)
XDR *xdrs;
char **objpp;
u_int objsize;
xdrproc_t xdrobj;

    Como xdr_reference() se excetua pelo fato de serializar ponteiros NULO, uma vez que xdr_reference() não o faz. Portanto, xdr_pointer() pode representar estruturas de dados recursivos, como árvores binárias ou listas ligadas.

void
xdrrec_create(xdrs, sendsize, recvsize, handle, readit, writeit)
XDR *xdrs;
u_int sendsize, recvsize;
char *handle;
int (*readit) (), (*writeit) ();

    Esta rotina inicializa o objeto de fluxo XDR apontado por xdrs. Os dados do fluxo são escritos em um 'buffer' de tamanho sendsize; um valor 0 indica que o sistema deve usar um padrão conveniente. Os dados do fluxo são lidos de um 'buffer' de tamanho. 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, writeit é chamado. Similarmente, quando um 'buffer' de entrada do fluxo está vazio, readit é chamado. O comportamento destas duas rotinas é similar às chamadas de sistema read e write, exceto pelo fato de que handle é passado para a antiga rotina como o primeiro parâmetro. Nota: o campo op do fluxo XDR precisa ser setado pelo chamador.

    Atenção: este fluxo XDR implementa um fluxo de registro intermediário. Portanto, há bytes adicionais no fluxo para prover informações de limite de registro.

xdrrec_endofrecord(xdrs, sendnow)
XDR *xdrs;
int sendnow;

    Esta rotina pode ser invocada somente em fluxos criados por 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 sendnow não é zero. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdrrec_eof(xdrs)
XDR *xdrs;
int empty;

    Esta rotina pode ser invocada somente em fluxos criados por xdrrec_create(). Depois de consumir o resto do registro corrente no fluxo, esta rotina retorna 1 se o fluxo não tiver mais entradas, e 0 em caso contrário.

xdrrec_skiprecord(xdrs)
XDR *xdrs;

    Esta rotina pode ser invocada somente em fluxos criados por xdrrec_create(). Ele diz à implementação XDR que o resto do registro corrente no 'buffer' de entrada do fluxo deve ser descartado. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_reference(xdrs, pp, size, proc)
XDR *xdrs;
char **pp;
u_int size;
xdrproc_t proc;

    Uma primitiva que fornece perseguição a ponteiros dentro de estruturas. O parâmetro pp é o endereço do ponteiro; size é a estrutura sizeof para o qual *pp aponta; e proc é um procedimento XDR que filtra a estrutura entre sua forma C e sua representação externa. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

    Atenção: esta rotina não entende ponteiros do tipo NULO. Use xdr_pointer() no lugar.

xdr_setpos(xdrs, pos)
XDR *xdrs;
u_int pos;

    Uma macro que invoca a rotina de posição setada associada com o fluxo XDR, xdrs. O parâmetro pos é um valor de posição obtido de xdr_getpos(). Esta rotina retorna 1 se o fluxo XDR não pode ser reposicionado, e 0 em caso contrário.

    Atenção: é difícil reposicionar alguns tipos de fluxos XDR, assim esta rotina pode falhar com um tipo de fluxo e funcionar com outro.

xdr_short(xdrs, sp)
XDR *xdrs;
short *sp;

    Uma primitiva de filtro que traduz entre inteiros curtos do C e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

void
xdrstdio_create(xdrs, file, op)
XDR *xdrs;
FILE *file;
enum xdr_op op;

    Esta rotina inicializa o objeto de fluxo XDR apontado por xdrs. Os dados do fluxo XDR são escritos ou lidos do arquivo de fluxo padrão de E/S. O parâmetro op determina a direção do fluxo XDR ( XDR_ENCODE, XDR_DECODE, ou XDR_FREE).

    Atenção: a rotina de destruição associada com tais rotinas de chamada de fluxo XDR, tais como fflush() sobre o fluxo de arquivo , mas nunca fclose().

xdr_string(xdrs, sp, maxsize)
XDR
*xdrs;
char **sp;
u_int maxsize;

    Uma primitiva de filtro que traduz entre strings C e suas representações externas correspondentes. Strings não podem ser maiores que maxsize. Nota: sp é o endereço do ponteiro da string. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_u_char(xdrs, ucp)
XDR *xdrs;
unsigned char *ucp;

    Uma primitiva de filtro que traduz entre caracteres C sem sinal e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_u_int(xdrs, up)
XDR *xdrs;
unsigned *up;

    Uma primitiva de filtro que traduz entre inteiros sem sinal do C e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_u_long(xdrs, ulp)
XDR *xdrs;
unsigned long *ulp;

    Uma primitiva de filtro que traduz entre inteiros longos sem sinal do C e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_u_short(xdrs, usp)
XDR *xdrs;
unsigned short *usp;

    Uma primitiva de filtro que traduz entre inteiros curtos sem sinal do C e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_union(xdrs, dscmp, unp, choices, dfault)
XDR *xdrs;
int *dscmp;
char *unp;
struct xdr_discrim *choices;
bool_t (*defaultarm) ();  /* may equal NULL */

    Uma primitiva de filtro que traduz entre uma union discriminada do C e sua representação externa correspondente. Ela primeiro traduz o discriminante da união localizado em dscmp. Este discriminante é sempre um enum_t. A seguir, a união localizada em unp é traduzida. O parâmetro choices é um ponteiro para uma matriz de estruturas xdr_discrim(). Cada estrutura contém um par ordenado de [value,proc]. Se o discriminante da união é igual ao valor associado, então proc é chamado para traduzir a união. O fim da matriz de estrutura xdr_discrim() é denotada por uma rotina de valor NULO. Se o discriminante não é encontrado na matriz choices, então o procedimento defaultarm é chamado (se ele não for NULO). Retorna 1 se for bem sucedida, e 0 em caso contrário.

xdr_vector(xdrs, arrp, size, elsize, elproc)
XDR *xdrs;
char *arrp;
u_int size, elsize;
xdrproc_t elproc;

    Uma primitiva de filtro que traduz entre matrizes de comprimento fixo e suas representações externas correspondentes. O parâmetro arrp é o endereço do ponteiro para a matriz, enquanto size é o elemento 'count' da matriz. O parâmetro elsize é o sizeof de cada um dos elementos da matriz, e elproc é um filtro XDR que traduz entre o formato dos elementos da matriz em C e suas representações externas. Em caso de sucesso, esta rotina, devolve 1, caso contrário 0.

xdr_void()

    Esta rotina sempre retorna 1. Ela pode ser passada para rotinas RPC que requerem um parâmetro de função, onde nada vai ser feito.

xdr_wrapstring(xdrs, sp)
XDR *xdrs;
char **sp;

    Uma primitiva que chama xdr_string(xdrs, sp,MAXUN.UNSIGNED ); onde MAXUN.UNSIGNED é o valor máximo de um inteiro sem sinal. xdr_wrapstring() está à mão porque o pacote RPC passa um máximo de duas rotinas XDR como parâmetros, e xdr_string(), uma das primitivas mais frequentemente usadas, requer três. Retorna 1 se for bem sucedida, e 9 em caso contrário.

VEJA TAMBÉM
rpc(3N)

Os seguintes manuais:
    eXternal Data Representation Standard: Protocol Specification,
    eXternal Data Representation: Sun Technical Notes,
    XDR: External Data Representation Standard, RFC1014, Sun Microsystems, Inc., USC-ISI.

TRADUZIDO POR LDP-BR em 21/08/2000.

  Tradução:
Rubens de Jesus Nogueira <darkseid99@usa.net>

  Revisão:
André Luiz Fassone <lonely_wolf@ig.com.br>