xdr_string(3nsl)

1xdr_complex(3NSL)    Networking Services Library Functions   xdr_complex(3NSL)
2
3
4

NAME

6       xdr_complex,  xdr_array, xdr_bytes, xdr_opaque, xdr_pointer, xdr_refer‐
7       ence, xdr_string, xdr_union, xdr_vector, xdr_wrapstring - library  rou‐
8       tines for external data representation
9

DESCRIPTION

11       XDR  library  routines  allow  C  programmers  to describe complex data
12       structures in a machine-independent fashion. Protocols such  as  remote
13       procedure  calls (RPC) use these routines to describe the format of the
14       data. These routines are the XDR  library  routines  for  complex  data
15       structures.  They  require  the  creation  of XDR streams. See xdr_cre‐
16       ate(3NSL).
17
18   Routines
19       See rpc(3NSL) for the definition of the XDR data structure.  Note  that
20       any  buffers passed to the XDR routines must be properly aligned. It is
21       suggested either that malloc() be used to allocate  these  buffers,  or
22       that the programmer insure  that the buffer address is divisible evenly
23       by four.
24
25
26       #include <rpc/xdr.h>
27
28       bool_t xdr_array(XDR *xdrs, caddr_t *arrp, uint_t *sizep, const uint_t
29       maxsize, const uint_t elsize, const xdrproc_t elproc);
30
31           xdr_array()  translates  between  variable-length  arrays and their
32           corresponding external representations. The parameter arrp  is  the
33           address  of the pointer to the array, while sizep is the address of
34           the element count of the array; this element  count  cannot  exceed
35           maxsize.  The  parameter  elsize is the size of each of the array's
36           elements, and elproc is an XDR routine that translates between  the
37           array  elements' C form and their external representation. If *aarp
38           is  NULL when decoding,  xdr_array()  allocates  memory  and  *aarp
39           points  to it. This routine returns TRUE if it succeeds, FALSE oth‐
40           erwise.
41
42
43       bool_t xdr_bytes(XDR *xdrs, char **sp, uint_t *sizep, const uint_t max‐
44       size);
45
46           xdr_bytes()  translates  between  counted  byte  strings  and their
47           external representations. The parameter sp is the  address  of  the
48           string  pointer.  The  length  of  the string is located at address
49           sizep; strings cannot be longer than maxsize. If *sp is  NULL  when
50           decoding,  xdr_bytes()  allocates memory and *sp points to it. This
51           routine returns TRUE if it succeeds, FALSE otherwise.
52
53
54       bool_t xdr_opaque(XDR *xdrs, caddr_t cp, const uint_t cnt);
55
56           xdr_opaque() translates between fixed  size  opaque  data  and  its
57           external  representation.  The  parameter  cp is the address of the
58           opaque object, and cnt is its size in bytes. This  routine  returns
59           TRUE if it succeeds, FALSE otherwise.
60
61
62       bool_t xdr_pointer(XDR *xdrs, char **objpp, uint_t objsize, const xdr‐
63       proc_t xdrobj);
64
65           Like xdr_reference()  except  that  it  serializes  null  pointers,
66           whereas  xdr_reference()  does not.  Thus, xdr_pointer() can repre‐
67           sent recursive data structures, such  as  binary  trees  or  linked
68           lists.  If  *objpp  is  NULL when decoding, xdr_pointer() allocates
69           memory and *objpp points to it.
70
71
72       bool_t xdr_reference(XDR *xdrs, caddr_t *pp, uint_t size, const xdr‐
73       proc_t proc);
74
75           xdr_reference()  provides  pointer  chasing within structures.  The
76           parameter pp is the address of the pointer; size is the sizeof  the
77           structure  that  *pp  points  to; and proc is an XDR procedure that
78           translates the structure between its C form and its external repre‐
79           sentation. If *pp is  NULL when decoding, xdr_reference() allocates
80           memory and *pp points to it.  This routine returns  1  if  it  suc‐
81           ceeds, 0 otherwise.
82
83           Warning:  this  routine  does  not  understand  null  pointers. Use
84           xdr_pointer() instead.
85
86
87       bool_t xdr_string(XDR *xdrs, char **sp, const uint_t maxsize);
88
89           xdr_string() translates between C strings and  their  corresponding
90           external  representations.  Strings  cannot be longer than maxsize.
91           Note: sp is the address of the string's pointer. If  *sp  is   NULL
92           when  decoding, xdr_string() allocates memory and *sp points to it.
93           This routine returns TRUE if it succeeds,  FALSE  otherwise.  Note:
94           xdr_string()  can  be  used to send an empty string (""), but not a
95           null string.
96
97
98       bool_t xdr_union(XDR *xdrs, enum_t *dscmp, char *unp, const struct
99       xdr_discrim *choices, const xdrproc_t (*defaultarm));
100
101           xdr_union() translates between a discriminated C union and its cor‐
102           responding external representation. It first  translates  the  dis‐
103           criminant  of  the  union  located  at  dscmp. This discriminant is
104           always an enum_t. Next the union located at unp is translated.  The
105           parameter  choices  is  a pointer to an array of xdr_discrim struc‐
106           tures. Each structure contains an ordered pair of [value, proc]. If
107           the union's discriminant is equal to the associated value, then the
108           proc is called to translate the union. The end of  the  xdr_discrim
109           structure  array is denoted by a routine of value NULL. If the dis‐
110           criminant is not found in the choices array,  then  the  defaultarm
111           procedure is called (if it is not NULL). It returns TRUE if it suc‐
112           ceeds, FALSE otherwise.
113
114
115       bool_t xdr_vector(XDR *xdrs, char *arrp, const uint_t size, const
116       uint_t elsize, const xdrproc_t elproc);
117
118           xdr_vector()  translates between fixed-length arrays and their cor‐
119           responding external representations.  The  parameter  arrp  is  the
120           address  of  the  pointer  to  the array, while size is the element
121           count of the array. The parameter elsize is the sizeof each of  the
122           array's  elements,  and  elproc  is  an XDR routine that translates
123           between the array elements' C form and their  external  representa‐
124           tion. This routine returns TRUE if it succeeds, FALSE otherwise.
125
126
127       bool_t xdr_wrapstring(XDR *xdrs, char **sp);
128
129           A  routine  that calls xdr_string(xdrs, sp, maxuint); where maxuint
130           is the maximum value of an unsigned integer.
131
132           Many routines, such as xdr_array(), xdr_pointer(), and xdr_vector()
133           take  a function pointer of type xdrproc_t(), which takes two argu‐
134           ments. xdr_string(), one of  the  most  frequently  used  routines,
135           requires three arguments, while xdr_wrapstring() only requires two.
136           For these routines, xdr_wrapstring()  is  desirable.  This  routine
137           returns TRUE if it succeeds, FALSE otherwise.
138
139

ATTRIBUTES

141       See attributes(5) for descriptions of the following attributes:
142
143
144
145
146       ┌─────────────────────────────┬─────────────────────────────┐
147       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
148       ├─────────────────────────────┼─────────────────────────────┤
149       │MT-Level                     │Safe                         │
150       └─────────────────────────────┴─────────────────────────────┘
151

NAME

DESCRIPTION

ATTRIBUTES

SEE ALSO