# Compaq TCP/IP Services for OpenVMS
ONC RPC Programming

Previous | Contents | Index

# Chapter 8
XDR Routine Reference

This chapter describes the routines that specify external data representation. They allow C programmers to describe arbitrary data structures in a system-independent fashion. These routines transmit data for remote procedure calls.

Table 8-1 indicates the type of task that each routine performs.

Table 8-1 XDR Data Conversion Routines
Routine | Encodes and Decodes...
--- | ---
`xdr_accepted_reply` | Accepted RPC messages
`xdr_array` | Variable-length arrays
`xdr_authunix_parms` | UNIX-style authentication information
`xdr_bool` | Boolean values
`xdr_bytes` | Single bytes
`xdr_callhdr` | Static part of RPC request message headers
`xdr_callmsg` | RPC request messages
`xdr_char` | Single characters
`xdr_double` | Double-precision floating-point numbers
`xdr_enum` | Enumerations
`xdr_float` | Single-precision floating-point numbers
`xdr_hyper` | Quad words (hyperintegers)
`xdr_int` | 4-byte integers
`xdr_long` | Longwords
`xdr_opaque` | Fixed-length opaque data structures
`xdr_opaque_auth` | Opaque `opaque_auth` structures containing authentication information
`xdr_pmap` | Portmapper parameters
`xdr_pmap_vms` | Portmapper parameters (including OpenVMS process IDs)
`xdr_pmaplist` | Portmapper lists
`xdr_pmaplist_vms` | Portmapper lists (including OpenVMS process IDs)
`xdr_pointer` | Data structure pointers
`xdr_reference` | Data structure pointers
`xdr_rejected_reply` | Rejected RPC reply messages
`xdr_replymsg` | RPC reply messages
`xdr_short` | 2-byte integers
`xdr_string` | Null-terminated strings
`xdr_u_char` | Unsigned characters
`xdr_u_hyper` | Unsigned quadwords (hyperintegers)
`xdr_u_int` | Unsigned 4-byte integers
`xdr_u_long` | Unsigned long integers
`xdr_u_short` | Unsigned 2-byte integers
`xdr_union` | Unions
`xdr_vector` | Fixed-length arrays
`xdr_void` | (A dummy routine)
`xdr_wrapstring` | Null-terminated strings

This chapter also describes the XDR routines that manage XDR streams. They allow C programmers to handle XDR streams in a system-independent fashion.

Table 8-2 indicates the type of task that each routine performs.

Table 8-2 XDR Stream Handling Routines
Routine | Task
--- | ---
`xdr_free` | Deallocates an XDR data structure.
`xdrmem_create` | Creates an XDR stream handle describing a memory buffer.
`xdrrec_create` | Creates an XDR stream handle describing a record-oriented TCP-based connection.
`xdrrec_endofrecord` | Generates an end-of-record indication for an XDR record.
`xdrrec_eof` | Positions the data pointer to the end of the current XDR record and indicates whether any more records follow the current record.
`xdrrec_skiprecord` | Positions the data pointer at the end of the current XDR record.
`xdrstdio_create` | Creates an XDR stream handle describing a `stdio` stream.
`xdr_accepted_reply` | Accepts RPC messages.

# xdr_accepted_reply

> Serializes and deserializes a message-accepted indication in an RPC reply message.

## Format

> #include <tcpip$rpcxdr.h>

> bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply *arp);

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### arp

> A pointer to a buffer to which the message-accepted indication is written.

## Description

> Used for encoding reply messages. This routine encodes the status of the RPC call and, in the case of success, the call results as well. This routine is useful for users who want to generate messages without using the ONC RPC package. It returns the message-accepted variant of a reply message union in the `arp` argument.

> The `xdr_replymsg` routine calls this routine.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure to encode the message.

# xdr_array

> Serializes and deserializes the elements of a variable-length array.

## Format

> #include <tcpip$rpcxdr.h>

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

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### arrp

> A pointer to the pointer to the array.

> ### sizep

> A pointer to the number of elements in the array. This element count cannot exceed the `maxsize` parameter.

> ### maxsize

> The maximum size of the `sizep` parameter. This value is the maximum number of elements that the array can hold.

> ### elsize

> The size, in bytes, of each of the array's elements.

> ### elproc

> The XDR routine to call that handles each element of the array.

## Description

> A filter primitive that translates between variable-length arrays and their corresponding external representations.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

# xdr_authunix_parms

> Serializes and deserializes credentials in an authentication parameter structure.

## Format

> #include <tcpip$rpcxdr.h>

> bool_t xdr_authunix_parms (XDR *xdrs, struct authunix_parms *authp);

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### authp

> A pointer to an `authunix_parms` structure.

## Description

> Used for externally describing standard UNIX credentials. On a TCP/IP Services host, this routine encodes the host name, the user ID, and the group ID. It sets the group ID list to `NULL` . This routine is useful for users who want to generate these credentials without using the ONC RPC authentication package.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

# xdr_bool

> Serializes and deserializes boolean data.

## Format

> #include <tcpip$rpcxdr.h>

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

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### bp

> A pointer to the boolean data.

## Description

> A filter primitive that translates between booleans (integers) and their external representations. When encoding data, this filter produces values of either 1 or 0.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

# xdr_bytes

> Serializes and deserializes a counted byte array.

## Format

> #include <tcpip$rpcxdr.h>

> bool_t xdr_bytes (XDR *xdrs, char **bpp, u_int *sizep, u_int maxsize);

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### bpp

> A pointer to a pointer to the byte array.

> ### sizep

> A pointer to the length of the byte array.

> ### maxsize

> The maximum size of the length of the byte array.

## Description

> A filter primitive that translates between a variable-length byte array and its external representation. The length of the array is located at `sizep` ; the array cannot be longer than `maxsize` . If `*bpp` is `NULL` , `xdr_bytes` allocates `maxsize` bytes.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

# xdr_callhdr

> Serializes and deserializes the static part of a call message header.

## Format

> #include <tcpip$rpcxdr.h>

> bool_t xdr_callhdr(XDR *xdrs, struct rpc_msg *chdrp);

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### chdrp

> A pointer to the call header data.

## Description

> Describes call header messages. This routine is useful for users who want to generate messages without using the ONC RPC package. The `xdr_callhdr` routine encodes the following fields: transaction ID, direction, RPC version, server program number, and server version.

## Return Values

> TRUE | Indicate success.
> FALSE | Indicates failure.

# xdr_callmsg

> Serializes and deserializes an ONC RPC call message.

## Format

> #include <tcpip$rpcxdr.h>

> bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsgp);

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### cmsgp

> A pointer to an `rpc_msg` structure that describes the RPC call message.

## Description

> This routine is useful for users who want to generate messages without using the ONC RPC package. The `xdr_callmsg` routine encodes the following fields: transaction ID, direction, RPC version, server program number, server version number, server procedure number, and client authentication.

> The `pmap_rmtcall` and `svc_sendreply` routines call `xdr_callmsg` .

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

# xdr_char

> Serializes and deserializes character data.

## Format

> #include <tcpip$rpcxdr.h>

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

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### cp

> A pointer to a character.

## Description

> A filter primitive that translates between internal representations of characters and their XDR representations.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

# xdr_double

> Serializes and deserializes VAX and IEEE double-precision floating-point numbers.

## Format

> #include <tcpip$rpcxdr.h>

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

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### dp

> A pointer to the double-precision floating-point number.

## Description

> A filter primitive that translates between double-precision numbers and their external representations.

> This routine is 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.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

# xdr_enum

> Serializes and deserializes enumerations.

## Format

> #include <tcpip$rpcxdr.h>

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

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### ep

> A pointer to the enumeration data.

## Description

> A filter primitive that translates between enumerations (actually integers) and their external representations.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

# xdr_float

> Serializes and deserializes VAX and IEEE single-precision floating-point numbers.

## Format

> #include <tcpip$rpcxdr.h>

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

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### fp

> A pointer to a single-precision floating-point number.

## Description

> A filter primitive that translates between single-precision floating-point numbers and their external representations.

> This routine is 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.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

# xdr_free

> Deallocates the memory associated with the indicated data structure.

## Format

> #include <tcpip$rpcxdr.h>

> bool_t xdr_free(xdrproc_t proc, char *objp);

## Arguments

> ### proc

> The XDR routine for the data structure being freed.

> ### objp

> A pointer to the data structure to be freed.

## Description

> Releases memory allocated for the data structure to which `objp` points. The pointer passed to this routine is not freed, but what it points to is freed (recursively). Use this routine to free decoded data that is no longer needed. Never use this routine for encoded data.

## Return Values

> TRUE | Indicate success.
> FALSE | Indicates failure.

# xdr_hyper

> Serializes and deserializes VAX quadwords (known in XDR as hyperintegers).

## Format

> #include <tcpip$rpcxdr.h>

> bool_t xdr_hyper(XDR *xdrs, quad *hp);

## Arguments

> ### xdrs

> A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines.

> ### hp

> A pointer to the hyperinteger data.

## Description

> A filter primitive that translates between hyperintegers and their external representations.

## Return Values

> TRUE | Indicates success.
> FALSE | Indicates failure.

Previous | Next | Contents | Index