18. ONC RPC RTL XDR Routines

Introduction

This chapter is for RPC programmers. It documents the XDR routines in the ONC RPC Run-Time Library (RTL). These routines are the programming interface to ONC RPC.

 

XDR Routines

This section explains what XDR routines do and when you would call them. It also provides quick reference and detailed reference sections describing each XDR routine.

 

What XDR Routines Do

Most XDR routines share these characteristics:

·         They convert data in two directions: from the host's local data format to XDR format (called encoding or marshalling), or the other way around (called decoding or unmarshalling).

·         They use xdrs, a structure containing instructions for encoding, decoding, and deallocating memory.

·         They return a Boolean value to indicate success or failure.

Some XDR routines allocate memory while decoding an argument. To free this memory, call the xdr_free() routine after the program is done with the decoded value.

The below table shows the order in which XDR routines perform encoding and decoding.

Client

Server

1. Encodes arguments

2. Decodes results

3. Frees results from memory

1. Decodes arguments

2. Encodes results

3. Frees arguments from memory

 

When to Call XDR Routines

Under most circumstances, you are not likely to call any XDR routines directly. The clnt_call and svc_sendreply routines call the XDR routines.

You would call the XDR routines directly only when you write your own routines to convert data to or from XDR format.

 

Quick Reference

The below table lists the XDR routines that encode and decode data.

This routine...

Encodes and decodes...

xdr_array

Variable-length array

xdr_bool

Boolean value

xdr_bytes

Bytes

xdr_char

Character

xdr_double

Double-precision floating point number

xdr_enum

Enumerated type

xdr_float

Floating point value

xdr_hyper

VAX quad word to an XDR hyper-integer, or the other way

xdr_int

Four-byte integer

xdr_long

Longword

xdr_opaque

Contents of a buffer (treats the data as a fixed length of bytes and does not attempt to interpret them)

xdr_pointer

Pointer to a data structure

xdr_reference

Pointer to a data structure (the address must be non-zero)

xdr_short

Two-byte unsigned integer

xdr_string

Null-terminated string

xdr_u_char

Unsigned character

xdr_u_hyper

VAX quad word to an XDR unsigned hyper-integer

xdr_u_int

Four-byte unsigned integer

xdr_u_long

Unsigned longword

xdr_u_short

Two-byte unsigned integer

xdr_union

Union

xdr_vector

Vector (fixed length array)

xdr_void

Nothing

xdr_wrapstring

Null-terminated string

 

The below table lists the XDR routines that perform various support functions.

This routine...

Does this...

xdr_free

Deallocates a data structure from memory

xdrmem_create

Creates a memory buffer XDR stream

xdrrec_create

Creates a record-oriented XDR stream

xdrrec_endofrecord

Marks the end of a record

xdrrec_eof

Goes to the end of the current record, then verifies whether any more data can be read

xdrrec_skiprecord

Goes to the end of the current record

xdrstdio_create

Initializes a stdio stream

 

The below table lists the upper layer XDR routines that support RPC.

This routine...

Encodes and decodes...

xdr_accepted_reply

Part of an RPC reply message after the reply is accepted

xdr_authunix_parms

UNIX-style authentication information

xdr_callhdr

Static part of an RPC request message header (encoding only)

xdr_callmsg

RPC request message

xdr_netobj

Data in the netobj structure

xdr_opaque_auth

Authentication information

xdr_pmap

Port Mapper parameters

xdr_pmaplist

List of Port Mapping data

xdr_rejected_reply

Part of an RPC reply message after the reply is rejected

xdr_replymsg

RPC reply header; it then calls the appropriate routine to convert the rest of the message

 

Routine Descriptions

The following sections describe each XDR routine in detail.

 

 

 

 


 

xdr_accepted_reply

Converts an RPC reply message from local format to XDR format, or the other way around.

 

Format

bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply *ar);

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

ar

Address of the structure containing the RPC reply message.

 

Description

The xdr_replymsg routine calls the xdr_accepted_reply routine.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_array

Converts a variable-length array from local format to XDR format, or the other way around.

 

Format

bool_t xdr_array(XDR *xdrs, u_char **addrp, u_long *sizep, u_long maxsize, u_long elsize, xdrproc_t elproc);

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

addrp

Address of the address containing the array being converted. If addrp is zero, then xdr_array allocates ((*sizep)*elsize) number of bytes when it decodes.

 

sizep

Address of the number of elements in the array.

 

maxsize

Maximum number of elements the array can hold.

 

elsize

Size of each element, in bytes.

 

elproc

XDR routine that handles each array element.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_authunix_parms

Converts UNIX-style authentication information from local format to XDR format, or the other way around.

 

Format

bool_t xdr_authunix_parms(XDR *xdrs, struct authunix_parms *aupp);

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

aupp

UNIX-style authentication information being converted.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_bool

Converts a boolean value from local format to XDR format, or the other way around.

 

Format

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

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

bp

Address of the boolean value.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_bytes

Converts bytes from local format to XDR format, or the other way around.

 

Format

bool_t xdr_bytes(XDR *xdrs, u_char **cpp, u_long *sizep, u_long maxsize);

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

cpp

Address of the address of the buffer containing the bytes being converted. If *cpp is zero, xdr_bytes allocates maxsize bytes when it decodes.

 

sizep

Address of the actual number of bytes being converted.

 

maxsize

Maximum number of bytes that can be used. The server protocol determines this number.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_callhdr

Encodes the static part of an RPC request message header.

 

Format

bool_t xdr_callhdr(XDR *xdrs, struct rpc_msg *chdr);

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

chdr

Address of the data being converted.

 

Description

The xdr_callhdr routine converts the following fields: transaction ID, direction, RPC version, server program number, and server version. It converts the last four fields once, when the client handle is created.

The clnttcp_create and clntudp_create routines call the xdr_callhdr routine.

 

Diagnostics

This routine always returns TRUE.

 

 

 

 


 

xdr_callmsg

Converts an RPC request message from local format to XDR format, or the other way around.

 

Format

bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsg);

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

cmsg

Address of the message being converted.

 

Description

The xdr_callmsg routine converts the following fields: transaction ID, RPC direction, RPC version, program number, version number, procedure number, client authentication.

The pmap_rmtcall, svc_sendreply, and svc_sendreply_dq routines call xdr_callmsg.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_char

Converts a character from local format to XDR format, or the other way around.

 

Format

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

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

cp

Address of the character being converted.

 

Description

This routine provides the same functionality as the xdr_u_char routine.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_double

Converts a double-precision floating point number between local and XDR format.

 

Format

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

 

Arguments

 

xdrs

Pointer to an XDR stream handle created by one of the XDR stream handle creation routines.

 

dp

Pointer to the double-precision floating point number.

 

Description

This routine provides a filter primitive that translates between double-precision numbers and their external representations. It is actually implemented by four XDR routines:

xdr_double_D

Converts VAX D format floating point numbers

xdr_double_G

Converts VAX G format floating point numbers

xdr_double_T

Converts IEEE T format floating point numbers

xdr_double_X

Converts IEEE X format floating point numbers

 

You can reference these routines explicitly or you can use compiler settings to control which routine is used when you reference the xdr_double routine.

VAX

 If you use...

link your program with...

VAX C D_float RTL

TCPWARE_RPCLIB_SHR.EXE

VAX C G_float RTL

TCPWARE_RPCLIBG_SHR.EXE

 

ALPHA and I64

If you use...

link your program with...

DEC C D_float RTL

TCPWARE_RPCLIBD_SHR.EXE

DEC C G_float RTL

TCPWARE_RPCLIB_SHR.EXE

DEC C T_float RTL

TCPWARE_RPCLIBT_SHR.EXE

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_enum

Converts an enumerated type from local format to XDR format, or the other way around.

 

Format

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

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

ep

Address containing the enumerated type.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_float

Converts a floating point value from local format to XDR format, or the other way around.

 

Format

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

 

Arguments

 

xdrs

Pointer to an XDR stream handle created by one of the XDR stream handle creation routines.

 

fp

Pointer to a single-precision floating point number.

 

Description

This routine provides a filter primitive that translates between double-precision numbers and their external representations. It is actually implemented by two XDR routines:

xdr_float_F

Converts VAX F format floating point numbers

xdr_float_S

Converts IEEE T format floating point numbers

 

You can reference these routines explicitly or you can use compiler settings to control which routine is used when you reference the xdr_float routine.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_free

Deallocates a data structure from memory.

 

Format

void xdr_free(xdrproc_t proc, u_char *objp);

 

Arguments

 

proc

XDR routine that describes the data structure.

 

objp

Address of the data structure.

 

Description

Call this routine after decoded data is no longer needed. Do not call it for encoded data.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_hyper

Converts a VAX quad word to an XDR hyper-integer, or the other way around.

 

Format

bool_t xdr_hyper(XDR *xdrs, quad *ptr);

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

ptr

Address of the structure containing the quad word. The quad word is stored in standard VAX quad word format, with the low-order longword first in memory.

 

Description

This routine provided the same functionality as the xdr_u_hyper() routine.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_int

Converts one four-byte integer from local format to XDR format, or the other way around.

 

Format

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

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

ip

Address containing the integer.

 

Description

This routine provides the same functionality as the xdr_u_int, xdr_long, and xdr_u_long routines.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_long

Converts one longword from local format to XDR format, or the other way around.

 

Format

bool_t xdr_long(XDR *xdrs, u_long *lp);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

lp

Address containing the longword.

 

Description

This routine provides the same functionality as the xdr_u_long, xdr_int, and xdr_u_int routines.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_netobj

Converts data in the netobj structure from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_netobj(XDR *xdrs, netobj *ptr);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

ptr

Address of the following structure:

typedef struct
{
   u_long n_len;
   byte *n_bytes;
} netobj;

This structure defines the data being converted.

 

Description

The netobj structure is an aggregate data structure that is opaque and contains a counted array of 1024 bytes.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_opaque

Converts the contents of a buffer from the local data format to XDR format, or the other way around. This routine treats the data as a fixed length of bytes and does not attempt to interpret them.

 

Format

bool_t xdr_opaque(XDR *xdrs, char *cp, u_long cnt);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

cp

Address of the buffer containing opaque data.

 

cnt

Byte length.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_opaque_auth

Converts authentication information from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *ap);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

ap

Address of the authentication information. This data was created by the authnone_create, authunix_create, or authunix_create_default routine.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_pmap

Converts Port Mapper parameters from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_pmap(XDR *xdrs, struct pmap *regs);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

regs

Address of a structure containing the program number, version number, protocol number, and port number. This is the data being converted.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_pmaplist

Converts a list of Port Mapping data from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rpp);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

rpp

Address of the address of the structure containing Port Mapper data. If this routine is used to decode a Port Mapper listing, rpp is set to the address of the newly allocated linked list of structures.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_pointer

Converts a recursive data structure from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_pointer(XDR *xdrs, u_char **objpp, u_long obj_size,
xdrproc_t xdr_obj);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

objpp

Address of the address containing the data being converted. May be zero.

 

obj_size

Size of the data structure in bytes.

 

xdr_obj

XDR routine that describes the object being pointed to. This routine can describe complex data structures, and these structures may contain pointers.

 

Description

An XDR routine for a data structure that contains pointers to other structures, such as a linked list, would call the xdr_pointer routine. The xdr_pointer routine encodes a pointer from an address into a Boolean. If the Boolean is TRUE, the data follows the Boolean.

 

Example

bool_t xdr_pointer(XDR *xdrs, char **objpp, longw obj_size, xdrproc_t xdr_obj)
{
  bool_t  more_data;

  /*
   * determine if the pointer is a valid address (0 is invalid)
   */
  if ( *objpp != NULL)
    more_data = TRUE;
  else
    more_data = FALSE;


  /*
   * XDR the flag

   * If we are decoding, then more_data is overwritten.
   */
  if (!xdr_bool(xdrs, &more_data))
    return(FALSE);


  /*
   * If there is no more data, set the pointer to 0 (No effect if we
   * were encoding) and return TRUE
   */
  if (!more_data)
  {
    *objpp = NULL;
    return( TRUE);
  }


  /*
   * Otherwise, call xdr_reference.  The result is that xdr_pointer is
   * the same as xdr_reference, except that xdr_pointer adds a Boolean
   * to the encoded data and will properly handle NULL pointers.
   */
  return(xdr_reference(xdrs, objpp, obj_size, xdr_obj));


} /* end function xdr_pointer() */

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_reference

This routine recursively converts a structure that is referenced by a pointer inside the structure.

 

Format

bool_t xdr_reference(XDR *xdrs, u_char **objpp, u_long obj_size, xdrproc_t xdr_obj);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

objpp

Address of the address of a structure containing the data being converted. If objpp is zero, the xdr_reference routine allocates the necessary storage when decoding. This argument must be non-zero when encoding.

When xdr_reference encodes data, it passes *objpp to xdr_obj. When decoding, xdr_reference allocates memory if *objpp equals zero.

 

obj_size

Size of the referenced structure.

 

xdr_obj

XDR routine that describes the object being pointed to. This routine can describe complex data structures, and these structures may contain pointers.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_rejected_reply

Converts the remainder of an RPC reply message after the header indicates that the reply is rejected.

 

Format

bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rr);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

rr

Address of the structure containing the reply message.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_replymsg

Converts the RPC reply header, then calls the appropriate routine to convert the rest of the message.

 

Format

bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsg);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

rmsg

Address of the structure containing the reply message.

 

Description

The xdr_replymsg routine calls the xdr_rejected_reply or xdr_accepted_reply routine to convert the body of the RPC reply message from the local data format to XDR format, or the other way around.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 


 

xdr_short

Converts a two-byte integer from the local data format to XDR format, or the other way around.

 

Format

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

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

sp

Address of the integer being converted.

 

Description

This routine provides the same functionality as xdr_u_short.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_string

Converts a null-terminated string from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_string(XDR *xdrs, char **cpp, u_long maxsize);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

cpp

Address of the address of the first byte in the string.

 

maxsize

Maximum length of the string. The service protocol determines this value.

 

Description

The xdr_string routine is the same as the xdr_wrapstring routine, except xdr_string allows you to specify the maxsize.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_u_char

Converts an unsigned character from local format to XDR format, or the other way around.

 

Format

bool_t xdr_u_char(XDR *xdrs, u_char bp);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

bp

Address of the character being converted.

 

Description

This routine provides the same functionality as xdr_char.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_u_hyper

Converts an VAX quad word to an XDR unsigned hyper-integer, or the other way around.

 

Format

bool_t xdr_u_hyper(XDR *xdrs, quad *ptr);

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

ptr

Address of the structure containing the quad word. The quad word is stored in standard VAX format, with the low-order longword first in memory.

 

Description

This routine provides the same functionality as the xdr_hyper routine.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_u_int

Converts a four-byte unsigned integer from local format to XDR format, or the other way around.

 

Format

bool_t xdr_u_int(XDR *xdrs, int *ip);

 

Arguments

 

xdrs

Address of a structure containing XDR encoding and decoding information.

 

ip

Address of the integer.

 

Description

This routine provides the same functionality as xdr_int, xdr_long, and xdr_u_long.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_u_long

Converts an unsigned longword from local format to XDR format, or the other way around.

 

Format

bool_t xdr_u_long(XDR *xdrs, u_long *lp);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

lp

Address of the longword.

 

Description

This routine provides the same functionality as xdr_long, xdr_int, and xdr_u_int.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_u_short

Converts a two-byte unsigned integer from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_u_short(XDR *xdrs, u_short *sp);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

sp

Address of the integer being converted.

 

Description

This routine provides the same functionality as xdr_short.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_union

Converts a union from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_union(XDR *xdrs, enum_t *dscmp, u_char *unp, xdr_discrim *choices, xdrproc_t dfault);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

dscmp

Integer from the choices array.

 

unp

Address of the union.

 

choices

Address of an array. This array maps integers to XDR routines.

 

dfault

XDR routine that is called if the dscmp integer is not in the choices array.

 

Description

The xdr_union routine searches the array choices for the value of dscmp. If it finds the value, it calls the corresponding XDR routine to process the remaining data. If xdr_union doesn't find the value, it calls the dfault routine.

 

Example

The TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC]GETSYI_XDR_2.C file contains a sample routine that calls xdr_union.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_vector

Converts a vector (fixed length array) from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_vector(XDR *xdrs, u_char *basep, u_long nelem, u_long elmsize, xdrproc_t xdr_elem);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

basep

Address of the array.

 

nelem

Number of elements in the array.

 

elmsize

Size of each element.

 

xdr_elem

Converts each element from the local data format to XDR format, or the other way around.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdr_void

Converts nothing.

 

Format

bool_t xdr_void(XDR *xdrs, u_char *ptr);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

ptr

Ignored.

 

Description

Use this routine as a place-holder for a program that passes no data. The server and client expect an XDR routine to be called, even when there is no data to pass.

 

Diagnostics

This routine always returns TRUE.

 

 

 

 


 

xdr_wrapstring

Converts a null-terminated string from the local data format to XDR format, or the other way around.

 

Format

bool_t xdr_wrapstring(XDR *xdrs, char **cpp);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

cpp

Address of the address of the first byte in the string.

 

Description

The xdr_wrapstring routine calls the xdr_string routine. The xdr_wrapstring routine hides the maxsize argument from the programmer. Instead, the maximum size of the string is assumed to be 232 - 1.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdrmem_create

Creates a memory buffer XDR stream.

 

Format

void xdrmem_create(XDR *xdrs, u_char *addr, u_long size, enum xdr_op op);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

addr

Address of the buffer containing the encoded data.

 

size

Size of the addr buffer.

 

op

Operations you will perform on the buffer. Valid values are XDR_ENCODE, XDR_DECODE, and XDR_FREE. You may change this value.

 

Description

The xdrmem_create routine initializes a structure so that other XDR routines can write to a buffer. The UDP and UDPA transports use this routine.

 

 

 

 


 

xdrrec_create

Creates a record-oriented XDR stream.

 

Format

void xdrrec_create(XDR *xdrs, u_long sendsize, u_long recvsize,
u_char *tcp_handle, int (*readit)(), int (*writeit)();

 

Arguments

 

xdrs

Address of the structure being created. The xdrrec_create routine will write XDR encoding and decoding information to this structure.

 

sendsize

Size of the send buffer in bytes. The minimum size is 100 bytes. If you specify fewer than 100 bytes, 4000 bytes is used as the default.

 

recvsize

Size of the receive buffer in bytes. The minimum size is 100 bytes. If you specify fewer than 100 bytes, 4000 bytes is used as the default.

 

tcp_handle

Address of the client or server handle.

 

readit

Address of a user-written routine that reads data from the stream transport. This routine must use the following format:

int readit(u_char *tcp_handle, u_char *buffer, u_long len)

tcp_handle  is the client or server handle, *buffer is the buffer to fill, and len is the number of bytes to read. The readit routine returns either the number of bytes read, or -1 if an error occurs.

 

writeit

Address of a user-written routine that writes data to the stream transport. This routine must use the following format:

int writeit(u_char *tcp_handle, u_char *buffer, u_long len)

·         tcp_handle is the client or server handle.

·         buffer is the address of the buffer being written.

·         len is the number of bytes to write.

The writeit routine returns either the number of bytes written, or -1 if an error occurs.

 

Description

The xdrrec_create routine requires one of the following:

·         The TCP transport

·         A stream-oriented interface (such as file I/O) not supported by TCPware. The stream consists of data organized into records. Each record is either an RPC request or reply.

The clnttcp_create and svcfd_create routines call the xdrrec_create routine.

 

 

 

 


 

xdrrec_endofrecord

Marks the end of a record.

 

Format

bool_t xdrrec_endofrecord(XDR *xdrs, bool_t sendnow);

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

sendnow

Indicates when the calling program will send the record to the writeit routine.

If sendnow is TRUE, xdrrec_endofrecord sends the record now. If sendnow is FALSE, xdrrec_endofrecord writes the record to a buffer and sends the buffer when it runs out of buffer space.

 

Description

A client or server program calls the xdrrec_endofrecord routine when it reaches the end of a record it is writing. The program must call the xdrrec_create routine before calling xdrrec_endofrecord.

 

Diagnostics

This routine returns TRUE if it succeeds and FALSE if it fails.

 

 

 

 


 

xdrrec_eof

Goes to the end of the current record, then verifies whether any more data can be read.

 

Format

bool_t xdrrec_eof(XDR *xdrs);

 

Argument

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

Description

The client or server program must call the xdrrec_create routine before calling xdrrec_eof.

 

Diagnostics

This routine returns TRUE if it reaches the end of the data stream, and FALSE if it finds more data to read.

 

 

 

 


 

xdrrec_skiprecord

Goes to the end of the current record.

 

Format

bool_t xdrrec_skiprecord(XDR *xdrs);

 

Argument

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

Description

A client or server program calls the xdrrec_skiprecord routine before it reads data from a stream. This routine ensures that the program starts reading a record from the beginning.

The xdrrec_skiprecord routine is similar to the xdrrec_eof routine, except that xdrrec_skiprecord does not verify whether any more data can be read.

The client or server program must call the xdrrec_create routine before calling xdrrec_skiprecord.

 

Diagnostics

This routine returns TRUE if it has skipped to the start of a record. Otherwise, it returns FALSE.

 

 

 

 


 

xdrstdio_create

Initializes a stdio XDR stream.

 

Format

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

 

Arguments

 

xdrs

Address of the structure containing XDR encoding and decoding information.

 

file

File pointer FILE *, which is to be associated with the stream.

 

op

An XDR operation, one of: XDR_ENCODE, XDR_DECODE, or XDR_FREE.

 

Description

The xdrstdio_create routine initializes a stdio stream for the specified file.