man3/xdr.3

   1 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
   2 .\"
   3 .\" %%%LICENSE_START(BSD_ONELINE_CDROM)
   4 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
   5 .\" %%%LICENSE_END
   6 .\"
   7 .\" @(#)xdr.3n  2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
   8 .\"
   9 .\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
  10 .\"
  11 .TH XDR 3 2017-09-15 "" "Linux Programmer's Manual"
  12 .SH NAME
  13 xdr \- library routines for external data representation
  14 .SH SYNOPSIS AND DESCRIPTION
  15 .PP
  16 These routines allow C programmers to describe
  17 arbitrary data structures in a machine-independent fashion.
  18 Data for remote procedure calls are transmitted using these
  19 routines.
  20 .PP
  21 The prototypes below are declared in
  22 .I <rpc/xdr.h>
  23 and make use of the following types:
  24 .PP
  25 .in +4n
  26 .EX
  27 .BI "typedef int " bool_t ;
  28 .PP
  29 .BI "typedef bool_t (*" xdrproc_t ") (XDR *, void *,...);"
  30 .EE
  31 .in
  32 .PP
  33 For the declaration of the
  34 .I XDR
  35 type, see
  36 .IR <rpc/xdr.h> .
  37 .PP
  38 .nf
  39 .BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep ,
  40 .BI "                 unsigned int " maxsize ", unsigned int " elsize ,
  41 .BI "                 xdrproc_t " elproc );
  42 .fi
  43 .IP
  44 A filter primitive that translates between variable-length arrays
  45 and their corresponding external representations.
  46 The argument
  47 .I arrp
  48 is the address of the pointer to the array, while
  49 .I sizep
  50 is the address of the element count of the array;
  51 this element count cannot exceed
  52 .IR maxsize .
  53 The argument
  54 .I elsize
  55 is the
  56 .I sizeof
  57 each of the array's elements, and
  58 .I elproc
  59 is an XDR filter that translates between
  60 the array elements' C form, and their external
  61 representation.
  62 This routine returns one if it succeeds, zero otherwise.
  63 .PP
  64 .nf
  65 .BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp );
  66 .fi
  67 .IP
  68 A filter primitive that translates between booleans (C
  69 integers)
  70 and their external representations.
  71 When encoding data, this
  72 filter produces values of either one or zero.
  73 This routine returns one if it succeeds, zero otherwise.
  74 .PP
  75 .nf
  76 .BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep ,
  77 .BI "                 unsigned int " maxsize );
  78 .fi
  79 .IP
  80 A filter primitive that translates between counted byte
  81 strings and their external representations.
  82 The argument
  83 .I sp
  84 is the address of the string pointer.
  85 The length of the
  86 string is located at address
  87 .IR sizep ;
  88 strings cannot be longer than
  89 .IR maxsize .
  90 This routine returns one if it succeeds, zero otherwise.
  91 .PP
  92 .nf
  93 .BI "bool_t xdr_char(XDR *" xdrs ", char *" cp );
  94 .fi
  95 .IP
  96 A filter primitive that translates between C characters
  97 and their external representations.
  98 This routine returns one if it succeeds, zero otherwise.
  99 Note: encoded characters are not packed, and occupy 4 bytes each.
 100 For arrays of characters, it is worthwhile to
 101 consider
 102 .BR xdr_bytes (),
 103 .BR xdr_opaque ()
 104 or
 105 .BR xdr_string ().
 106 .PP
 107 .nf
 108 .BI "void xdr_destroy(XDR *" xdrs );
 109 .fi
 110 .IP
 111 A macro that invokes the destroy routine associated with the XDR stream,
 112 .IR xdrs .
 113 Destruction usually involves freeing private data structures
 114 associated with the stream.
 115 Using
 116 .I xdrs
 117 after invoking
 118 .BR xdr_destroy ()
 119 is undefined.
 120 .PP
 121 .nf
 122 .BI "bool_t xdr_double(XDR *" xdrs ", double *" dp );
 123 .fi
 124 .IP
 125 A filter primitive that translates between C
 126 .I double
 127 precision numbers and their external representations.
 128 This routine returns one if it succeeds, zero otherwise.
 129 .PP
 130 .nf
 131 .BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep );
 132 .fi
 133 .IP
 134 A filter primitive that translates between C
 135 .IR enum s
 136 (actually integers) and their external representations.
 137 This routine returns one if it succeeds, zero otherwise.
 138 .PP
 139 .nf
 140 .BI "bool_t xdr_float(XDR *" xdrs ", float *" fp );
 141 .fi
 142 .IP
 143 A filter primitive that translates between C
 144 .IR float s
 145 and their external representations.
 146 This routine returns one if it succeeds, zero otherwise.
 147 .PP
 148 .nf
 149 .BI "void xdr_free(xdrproc_t " proc ", char *" objp );
 150 .fi
 151 .IP
 152 Generic freeing routine.
 153 The first argument is the XDR routine for the object being freed.
 154 The second argument is a pointer to the object itself.
 155 Note: the pointer passed to this routine is
 156 .I not
 157 freed, but what it points to
 158 .I is
 159 freed (recursively).
 160 .PP
 161 .nf
 162 .BI "unsigned int xdr_getpos(XDR *" xdrs );
 163 .fi
 164 .IP
 165 A macro that invokes the get-position routine
 166 associated with the XDR stream,
 167 .IR xdrs .
 168 The routine returns an unsigned integer,
 169 which indicates the position of the XDR byte stream.
 170 A desirable feature of XDR
 171 streams is that simple arithmetic works with this number,
 172 although the XDR stream instances need not guarantee this.
 173 .PP
 174 .nf
 175 .BI "long *xdr_inline(XDR *" xdrs ", int " len );
 176 .fi
 177 .IP
 178 A macro that invokes the inline routine associated with the XDR stream,
 179 .IR xdrs .
 180 The routine returns a pointer
 181 to a contiguous piece of the stream's buffer;
 182 .I len
 183 is the byte length of the desired buffer.
 184 Note: pointer is cast to
 185 .IR "long\ *" .
 186 .IP
 187 Warning:
 188 .BR xdr_inline ()
 189 may return NULL (0)
 190 if it cannot allocate a contiguous piece of a buffer.
 191 Therefore the behavior may vary among stream instances;
 192 it exists for the sake of efficiency.
 193 .PP
 194 .nf
 195 .BI "bool_t xdr_int(XDR *" xdrs ", int *" ip );
 196 .fi
 197 .IP
 198 A filter primitive that translates between C integers
 199 and their external representations.
 200 This routine returns one if it succeeds, zero otherwise.
 201 .PP
 202 .nf
 203 .BI "bool_t xdr_long(XDR *" xdrs ", long *" lp );
 204 .fi
 205 .IP
 206 A filter primitive that translates between C
 207 .I long
 208 integers and their external representations.
 209 This routine returns one if it succeeds, zero otherwise.
 210 .PP
 211 .nf
 212 .BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size ,
 213 .BI "                   enum xdr_op " op );
 214 .fi
 215 .IP
 216 This routine initializes the XDR stream object pointed to by
 217 .IR xdrs .
 218 The stream's data is written to, or read from,
 219 a chunk of memory at location
 220 .I addr
 221 whose length is no more than
 222 .I size
 223 bytes long.
 224 The
 225 .I op
 226 determines the direction of the XDR stream (either
 227 .BR XDR_ENCODE ,
 228 .BR XDR_DECODE ,
 229 or
 230 .BR XDR_FREE ).
 231 .PP
 232 .nf
 233 .BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt );
 234 .fi
 235 .IP
 236 A filter primitive that translates between fixed size opaque data
 237 and its external representation.
 238 The argument
 239 .I cp
 240 is the address of the opaque object, and
 241 .I cnt
 242 is its size in bytes.
 243 This routine returns one if it succeeds, zero otherwise.
 244 .PP
 245 .nf
 246 .BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp ,
 247 .BI "                   unsigned int " objsize ", xdrproc_t " xdrobj );
 248 .fi
 249 .IP
 250 Like
 251 .BR xdr_reference ()
 252 except that it serializes null pointers, whereas
 253 .BR xdr_reference ()
 254 does not.
 255 Thus,
 256 .BR xdr_pointer ()
 257 can represent
 258 recursive data structures, such as binary trees or
 259 linked lists.
 260 .PP
 261 .nf
 262 .BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize ,
 263 .BI "                   unsigned int " recvsize ", char *" handle ,
 264 .BI "                   int (*" readit ") (char *, char *, int),"
 265 .BI "                   int (*" writeit ") (char *, char *, int));"
 266 .fi
 267 .IP
 268 This routine initializes the XDR stream object pointed to by
 269 .IR xdrs .
 270 The stream's data is written to a buffer of size
 271 .IR sendsize ;
 272 a value of zero indicates the system should use a suitable default.
 273 The stream's data is read from a buffer of size
 274 .IR recvsize ;
 275 it too can be set to a suitable default by passing a zero value.
 276 When a stream's output buffer is full,
 277 .I writeit
 278 is called.
 279 Similarly, when a stream's input buffer is empty,
 280 .I readit
 281 is called.
 282 The behavior of these two routines is similar to
 283 the system calls
 284 .BR read (2)
 285 and
 286 .BR write (2),
 287 except that
 288 .I handle
 289 is passed to the former routines as the first argument.
 290 Note: the XDR stream's
 291 .I op
 292 field must be set by the caller.
 293 .IP
 294 Warning: to read from an XDR stream created by this API,
 295 you'll need to call
 296 .BR xdrrec_skiprecord ()
 297 first before calling any other XDR APIs.
 298 This inserts additional bytes in the stream to provide
 299 record boundary information.
 300 Also, XDR streams created with different
 301 .BR xdr*_create
 302 APIs are not compatible for the same reason.
 303 .PP
 304 .nf
 305 .BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow );
 306 .fi
 307 .IP
 308 This routine can be invoked only on streams created by
 309 .BR xdrrec_create ().
 310 The data in the output buffer is marked as a completed record,
 311 and the output buffer is optionally written out if
 312 .I sendnow
 313 is nonzero.
 314 This routine returns one if it succeeds, zero otherwise.
 315 .PP
 316 .nf
 317 .BI "bool_t xdrrec_eof(XDR *" xdrs );
 318 .fi
 319 .IP
 320 This routine can be invoked only on streams created by
 321 .BR xdrrec_create ().
 322 After consuming the rest of the current record in the stream,
 323 this routine returns one if the stream has no more input,
 324 zero otherwise.
 325 .PP
 326 .nf
 327 .BI "bool_t xdrrec_skiprecord(XDR *" xdrs );
 328 .fi
 329 .IP
 330 This routine can be invoked only on
 331 streams created by
 332 .BR xdrrec_create ().
 333 It tells the XDR implementation that the rest of the current record
 334 in the stream's input buffer should be discarded.
 335 This routine returns one if it succeeds, zero otherwise.
 336 .PP
 337 .nf
 338 .BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size ,
 339 .BI "                     xdrproc_t " proc );
 340 .fi
 341 .IP
 342 A primitive that provides pointer chasing within structures.
 343 The argument
 344 .I pp
 345 is the address of the pointer;
 346 .I size
 347 is the
 348 .I sizeof
 349 the structure that
 350 .I *pp
 351 points to; and
 352 .I proc
 353 is an XDR procedure that filters the structure
 354 between its C form and its external representation.
 355 This routine returns one if it succeeds, zero otherwise.
 356 .IP
 357 Warning: this routine does not understand null pointers.
 358 Use
 359 .BR xdr_pointer ()
 360 instead.
 361 .PP
 362 .nf
 363 .BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos );
 364 .fi
 365 .IP
 366 A macro that invokes the set position routine associated with
 367 the XDR stream
 368 .IR xdrs .
 369 The argument
 370 .I pos
 371 is a position value obtained from
 372 .BR xdr_getpos ().
 373 This routine returns one if the XDR stream could be repositioned,
 374 and zero otherwise.
 375 .IP
 376 Warning: it is difficult to reposition some types of XDR
 377 streams, so this routine may fail with one
 378 type of stream and succeed with another.
 379 .PP
 380 .nf
 381 .BI "bool_t xdr_short(XDR *" xdrs ", short *" sp );
 382 .fi
 383 .IP
 384 A filter primitive that translates between C
 385 .I short
 386 integers and their external representations.
 387 This routine returns one if it succeeds, zero otherwise.
 388 .PP
 389 .nf
 390 .BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op );
 391 .fi
 392 .IP
 393 This routine initializes the XDR stream object pointed to by
 394 .IR xdrs .
 395 The XDR stream data is written to, or read from, the
 396 .I stdio
 397 stream
 398 .IR file .
 399 The argument
 400 .I op
 401 determines the direction of the XDR stream (either
 402 .BR XDR_ENCODE ,
 403 .BR XDR_DECODE ,
 404 or
 405 .BR XDR_FREE ).
 406 .IP
 407 Warning: the destroy routine associated with such XDR streams calls
 408 .BR fflush (3)
 409 on the
 410 .I file
 411 stream, but never
 412 .BR fclose (3).
 413 .PP
 414 .nf
 415 .BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize );
 416 .fi
 417 .IP
 418 A filter primitive that translates between C strings and
 419 their corresponding external representations.
 420 Strings cannot be longer than
 421 .IR maxsize .
 422 Note:
 423 .I sp
 424 is the address of the string's pointer.
 425 This routine returns one if it succeeds, zero otherwise.
 426 .PP
 427 .nf
 428 .BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp );
 429 .fi
 430 .IP
 431 A filter primitive that translates between
 432 .I unsigned
 433 C characters and their external representations.
 434 This routine returns one if it succeeds, zero otherwise.
 435 .PP
 436 .nf
 437 .BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned *" up );
 438 .fi
 439 .IP
 440 A filter primitive that translates between C
 441 .I unsigned
 442 integers and their external representations.
 443 This routine returns one if it succeeds, zero otherwise.
 444 .PP
 445 .nf
 446 .BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp );
 447 .fi
 448 .IP
 449 A filter primitive that translates between C
 450 .I "unsigned long"
 451 integers and their external representations.
 452 This routine returns one if it succeeds, zero otherwise.
 453 .PP
 454 .nf
 455 .BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp );
 456 .fi
 457 .IP
 458 A filter primitive that translates between C
 459 .I "unsigned short"
 460 integers and their external representations.
 461 This routine returns one if it succeeds, zero otherwise.
 462 .PP
 463 .nf
 464 .BI "bool_t xdr_union(XDR *" xdrs ", int *" dscmp ", char *" unp ,
 465 .BI "                 struct xdr_discrim *" choices ,
 466 .BI "                 xdrproc_t " defaultarm ");     /* may equal NULL */"
 467 .fi
 468 .IP
 469 A filter primitive that translates between a discriminated C
 470 .I union
 471 and its corresponding external representation.
 472 It first
 473 translates the discriminant of the union located at
 474 .IR dscmp .
 475 This discriminant is always an
 476 .IR enum_t .
 477 Next the union located at
 478 .I unp
 479 is translated.
 480 The argument
 481 .I choices
 482 is a pointer to an array of
 483 .BR xdr_discrim ()
 484 structures.
 485 Each structure contains an ordered pair of
 486 .RI [ value , proc ].
 487 If the union's discriminant is equal to the associated
 488 .IR value ,
 489 then the
 490 .I proc
 491 is called to translate the union.
 492 The end of the
 493 .BR xdr_discrim ()
 494 structure array is denoted by a routine of value NULL.
 495 If the discriminant is not found in the
 496 .I choices
 497 array, then the
 498 .I defaultarm
 499 procedure is called (if it is not NULL).
 500 Returns one if it succeeds, zero otherwise.
 501 .PP
 502 .nf
 503 .BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size ,
 504 .BI "                  unsigned int " elsize ", xdrproc_t " elproc );
 505 .fi
 506 .IP
 507 A filter primitive that translates between fixed-length arrays
 508 and their corresponding external representations.
 509 The argument
 510 .I arrp
 511 is the address of the pointer to the array, while
 512 .I size
 513 is the element count of the array.
 514 The argument
 515 .I elsize
 516 is the
 517 .I sizeof
 518 each of the array's elements, and
 519 .I elproc
 520 is an XDR filter that translates between
 521 the array elements' C form, and their external
 522 representation.
 523 This routine returns one if it succeeds, zero otherwise.
 524 .PP
 525 .nf
 526 .BI "bool_t xdr_void(void);"
 527 .fi
 528 .IP
 529 This routine always returns one.
 530 It may be passed to RPC routines that require a function argument,
 531 where nothing is to be done.
 532 .PP
 533 .nf
 534 .BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp );
 535 .fi
 536 .IP
 537 A primitive that calls
 538 .B "xdr_string(xdrs, sp,MAXUN.UNSIGNED );"
 539 where
 540 .B MAXUN.UNSIGNED
 541 is the maximum value of an unsigned integer.
 542 .BR xdr_wrapstring ()
 543 is handy because the RPC package passes a maximum of two XDR
 544 routines as arguments, and
 545 .BR xdr_string (),
 546 one of the most frequently used primitives, requires three.
 547 Returns one if it succeeds, zero otherwise.
 548 .SH ATTRIBUTES
 549 For an explanation of the terms used in this section, see
 550 .BR attributes (7).
 551 .TS
 552 allbox;
 553 lbw31 lb lb
 554 l l l.
 555 Interface       Attribute       Value
 556 T{
 557 .BR xdr_array (),
 558 .BR xdr_bool (),
 559 .br
 560 .BR xdr_bytes (),
 561 .BR xdr_char (),
 562 .br
 563 .BR xdr_destroy (),
 564 .BR xdr_double (),
 565 .br
 566 .BR xdr_enum (),
 567 .BR xdr_float (),
 568 .br
 569 .BR xdr_free (),
 570 .BR xdr_getpos (),
 571 .br
 572 .BR xdr_inline (),
 573 .BR xdr_int (),
 574 .br
 575 .BR xdr_long (),
 576 .BR xdrmem_create (),
 577 .br
 578 .BR xdr_opaque (),
 579 .BR xdr_pointer (),
 580 .br
 581 .BR xdrrec_create (),
 582 .BR xdrrec_eof (),
 583 .br
 584 .BR xdrrec_endofrecord (),
 585 .br
 586 .BR xdrrec_skiprecord (),
 587 .br
 588 .BR xdr_reference (),
 589 .BR xdr_setpos (),
 590 .br
 591 .BR xdr_short (),
 592 .BR xdrstdio_create (),
 593 .br
 594 .BR xdr_string (),
 595 .BR xdr_u_char (),
 596 .br
 597 .BR xdr_u_int (),
 598 .BR xdr_u_long (),
 599 .br
 600 .BR xdr_u_short (),
 601 .BR xdr_union (),
 602 .br
 603 .BR xdr_vector (),
 604 .BR xdr_void (),
 605 .br
 606 .BR xdr_wrapstring ()
 607 T}      Thread safety   MT-Safe
 608 .TE
 609 .sp 1
 610 .SH SEE ALSO
 611 .BR rpc (3)
 612 .PP
 613 The following manuals:
 614 .RS
 615 eXternal Data Representation Standard: Protocol Specification
 616 .br
 617 eXternal Data Representation: Sun Technical Notes
 618 .br
 619 .IR "XDR: External Data Representation Standard" ,
 620 RFC\ 1014, Sun Microsystems, Inc.,
 621 USC-ISI.
 622 .RE