*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> xdr_array (3)              
Title
Content
Arch
Section
 

xdr(3)

Contents


NAME    [Toc]    [Back]

       xdr,    xdr_array,    xdr_bool,    xdr_bytes,    xdr_char,
       xdr_destroy, xdr_double,  xdr_enum,  xdr_float,  xdr_free,
       xdr_functions, xdr_getpos, xdr_hyper, xdr_inline, xdr_int,
       xdr_long,    xdr_longlong_t,     xdr_opaque,     xdr_pmap,
       xdr_pmaplist,   xdr_pointer,   xdr_reference,  xdr_setpos,
       xdr_short, xdr_string, xdr_u_char, xdr_u_hyper, xdr_u_int,
       xdr_u_long,   xdr_u_longlong_t,   xdr_u_short,  xdr_union,
       xdr_vector, xdr_void, xdr_wrapstring, xdrmem_create,  xdrrec_create,
 xdrrec_endofrecord, xdrrec_eof, xdrrec_skiprecord,
 xdrstdio_create - library routines for external data
       representation

SYNOPSIS    [Toc]    [Back]

       #include <rpc/xdr.h>

       xdr_array(
               XDR *xdrs,
               char **arrp,
               u_int *sizep,
               u_int *maxsize,
               u_int *elsize,
               xdrproc_t elproc ); xdr_bool(
               XDR *xdrs,
               bool_t bp ); xdr_bytes(
               XDR *xdrs,
               char **sp,
               u_int *sizep,
               u_int maxsize ); xdr_char(
               XDR *xdrs,
               char*cp ); void xdr_destroy(
               XDR *xdrs ); xdr_double(
               XDR *xdrs,
               double *dp ); xdr_enum(
               XDR *xdrs,
               enum_t *ep ); xdr_float(
               XDR *xdrs,
               float *fp ); void xdr_free(
               xdrproc_t proc,
               char *objp ); u_int xdr_getpos(
               XDR *xdrs ); xdr_hyper(
               XDR *xdrs,
               longlong_t *hp ); long *xdr_inline(
               XDR *xdrs,
               int len ); xdr_int(
               XDR *xdrs,
               int *ip ); xdr_long(
               XDR *xdrs,
               long *lp ); xdr_longlong_t(
               XDR *xdrs,
               longlong_t *hp ); xdr_opaque(
               XDR *xdrs,
               char *cp,
               u_int cnt ); xdr_pmap(
               XDR *xdrs,
               struct pmap *regs ); xdr_pmaplist(
               XDR *xdrs,
               struct pmaplist **rp ); xdr_pointer(
               XDR *xdrs,
               char **objpp,
               u_int objsize,
               xdrproc_t xdrobj ); xdr_reference(
               XDR *xdrs,
               char **pp,
               u_int size,
               xdrproc_t proc ); xdr_setpos(
               XDR *xdrs,
               u_int pos ); xdr_short(
               XDR *xdrs,
               short *sp ); xdr_string(
               XDR *xdrs,
               char **sp,
               u_int maxsize ); xdr_u_char(
               XDR *xdrs,
               unsigned char *ucp ); xdr_u_hyper(
               XDR *xdrs,
               u_longlong_t *uhp ); xdr_u_int(
               XDR *xdrs,
               unsigned *up ); xdr_u_long(
               XDR *xdrs,
               unsigned long *ulp ); xdr_u_longlong_t(
               XDR *xdrs,
               u_longlong_t *uhp ); xdr_u_short(
               XDR *xdrs,
               unsigned short *usp ); xdr_union(
               XDR *xdrs,
               int *dscmp,
               char *unp,
               struct xdr_discrim *choices,
               bool_t (*defaultarm) (void) ); xdr_vector(
               XDR *xdrs,
               char *arrp,
               u_int size,
               u_int elsize,
               xdrproc_t elproc ); xdr_void(
               void ); xdr_wrapstring(
               XDR *xdrs,
               char **sp ); void xdrmem_create(
               XDR *xdrs,
               char *addr,
               u_int size,
               enum xdr_op op ); void xdrrec_create(
               XDR *xdrs,
               u_int sendsize,
               u_int recvsize,
               char *handle,
               int (*readit) (void),
               int (*writeit) (void) ); xdrrec_endofrecord(
               XDR *xdrs,
               int sendnow ); xdrrec_eof(
               XDR *xdrs,
               int empty ); xdrrec_skiprecord(
               XDR *xdrs ); void xdrstdio_create(
               XDR *xdrs,
               FILE *file,
               enum xdr_op op );

DESCRIPTION    [Toc]    [Back]

       These  routines  allow C programmers to describe arbitrary
       data structures in a machine-independent fashion. Data for
       ONC  remote procedure calls are transmitted using the following
 routines:

       A filter primitive that translates between variable-length
       arrays  and  their corresponding external representations.
       The arrp parameter is the address of the  pointer  to  the
       array,  while sizep is the address of the element count of
       the array; this element count cannot exceed  maxsize.  The
       elsize parameter is the sizeof of each of the array's elements,
 and elproc is an XDR filter that translates between
       the  array elements' C form and their external representation.
 This routine returns one (1) if  it  succeeds,  zero
       (0) otherwise.  A filter primitive that translates between
       Booleans (C integers) and their external  representations.
       When  encoding data, this filter produces values of either
       one (1) or zero (0). This routine returns one  (1)  if  it
       succeeds,  zero  (0)  otherwise.   A filter primitive that
       translates between counted byte strings and their external
       representations.   The  sp parameter is the address of the
       string pointer.  The length of the string  is  located  at
       address sizep; strings cannot be longer than maxsize. This
       routine returns one (1) if it succeeds,  zero  (0)  otherwise.
   A filter primitive that translates between C characters
 and their external representations.   This  routine
       returns  one (1) if it succeeds, zero (0) otherwise. Note:
       Encoded characters are not packed and occupy 4 bytes each.
       For  arrays  of  characters,  it is worthwhile to consider
       xdr_bytes(), xdr_opaque(), or xdr_string().  A macro  that
       invokes  the  destroy  routine  associated  with  the  XDR
       stream, xdrs. Destruction usually involves freeing private
       data  structures  associated  with  the stream. Using xdrs
       after invoking xdr_destroy() is undefined.  A filter primitive
  that  translates between C double-precision numbers
       and their external representations.  This routine  returns
       one  (1)  if  it  succeeds,  zero (0) otherwise.  A filter
       primitive that translates between C enums (actually  integers)
  and  their  external representations.  This routine
       returns one (1) if it succeeds,  zero  (0)  otherwise.   A
       filter  primitive  that  translates  between  C floats and
       their external representations. This routine  returns  one
       (1) if it succeeds, zero (0) otherwise.  A generic freeing
       routine. The first argument is the  XDR  routine  for  the
       object  being  freed.  The second argument is a pointer to
       the object itself. Note: The pointer passed to  this  routine
  is not freed, but what it points to is freed (recursively).
  A macro that invokes  the  get-position  routine
       associated  with the XDR stream, xdrs. The routine returns
       an unsigned integer, which indicates the position  of  the
       XDR  byte  stream.  A  desirable feature of XDR streams is
       that simple arithmetic works with  this  number,  although
       the  XDR stream instances need not guarantee this.  A filter
 primitive that translates between C long integers  and
       their external representations. (The typedef longlong_t is
       defined as  long  in  the  <rpc/types.h>  file,  which  is
       included  from  the  <rpc/xdr.h>  file.) This routine will
       translate all 8 bytes of data to the XDR stream. Note that
       this  differentiates  this routine from xdr_long() in that
       they both take a pointer to a long as an  argument,  while
       xdr_long()  only  translates  4  bytes  of data to the XDR
       stream. This routine returns one (1) if it succeeds,  zero
       (0) otherwise.

              The  xdr_hyper() routine is functionally equivalent
              to the xdr_longlong_t() routine.

              See the next section for an explanation of the differences
   betweenxdr_long()  and  xdr_hyper().   A
              macro that invokes the in-line  routine  associated
              with  the  XDR stream, xdrs.  The routine returns a
              pointer to  a  contiguous  piece  of  the  stream's
              buffer;  len  is  the  byte  length  of the desired
              buffer. Note: Pointer is cast to long *.

              Warning: xdr_inline() may return NULL if it  cannot
              allocate a contiguous piece of a buffer. Therefore,
              the behavior may vary among  stream  instances;  it
              exists for the sake of efficiency.  A filter primitive
 that translates between C integers  and  their
              external  representations. This routine returns one
              (1) if it succeeds, zero (0) otherwise.   A  filter
              primitive  that  translates between C long integers
              and their external representations.   This  routine
              returns one (1) if it succeeds, zero (0) otherwise.

              Note that the lp argument must be the C type  long.
              The  amount  of  data  encoded to the XDR stream is
              only 4 bytes (not the full 8 bytes of  data  represented
 by the C long type).  This is because a long
              type is considered to be 4 bytes in the context  of
              XDR  streams.  When  data  is  encoded from the XDR
              stream, 4 bytes  will  be  received  from  the  XDR
              stream;  the xdr_long() interface then sign extends
              the high-order 4 bytes of the C long type.

              Prior to serializing the data on the  ENCODE  side,
              xdr_long() performs a validity check to ensure that
              the value represents a valid 32-bit signed  number.
              This  involves determining that the signed value is
              no less than the most negative 32-bit signed  quantity
  (which  is  the hexadecimal value 0x80000000)
              and no greater than the most positive 32-bit signed
              quantity    (which   is   the   hexadecimal   value
              0x7fffffff). If the value  pointed  to  by  the  lp
              argument  is  not within this range, the xdr_long()
              interface returns an error.

              To translate the full 8 bytes of a C long, use  the
              xdr_hyper() interface.

              See the next section for an explanation of the differences
 between  xdr_long()  and  xdr_hyper().   A
              filter  primitive  that  translates  between C long
              integers and their external  representations.  (The
              typedef  longlong_t  is  defined  as  long  in  the
              <rpc/types.h> file,  which  is  included  from  the
              <rpc/xdr.h>  file.) This routine will translate all
              8 bytes of data to the XDR stream. Note  that  this
              differentiates this routine from xdr_long() in that
              they both take a pointer to a long as an  argument,
              while xdr_long() only translates 4 bytes of data to
              the XDR stream. This routine returns one (1) if  it
              succeeds, zero (0) otherwise.

              The xdr_longlong_t() routine is functionally equivalent
 to the xdr_hyper() routine.

              See the next section for an explanation of the differences
  between  xdr_long()  and  xdr_hyper().  A
              filter primitive that translates between fixed size
              opaque  data  and its external representation.  The
              cp parameter is the address of the  opaque  object,
              and  cnt is its size in bytes. This routine returns
              one (1) if it succeeds, zero (0)  otherwise.   Used
              for describing parameters to various portmap procedures,
 externally. This routine is useful for users
              who wish to generate these parameters without using
              the pmap interface.  Used for describing a list  of
              port  mappings,  externally. This routine is useful
              for users who wish  to  generate  these  parameters
              without    using    the   pmap   interface.    Like
              xdr_reference()  except  that  it  serializes  NULL
              pointers,  whereas  xdr_reference() does not. Thus,
              xdr_pointer() can represent recursive  data  structures,
  such  as  binary  trees or linked lists.  A
              primitive  that  provides  pointer  chasing  within
              structures.  The pp parameter is the address of the
              pointer; size is the sizeof of the  structure  that
              *pp  points  to;  and proc is an XDR procedure that
              filters the structure between its C  form  and  its
              external  representation.  This routine returns one
              (1) if it succeeds, zero (0) otherwise.

              Warning: This  routine  does  not  understand  NULL
              pointers.  Use xdr_pointer() instead.  A macro that
              invokes the set position  routine  associated  with
              the  XDR stream, xdrs. The pos parameter is a position
 value obtained from xdr_getpos(). This routine
              returns  one (1) if the XDR stream could be repositioned,
 and zero (0) otherwise.

              Warning: It is difficult to reposition  some  types
              of  XDR  streams, so this routine may fail with one
              type of stream and succeed with another.  A  filter
              primitive  that translates between C short integers
              and their external  representations.  This  routine
              returns one (1) if it succeeds, zero (0) otherwise.
              A  filter  primitive  that  translates  between   C
              strings  and their corresponding external representations.
  Strings cannot be  longer  than  maxsize.
              The  sp  parameter  is  the address of the string's
              pointer. While encoding, if sp is NULL, an error is
              returned.  While decoding, if *sp is NULL, the necessary
 storage is allocated to hold this  null-terminated
  string  and  *sp  is set to point to this.
              This storage can be freed by using xdr_free(). This
              routine  returns  one  (1) if it succeeds, zero (0)
              otherwise.   A  filter  primitive  that  translates
              between  unsigned  C  characters and their external
              representations.  This routine returns one  (1)  if
              it  succeeds,  zero (0) otherwise.  A filter primitive
 that translates between C unsigned long  integers
 and their external representations. (The typedef
 u_longlong_t is defined as unsigned long in the
              <rpc/types.h>  file,  which  is  included  from the
              <rpc/xdr.h> file.) This routine will translate  all
              8  bytes of data to the XDR stream.  Note that this
              differentiates this routine  from  xdr_u_long()  in
              that  they  both take a pointer to an unsigned long
              as an argument, while xdr_u_long() only  translates
              4  bytes  of  data  to the XDR stream. This routine
              returns one (1) if it succeeds, zero (0) otherwise.

              The  xdr_u_hyper()  routine is functionally equivalent
 to the xdr_u_longlong_t() routine.

              See the next section for an explanation of the differences
  between  xdr_long()  and  xdr_hyper().  A
              filter primitive that translates between C unsigned
              integers  and their external representations.  This
              routine returns one (1) if it  succeeds,  zero  (0)
              otherwise.   A  filter  primitive  that  translates
              between C unsigned long integers and their external
              representations. This routine returns one (1) if it
              succeeds, zero (0) otherwise.

              Prior to serializing the data on the  ENCODE  side,
              xdr_u_long()  performs  a  validity check to insure
              that the value represents a valid  32-bit  unsigned
              number. This involves determining that the unsigned
              value  is  no  greater  than  the  largest   32-bit
              unsigned  quantity  (which is the hexadecimal value
              0xffffffff). If the value pointed  to  by  the  ulp
              argument is not within this range, the xdr_u_long()
              interface returns an error.

              For DECODE operations, the 32-bit unsigned value is
              sign   extended   into  the  64-bit  unsigned  long
              referred to by the ulp argument.

              Note that this routine actually translates 4  bytes
              of the data to or from the XDR stream. Refer to the
              description  of  xdr_long()  for  a  more  detailed
              explanation.   A  filter  primitive that translates
              between C unsigned long integers and their external
              representations.   (The   typedef  u_longlong_t  is
              defined as unsigned long in the <rpc/types.h> file,
              which  is included from the <rpc/xdr.h> file.) This
              routine will translate all 8 bytes of data  to  the
              XDR  stream.   Note  that  this differentiates this
              routine from xdr_u_long() in that they both take  a
              pointer  to  an unsigned long as an argument, while
              xdr_u_long() only translates 4 bytes of data to the
              XDR stream. This routine returns one (1) if it succeeds,
 zero (0) otherwise.

              The xdr_u_longlong routine is functionally  equivalent
 to the xdr_u_hyper() routine.

              See the next section for an explanation of the differences
 between  xdr_long()  and  xdr_hyper().   A
              filter primitive that translates between C unsigned
              short integers and their external  representations.
              This  routine  returns one (1) if it succeeds, zero
              (0) otherwise.  A filter primitive that  translates
              between a discriminated C union and its corresponding
 external representation.  It  first  translates
              the  discriminant  of  the  union located at dscmp.
              This discriminant is always an  enum_t.  Next,  the
              union  located  at  unp  is translated. The choices
              parameter is a pointer to an array  of  xdr_discrim
              structures. Each structure contains an ordered pair
              of [value,proc]. If  the  union's  discriminant  is
              equal  to any of the values, the associated proc is
              called to translate  the  union.  The  end  of  the
              xdr_discrim  structure  array  is denoted by a NULL
              pointer. If the discriminant is not  found  in  the
              choices  array,  then  the  defaultarm procedure is
              called (if it is not NULL). Returns one (1)  if  it
              succeeds,  zero  (0) otherwise.  A filter primitive
              that translates  between  fixed-length  arrays  and
              their  corresponding  external representations. The
              arrp parameter is the address of the  array,  while
              size  is the element count of the array. The elsize
              parameter is the sizeof of each of the array's elements,
  and elproc is an XDR filter that translates
              between the array elements' C form and their external
 representation. This routine returns one (1) if
              it succeeds,  zero  (0)  otherwise.   This  routine
              always  returns  one  (1).  It may be passed to RPC
              routines that require  a  function  parameter,  but
              where  nothing  is  to  be  done.  A primitive that
              calls    xdr_string(xdrs,sp,MAXUNSIGNED);     where
              MAXUNSIGNED  is  the  maximum  value of an unsigned
              integer. The xdr_wrapstring()  primitive  is  handy
              because the RPC package passes a maximum of two XDR
              routines as parameters, and  xdr_string(),  one  of
              the   most  frequently  used  primitives,  requires
              three. The sp  parameter  is  the  address  of  the
              pointer  to  the  string.  While decoding, if sp is
              NULL, the necessary storage is  allocated  to  hold
              the  null-terminated  string and sp is set to point
              to  this.  This  storage  can  be  freed  by  using
              xdr_free().  Returns  one  (1) if it succeeds, zero
              (0) otherwise.  This routine  initializes  the  XDR
              stream  object  pointed  to  by xdrs.  The stream's
              data is written to, or read from, a chunk of memory
              at  location addr whose length is no more than size
              bytes long. The op determines the direction of  the
              XDR   stream  (either  XDR_ENCODE,  XDR_DECODE,  or
              XDR_FREE).  This routine initializes the XDR stream
              object  pointed  to  by xdrs.  The stream's data is
              written to a buffer of size sendsize;  a  value  of
              zero (0) indicates the system should use a suitable
              default. The stream's data is read from a buffer of
              size  recvsize;  it  too  can  be set to a suitable
              default  by  passing  a  zero  (0)  value.  When  a
              stream's  output buffer is full, writeit is called.
              Similarly, when a stream's input buffer  is  empty,
              readit  is  called.  The behavior of these two routines
 is similar to the  system  calls  read()  and
              write(), except that handle is passed to the former
              routines as the first parameter.  The XDR  stream's
              op  field  must be set by the caller.  The sendsize
              and recvsize parameters should be multiples of 4.

              Warning: This XDR stream implements an intermediate
              record stream. Therefore there are additional bytes
              in the stream to provide record  boundary  information.
   This routine can be invoked only on streams
              created by xdrrec_create().  The data in the output
              buffer  is  marked  as  a completed record, and the
              output buffer is optionally written out if  sendnow
              is nonzero. This routine returns one (1) if it succeeds,
 zero (0) otherwise.   This  routine  can  be
              invoked only on streams created by xdrrec_create().
              After consuming the rest of the current  record  in
              the  stream,  this  routine  returns one (1) if the
              stream has no more input, zero (0) otherwise.  This
              routine  can  be invoked only on streams created by
              xdrrec_create().  It tells the  XDR  implementation
              that the rest of the current record in the stream's
              input buffer  should  be  discarded.  This  routine
              returns one (1) if it succeeds, zero (0) otherwise.
              This routine  initializes  the  XDR  stream  object
              pointed to by xdrs.  The XDR stream data is written
              to, or read from, the Standard I/O stream file. The
              op  parameter  determines  the direction of the XDR
              stream   (either   XDR_ENCODE,    XDR_DECODE,    or
              XDR_FREE).

              Warning:  The  destroy routine associated with such
              XDR streams calls fflush() on the file stream,  but
              never fclose().






   Differences Between xdr_long and xdr_hyper Routines    [Toc]    [Back]
       On  Tru64  UNIX  platforms, the C programming language and
       the XDR routines apply different conventions to the  definitions
 of the long data type.

       On  Tru64  UNIX  platforms,  the  C  programming  language
       applies the following conventions for int  and  long  data
       types:

       ---------------------------
       Data Type   bits   bytes
       ---------------------------
       int         32     4 bytes
       long        64     8 bytes
       ---------------------------

       The XDR routines apply the following conventions:

       ---------------------------
       Data Type   bits   bytes
       ---------------------------
       int         32     4 bytes
       long        32     4 bytes
       hyper       64     8 bytes
       ---------------------------

       The  xdr_long()  and  xdr_u_long()  interfaces serialize 4
       bytes of data. The xdr_hyper()  and  xdr_u_hyper()  interfaces
 serialize 8 bytes of data.

       On  Tru64  UNIX  systems,  the  second  argument  to  both
       xdr_long() and xdr_hyper() must be either a pointer or  of
       the  C  language  type long (8 bytes). When xdr_hyper() is
       called with a parameter that points to a long, all 8 bytes
       are  serialized.  In  contrast,  when xdr_long() is called
       with a parameter that points to a long, only the low-order
       4 bytes are serialized.

       When calling xdr_long() on the DECODE operation, the upper
       4 bytes of the long are sign extended in  accordance  with
       the  high-order bit of the lower 4-byte quantity.  This is
       necessary to maintain the  XDR  convention  of  xdr_long()
       serializing 4 bytes.

       If  you  want  all  8  bytes  to  be  serialized,  use the
       xdr_hyper() interface.

       The  xdr_longlong_t()  and  xdr_u_longlong_t()  interfaces
       perform  the  same  function  as  the  xdr_hyper() and the
       xdr_u_hyper() interfaces, respectively.

SEE ALSO    [Toc]    [Back]

      
      
       Routines: rpc(3),  rpc_clnt(3),  rpc_misc(3),  rpc_svc(3),
       rpc_xdr(3)



                                                           xdr(3)
[ Back ]
 Similar pages
Name OS Title
xdr IRIX External Data Representation (XDR) library routines
xdr_create IRIX library routines for external data representation stream creation
des_crypt Tru64 Data Encryption Standard (DES) encryption library routines (Auth)
des_quad_cksum Tru64 Data Encryption Standard (DES) encryption library routines (Auth)
des_string_to_key Tru64 Data Encryption Standard (DES) encryption library routines (Auth)
des_key_sched Tru64 Data Encryption Standard (DES) encryption library routines (Auth)
des_is_weak_key Tru64 Data Encryption Standard (DES) encryption library routines (Auth)
unvis OpenBSD revert a visual representation of data back to original form
unvis FreeBSD revert a visual representation of data back to original form
XmRepTypeGetId Tru64 A representation type manager function that retrieves the identification number of a representation ...
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service