# Digital TCP/IP Services for OpenVMS
ONC RPC Programming

Previous | Contents

The svc_register routine calls this routine; therefore, you are unlikely to use this routine directly.

## Return Values

> None |

# xprt_unregister

> Removes a socket associated with an RPC server handle from the list of registered sockets.

## Format

> ### #include <rpc/rpc.h>

> ### void xprt_unregister(SVCXPRT *xprt);

## ARGUMENTS

> ### xprt

> A pointer to an RPC server handle created by any of the server handle creation routines.

## DESCRIPTION

> Removes the socket associated with the indicated handle from the list of registered sockets maintained in the svc_fdset variable. Activity on the socket associated with xprt will no longer be checked by the svc_run routine.

> The svc_unregister routine calls this routine; therefore, you are unlikely to use this routine directly.

## Return Values

> None |

# _authenticate

> Authenticates the request message.

## Format

> ### #include <rpc/rpc.h>

> ### enum auth_stat _authenticate(struct svc_req *rqst, struct rpc_msg *msg);

## ARGUMENTS

> ### rqst

> A pointer to an svc_req structure with the requested program number, procedure number, version number, and credentials passed by the client.

> ### msg

> A pointer to an rpc_msg structure with members that make up the RPC message.

## DESCRIPTION

> Returns AUTH_OK if the message is authenticated successfully. If it returns AUTH_OK, the routine also does the following:
> - Sets rqst->rq_xprt->verf to the appropriate response verifier.
> - Sets rqst->rq_client_cred to the "cooked" form of the credentials.

> The expression rqst->rq_xprt->verf must be preallocated, and its length set appropriately.

> The program still owns and is responsible for msg->u.cmb.cred and msg->u.cmb.verf. The authentication system retains ownership of rqst->rq_client_cred, the "cooked" credentials.

## Return Values

> enum auth_stat | The return status code for the authentication checks: AUTH_OK=0---Authentication checks successful. AUTH_BADCRED=1---Invalid credentials (seal broken) AUTH_REJECTEDCRED=2---Client should begin new session AUTH_BADVERF=3---Invalid verifier (seal broken) AUTH_REJECTEDVERF=4---Verifier expired or was replayed AUTH_TOOWEAK=5---Rejected due to security reasons AUTH_INVALIDRESP=6---Invalid response verifier AUTH_FAILED=7---some unknown reason

# 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 four-byte integers
xdr_u_long | Unsigned long integers
xdr_u_short | Unsigned two-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 if 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 | Accepted RPC messages

# xdr_accepted_reply

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

## Format

> ### #include <ucx$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 wish 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 <ucx$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 <ucx$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 UCX 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 <ucx$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 one or zero.

## Return Values

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

# xdr_bytes

> Serializes and deserializes a counted byte array.

## Format

> ### #include <ucx$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 <ucx$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 <ucx$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 <ucx$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 <ucx$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 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.

## Return Values

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

# xdr_enum

> Serializes and deserializes enumerations.

## Format

> ### #include <ucx$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 <ucx$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 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.

## Return Values

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

# xdr_free

> Deallocates the memory associated with the indicated data structure.

## Format

> ### #include <ucx$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 hyper-integers).

## Format

> ### #include <ucx$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 hyper-integer data.

## DESCRIPTION

> A filter primitive that translates between hyper-integers and their external representations.

## Return Values

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

# xdr_int

> Serializes and deserializes integers.

## Format

> ### #include <ucx$rpcxdr.h>

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

## ARGUMENTS

> ### xdrs

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

> ### ip

> A pointer to the integer data.

## DESCRIPTION

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

## Return Values

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

# xdr_long

> Serializes and deserializes long integers.

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_long(XDR *xdrs, long *lp);

## ARGUMENTS

> ### xdrs

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

> ### lp

> A pointer to a long integer.

## DESCRIPTION

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

## Return Values

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

# xdr_opaque

> Serializes and deserializes opaque structures.

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_opaque(XDR *xdrs, char *op, u_int cnt);

## ARGUMENTS

> ### xdrs

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

> ### op

> A pointer to the opaque data.

> ### cnt

> The size of op in bytes.

## DESCRIPTION

> A filter primitive that translates between fixed-size opaque data and its external representation. This routine treats the data as a fixed length of bytes and does not attempt to convert the bytes.

## Return Values

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

# xdr_opaque_auth

> Serializes and deserializes ONC RPC authentication information message.

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *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 opaque_auth structure describing authentication information. The pointer should reference data created by the authnone_create, authunix_create, or authunix_create_default routine.

## DESCRIPTION

> Translates ONC RPC authentication information messages. This routine is useful for users who want to generate messages without using the ONC RPC package.

## Return Values

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

# xdr_pmap

> Serializes and deserializes Portmapper parameters.

## Format

> ### #include <ucx$rpcxdr.h>

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

## ARGUMENTS

> ### xdrs

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

> ### regs

> A pointer to the pmap structure. This structure contains the program number, version number, protocol number, and port number.

## DESCRIPTION

> Describes parameters to various Portmapper procedures, externally. This routine is useful for users who want to generate these parameters without using the Portmapper interface.

## Return Values

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

# xdr_pmap_vms

> Serializes and deserializes OpenVMS-specific Portmapper parameters.

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_pmap_vms(XDR *xdrs, struct pmap_vms *regs);

## ARGUMENTS

> ### xdrs

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

> ### regs

> A pointer to the pmap_vms structure. This structure contains the program number, version number, protocol number, port number and the OpenVMS-specific process identification.

## DESCRIPTION

> This routine is similar to xdr_pmap(), except it also includes the process identification in the pmap_vms structure.

## Return Values

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

# xdr_pmaplist

> Serializes and deserializes a list of Portmapper port mappings.

## Format

> ### #include <ucx$rpcxdr.h>

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

## ARGUMENTS

> ### xdrs

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

> ### rpp

> A pointer to a pointer to a pmaplist structure containing a list of Portmapper programs and their respective information. If the routine is used to decode a Portmapper listing, it sets rpp to the address of a newly-allocated linked list of pmaplist structures.

## DESCRIPTION

> Describes a list of port mappings, externally. This routine is useful for users who want to generate these parameters without using the Portmapper interface.

## Return Values

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

# xdr_pmaplist_vms

> Serializes and deserializes a list of Portmapper port mappings for OpenVMS systems.

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_pmaplist_vms (XDR *xdrs, struct pmaplist_vms **rpp);

## ARGUMENTS

> ### xdrs

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

> ### rpp

> A pointer to a pointer to a pmaplist_vms structure containing a list of Portmapper programs and their respective information, including OpenVMS-specific information.

## DESCRIPTION

> This routine is similar to the xdr_pmaplist routine, except it also includes the process identification in the pmaplist_vms structure.

## Return Values

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

# xdr_pointer

> Serializes and deserializes indirect pointers and the data being pointed to.

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_pointer(XDR *xdrs, char **objpp, u_int objsize, xdrproc_t objproc);

## ARGUMENTS

> ### xdrs

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

> ### objpp

> A pointer to a pointer to the data being converted.

> ### objsize

> The size of the data structure in bytes.

> ### objproc

> The XDR procedure that filters the structure between its local form and its external representation.

## DESCRIPTION

> An XDR routine for translating data structures that contain pointers to other structures, such as a linked list. The xdr_pointer routine is similar to the xdr_reference routine. The differences are that the xdr_pointer routine handles pointers with the value NULL and that it translates the pointer values to a boolean. If the boolean is TRUE, the data follows the boolean.

## Return Values

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

# xdr_reference

> Serializes and deserializes indirect pointers and the data being pointed to.

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_reference(XDR *xdrs, char **objpp, u_int objsize, xdrproc_t objproc);

## ARGUMENTS

> ### xdrs

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

> ### objpp

> A pointer to a pointer to the 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 during encoding.

> ### objsize

> The size of the structure in bytes.

> ### objproc

> The XDR procedure that filters the structure between its local form and its external representation.

## DESCRIPTION

> A primitive that provides pointer chasing within structures.

## Return Values

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

# xdr_rejected_reply

> Serializes and deserializes the remainder of an RPC reply message after the header indicates that the reply is rejected.

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rrp);

## ARGUMENTS

> ### xdrs

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

> ### rrp

> A pointer to the rejected_reply structure describing the rejected-reply message.

## DESCRIPTION

> Describes ONC RPC reply messages. This routine is useful for users who want to generate messages without using the ONC RPC package.

## Return Values

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

# xdr_replymsg

> Serializes and deserializes the RPC reply header and then calls the appropriate routine to interpret the rest of the message.

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsgp);

## ARGUMENTS

> ### xdrs

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

> ### rmsgp

> A pointer to the rpc_msg structure describing the reply message.

## DESCRIPTION

> Describes ONC RPC reply messages. This routine is useful for users who want to generate messages without using the ONC RPC package. This routine interprets the message header and then calls either the xdr_accepted_reply or the xdr_rejected_reply routine to interpret the body of the RPC message.

## Return Values

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

# xdr_short

> Serializes and deserializes short integers.

## Format

> ### #include <ucx$rpcxdr.h>

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

## ARGUMENTS

> ### xdrs

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

> ### sp

> A pointer to a short integer.

## DESCRIPTION

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

## Return Values

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

# xdr_string

> Serializes and deserializes strings (arrays of bytes terminated by a NULL character).

## Format

> ### #include <ucx$rpcxdr.h>

> ### bool_t xdr_string(XDR *xdrs, char **spp, u_int maxsize);

## ARGUMENTS

> ### xdrs

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

> ### spp

> A pointer to a pointer to a character string.

> ### maxsize

> The maximum size of the string.

## DESCRIPTION

> A filter primitive that translates between strings and their corresponding external representations. Strings cannot be longer than the value specified with the maxsize parameter.

> Previous | Next | Contents