NOTES ON XDR XDR is the external data representation library. The XDR routines allow programmers to describe arbitrary data structures in a machine-independent way. Data for remote procedure calls are transmitted using these routines. XDR routines are especially useful for remote procedure calls (RPC). In a remote procedure call, two programs, which may be running on different computers, need to pass data. The first program takes its data, which is in a local data format, and passes it through an XDR routine so that it is in XDR format. Then RPC routines transmit the data. The second program receives the data from an RPC routine, and calls an XDR routine to convert the data from XDR format to its local data format. ----------- XDR on UNIX ----------- XDR is a built in library on the SGI systems. To use the XDR library, in particular, to use the XDR data type, you must include the appropriate file in your C programs: #include If your C program calls XDR routines, they are loaded automatically. You can get information about XDR by typing man xdr The man pages on POWER1 are stored in /usr/share/catman/p_man/cat3n ---------- XDR on VMS ---------- There is a TCPWARE: logical device (at least on TECH88). To use the XDR library, in particular, to use the XDR data type, you must include the appropriate file in your C programs: #include "tcpware_include:rpc.h" You need to create a link options file, called, say, "XDR.OPT" containing the line: SYS$SHARE:TCPWARE_RPCLIB_SHR.EXE/SHARE for the D floating point option, or SYS$SHARE:TCPWARE_RPCLIBG_SHR.EXE/SHARE for the G floating point option. At compile time, you should issue a command like: $ cc myprog.c $ link myprog.obj, xdr.opt/options, sys$share:vaxcrtl/lib When you type $ HELP TCPWARE you get the following topics Overview FSS FTP NETCU NFSDISMOUNT NFSMOUNT NPS NSLOOKUP PING RCP RLOGIN RPCGEN RPCINFO RSH TELNET TES TFTP TRACEROUTE WHOIS Release_Notes Print_Commands Security_Services -------------------- List of XDR Routines -------------------- xdr_array encodes and decodes a variable-length array. xdr_accepted_reply part of an RPC reply message after the reply is accepted. xdr_authunix_parms UNIX-style authentication information. xdr_bool encodes and decodes a boolean value. xdr_bytes encodes and decodes bytes. xdr_callhdr the static part of an RPC request message header. xdr_callmsg an RPC request message. xdr_char encodes and decodes a character. xdr_destroy invokes the destroy routine associated with the XDR stream XDRS. xdr_double encodes and decodes a double-precision floating point number. xdr_enum encodes and decodes an enumerated type. xdr_float encodes and decodes a floating point value. xdr_free deallocates a data structure from memory. xdr_getpos invokes the get-position routine associated with the XDR stream XDRS. xdr_hyper encodes and decodes a VAX quad word to an XDR hyper-integer. (VMS version only!) xdr_inline invokes the in-line routine associated with the XDR stream XDRS. xdr_int encodes and decodes a four-byte integer. xdr_long encodes and decodes a longword. xdr_netobj data in the NETOBJ structure. (VMS version only!) xdr_opaque encodes and decodes the contents of a buffer. xdr_opaque_auth authentication information. xdr_pmap Port Mapper parameters. xdr_pmaplist a list of Port Mapper data. xdr_pointer encodes and decodes a pointer to a data structure. xdr_reference encodes and decodes a pointer to a data structure. xdr_rejected_reply part of an RPC reply message after the reply is rejected. xdr_replymsg an RPC reply header. Then it calls the appropriate routine to convert the rest of the message. xdr_setpos invokes the set position routine associated with XDRS. xdr_short encodes and decodes a two-byte signed integer. xdr_string encodes and decodes a null-terminated string. xdr_u_char encodes and decodes an unsigned character. xdr_u_hyper encodes and decodes a VAX quad word to an XDR unsigned hyper-integer. (VMS version only!) xdr_u_int encodes and decodes a four-byte unsigned integer. (VMS version only!) xdr_u_long encodes and decodes an unsigned longword. xdr_u_short encodes and decodes a two-byte unsigned integer. xdr_union encodes and decodes a union. xdr_vector encodes and decodes a vector. xdr_void encodes and decodes nothing. xdr_wrapstring encodes and decodes a null-terminated string. 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_readbytes reads data from the stream. (IRIX version only!) xdrrec_skiprecord goes to the end of the current record. xdrstdio_create Initializes the XDR stream object pointed to by XDRS. --------------------- Detailed Descriptions --------------------- ------------------ xdr_accepted_reply ------------------ XDR_ACCEPTED_REPLY converts an RPC reply message between local and XDR formats. bool_t xdr_accepted_reply(xdrs, ar) XDR *xdrs; struct accepted_reply *ar; xdrs The address of a structure containing XDR coding information. ar The address of the structure containing the RPC reply message. --------- xdr_array --------- XDR_ARRAY converts a variable length array between local and XDR formats. bool_t xdr_array(xdrs, addrp, sizep, maxsize, elsize, elproc) XDR *xdrs; u_char **addrp; u_long *sizep; u_long maxsize; u_long elsize; xdrproc_t elproc; xdr_array Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. addrp The address of the address containing the array being converted. sizep The address of the number of elements in the array. maxsize The maximum number of elements the array can hold. elsize The size of each element, in bytes. elproc The XDR routine that handles each array element. ------------------ xdr_authunix_parms ------------------ XDR_AUTHUNIX_PARMS converts UNIX style authentication information between local and XDR formats. bool_t xdr_authunix_parms(xdrs, aupp) XDR *xdrs; struct authunix_parms *aupp; xdr_authunix_parms Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. aupp The UNIX style authentication information being converted. -------- xdr_bool -------- XDR_BOOL converts a boolean value between local and XDR formats. bool_t xdr_bool(xdrs, bp) XDR *xdrs; bool_t *bp; xdr_bool Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. bp The address of the boolean value. --------- xdr_bytes --------- XDR_BYTES converts bytes between local and XDR formats. bool_t xdr_bytes(xdrs, cpp, sizep, maxsize) XDR *xdrs; u_char **cpp; u_long *sizep; u_long maxsize; xdr_bytes Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. cpp The address of the address of the buffer containing the bytes being converted. sizep The address of the actual number of bytes being converted. maxsize The maximum number of bytes that can be used. ----------- xdr_callhdr ----------- XDR_CALLHDR converts the static part of an RPC request message header between local and XDR formats. bool_t xdr_callhdr(xdrs, chdr) XDR *xdrs; struct rpc_msg *chdr; xdr_callhdr Always returns TRUE. xdrs The address of a structure containing XDR coding information. chdr The address of the data being converted. ----------- xdr_callmsg ----------- XDR_CALLMSG converts an RPC request message between local and XDR formats. bool_t xdr_callmsg(xdrs, cmsg) XDR *xdrs; struct rpc_msg *cmsg; xdr_callmsg Returns TRUE if successful, FALSE otherwise. xdrs The address of a structure containing XDR coding information. cmsg The address of the message being converted. -------- xdr_char -------- XDR_CHAR converts a character between local and XDR formats. bool_t xdr_char(xdrs, cp) XDR *xdrs; bool_t *cp; xdr_char Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. cp The address of the character. ----------- xdr_destroy ----------- XDR_DESTROY invokes the destroy routine associated with the XDR stream XDRS. Destruction usually involves freeing private data structures associated with the stream. Using XDRS after invoking XDR_DESTROY is undefined. This routine is in the IRIX manual, but not the TCPWARE manual. void xdr_destroy(xdrs) XDR *xdrs xdrs The address of a structure containing XDR coding information. ---------- xdr_double ---------- XDR_DOUBLE converts a double precision floating point number between local and XDR formats. bool_t xdr_double(xdrs, dp) XDR *xdrs; double *dp; xdr_double Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. dp The address of the double precision floating point number. -------- xdr_enum -------- XDR_ENUM converts an enumerated type between local and XDR formats. bool_t xdr_enum(xdrs, ep) XDR *xdrs; enum_t *ep; xdr_enum Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. ep The address of the enumerated value. --------- xdr_float --------- XDR_FLOAT converts a floating point value between local and XDR formats. bool_t xdr_bool(xdrs, fp) XDR *xdrs; float *fp; xdr_float Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. fp The address of the floating point value. -------- xdr_free -------- XDR_FREE deallocates an XDR data structure from memory. void xdr_free(proc, objp) xdrproc_t proc; u_char objp; proc An XDR routine that describes the data structure. objp The address of the data structure. ---------- xdr_getpos ---------- XDR_GETPOS invokes the get-position routine associated with the XDR stream XDRS. The routine returns an unsigned integer, which indicates the position of the XDR byte stream. This routine is in the IRIX manual, but not the TCPWARE manual. u_int xdr_getpos(xdrs) XDR *xdrs; xdr_getpos The position of the XDR byte stream. xdrs The address of a structure containing XDR coding information. --------- xdr_hyper --------- XDR_HYPER converts between a VAX quad word and an XDR hyper-integer. This routine is in the VMS library, but not the IRIX library. bool_t xdr_hyper(xdrs, ptr) XDR *xdrs; quad *ptr; xdr_hyper Returns TRUE if successful, and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. ptr The address of the structure containing the quad word. ---------- xdr_inline ---------- XDR_INLINE invokes the in-line routine associated with the XDR stream XDRS. The routine returns a pointer to a contiguous piece of the stream's buffer. This routine is in the IRIX manual, but not the TCPWARE manual. long*xdr_inline(xdrs,len) XDR *xdrs; int len; xdr_inline A pointer to a contiguous piece of the stream's buffer, or NULL (0) if it cannot allocate a continuous piece. xdrs The address of the structure containing XDR encoding and decoding information. len The byte length of the desired buffer. ------- xdr_int ------- XDR_INT converts a four-byte integer between local and XDR formats. bool_t xdr_int(xdrs, ip) XDR *xdrs; int *ip; xdr_int Returns TRUE if successful, FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. ip The address of the integer. -------- xdr_long -------- XDR_LONG converts a longword between local and XDR formats. bool_t xdr_long(xdrs, lp) XDR *xdrs; u_long *lp; xdr_long Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. lp The address of the longword. ---------- xdr_netobj ---------- XDR_NETOBJ converts data in the NETOBJ structure between local and XDR formats. This routine is in the VMS library, but not the IRIX library. bool_t xdr_netobj(xdrs, ptr) XDR *xdrs; netobj *ptr; xdr_netobj Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. ptr The address of the following structure: typedef struct { u_long n_len; byte *n_bytes; } netobj; ---------- xdr_opaque ---------- XDR_OPAQUE converts the contents of a buffer between local and XDR formats. This routine treats the data as a fixed length of bytes, and does not attempt to interpret them. bool_t xdr_opaque(xdrs, cp, cnt) XDR *xdrs; char *cp; u_long cnt; xdr_opaque Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. cp The address of the buffer containing opaque data. cnt The byte length. --------------- xdr_opaque_auth --------------- XDR_OPAQUE_AUTH converts authentication data between local and XDR formats. bool_t xdr_opaque_auth(xdrs, ap) XDR *xdrs; struct opaque_auth *ap; xdr_opaque_auth Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. ap The address of the authentication information. -------- xdr_pmap -------- XDR_PMAP converts Port Mapper parameters between local and XDR formats. #include "TCPWARE_INCLUDE:PMAP_PROT.H" bool_t xdr_pmap(xdrs, regs) XDR *xdrs; struct pmap *regs; xdr_pmap Returnst TRUE if it succeeds and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. regs The address of a structure containing the program number, version number, protocol number, and port number. This is the data being converted. ------------ xdr_pmaplist ------------ XDR_PMAPLIST converts a list of Port Mapping data between local and XDR formats. #include "TCPWARE_INCLUDE:PMAP_PROT.H" bool_t xdr_pmaplist(xdrs, rpp) XDR *xdrs; struct pmaplist **rpp; xdr_pmaplist Returnst TRUE if it succeeds and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. rpp The address of the address of the structure containing Port Mapper data. ----------- xdr_pointer ----------- XDR_POINTER converts a recursive data structure between local and XDR format. bool_t xdr_pointer(xdrs, objpp, obj_size, xdr_obj) XDR *xdrs; u_char **objpp; u_long obj_size; xdrproc_t xdr_obj; xdr_pointer Returns TRUE if successful, FALSE otherwise. xdrs The address of a structure containing XDR coding information. objpp The address of the address containing the data being converted. obj_size The size of the data structure in bytes. xdr_obj The XDR routine that describes the object being pointed to. ------------- xdr_reference ------------- XDR_REFERENCE recursively converts a structure that is referenced by a pointer inside the structure between local and XDR formats. bool_t xdr_reference(xdrs, objpp, obj_size, xdr_obj) XDR *xdrs; u_char **objpp; u_long obj_size; xdrproc_t xdr_obj; xdr_reference Returns TRUE if success, FALSE otherwise. xdrs The address of a structure containing XDR coding information. objpp The address of the address of a structure containing the data being converted. obj_size The size of the referenced structure. xdr_obj The XDR routine that describes the object being pointed to. ------------------ xdr_rejected_reply ------------------ XDR_REJECTED_REPLY converts the remainder of an RPC reply message between local and XDR formats. This routine is called after the header indicates that the reply is rejected. bool_t xdr_rejected_reply(xdrs, rr) XDR *xdrs; struct rejected_reply *rr; xdr_rejected_reply Returns TRUE if success, FALSE otherwise. xdrs The address of a structure containing XDR coding information. rr The address of the structure containing the reply message. ------------ xdr_replymsg ------------ XDR_REPLYMSG converts the RPC reply header between local and XDR formats, then calls the appropriate routine to convert the rest of the message. bool_t xdr_replymsg(xdrs, rmsg) XDR *xdrs; struct rpc_msg *rmsg; xdr_replymsg Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. rmsg The address of the structure containing the reply message. ---------- xdr_setpos ---------- XDR_SETPOS invokes the set position routine associated with the XDR stream XDRS. This routine is in the IRIX manual, but not the TCPWARE manual. bool_t xdr_setpos(xdrs,pos) XDR *xdrs; u_int pos; xdr_setpos Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. pos A position value obtained from XDR_GETPOS. --------- xdr_short --------- XDR_SHORT converts a two byte integer between local and XDR formats. bool_t xdr_short(xdrs, sp) XDR *xdrs; short *sp; xdr_short Returns TRUE if it succeeds, and FALSE otherwise. xdrs The address of a structure containing XDR coding information. sp The address of the short integer. ---------- xdr_string ---------- XDR_STRING converts a null-terminated string between local and XDR formats. XDR_STRING is the same as the XDR_WRAPSTRING routine, except that XDR_STRING allows you to specify the MAXSIZE. bool_t xdr_string(xdrs, cpp, maxsize) XDR *xdrs; char **cpp; u_long maxsize; xdr_string Returns TRUE if it succeeds and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. cpp The address of the address of the first byte of the string. maxsize The maximum length of the string. The service protocol determines this value. ---------- xdr_u_char ---------- XDR_U_CHAR converts an unsigned character between local and XDR formats. bool_t xdr_u_char(xdrs, bp) XDR *xdrs; u_char bp; xdr_u_char Returns TRUE if successful, and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. bp The address of the character being converted. ----------- xdr_u_hyper ----------- XDR_U_HYPER converts between a VAX quad word and an XDR unsigned hyper-integer. This routine is in the VMS library, but not the IRIX library. bool_t xdr_u_hyper(xdrs, ptr) XDR *xdrs; quad *ptr; xdr_u_hyper Returns TRUE if successful, and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. ptr The address of the structure containing the quad word. --------- xdr_u_int --------- XDR_U_INT converts a four-byte unsigned integer between local and XDR formats. This routine is in the VMS library, but not the IRIX library. bool_t xdr_u_int(xdrs, ip) XDR *xdrs; int *ip; xdr_u_int Returns TRUE if successful, FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. ip The address of the integer. ---------- xdr_u_long ---------- XDR_U_LONG converts an unsigned longword between local and XDR formats. bool_t xdr_u_long(xdrs, lp) XDR *xdrs; int *lp; xdr_u_long Returns TRUE if successful, FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. lp The address of the longword. ----------- xdr_u_short ----------- XDR_U_SHORT converts a two-byte unsigned integer between local and XDR formats. bool_t xdr_u_short(xdrs, sp) XDR *xdrs; int *sp; xdr_u_short Returns TRUE if successful, FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. sp The address of the integer. --------- xdr_union --------- XDR_UNION converts a union between local and XDR formats. bool_t xdr_union(xdrs, dscmp, unp, choices, dfault) XDR *xdrs; enum_t *dscmp; u_char *unp; xdr_discrim *choices; xdrproc_t dfault; xdr_union Returns TRUE if successful, and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. dscmp An integer from the CHOICES array. unp The address of the union. choices The address of an array. This array maps integers to XDR routines. dfault An XDR routine that is called if the DSCMP integer is not in the CHOICES array. ---------- xdr_vector ---------- XDR_VECTOR converts a vector (fixed length array) between local and XDR formats. bool_t xdr_vector(xdrs, basep, nelem, elmsize, xdr_elem) XDR *xdrs; u_char *basep; u_long nelem; u_long elmsize; xdrproc_t xdr_elem; xdr_vector Returns TRUE if successful, and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. basep The address of the array. nelem The number of elements in the array. elmsize The size of each element. xdr_elem A routine that converts each element from the local data format to XDR format and vice versa. -------- xdr_void -------- XDR_VOID converts nothing. It can be used as a placeholder for a program that passes no data. bool_t xdr_void(xdrs,ptr) XDR *xdr; u_char *ptr; xdr_void Always returns TRUE. xdrs The address of the structure containing XDR encoding and decoding information. ptr Ignored. -------------- xdr_wrapstring -------------- XDR_WRAPSTRING converts a null-terminated string between local and XDR formats. The maximum size of the string is assumed to be (2^32)-1. bool_t xdr_wrapstring(xdrs, cpp) XDR *xdrs; char **cpp; xdr_wrapstring Returns TRUE if it succeeds and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. cpp The address of the address of the first byte of the string. ------------- xdrmem_create ------------- XDRMEM_CREATE creates a memory buffer XDR stream. void xdrmem_create(xdrs, addr, size, op) XDR *xdrs; u_char *addr; u_long size; enum xdr_op op; xdrs The address of the structure containing XDR encoding and decoding information. addr The address of the buffer containing the encoded data. size The size of the ADDR buffer. op The value indicating which operations you will perform on the buffer. Valid values are XDR_ENCODE, XDR_DECODE and XDR_FREE. ------------- xdrrec_create ------------- XDRREC_CREATE creates a record oriented XDR stream. void xdrrec_create(xdrs, sendsize, recvsize, tcp_handle, readit, writeit) XDR *xdrs; u_long sendsize; u_long recvsize; u_char *tcp_handle; int (*readit)(); int (*writeit)(); xdrs The address of the structure containing XDR encoding and decoding information. sendsize The size of the send buffer in bytes. recvsize The size of the receive buffer in bytes. tcp_handle The address of the client or server handle. readit The address of a user written routine that reads data from the stream transport, in the format int readit(tcp_handle, buffer, len) u_char *tcp_handle; u_char *buffer; u_long len; READIT returns the number of bytes read, or -1 for an error. writeit The address of a user written routine that writes data to the stream transport, in the form int writeit(tcp_handle, buffer, len) u_char *tcp_handle; u_char *buffer; u_long len; WRITEIT returns the number of bytes written, or -1 for an error. ------------------ xdrrec_endofrecord ------------------ XDRREC_ENDOFRECORD marks the end of a record. bool_t xdrrec_endofrecord( xdrs, sendnow) XDR *xdrs; bool_t sendnow; xdrrec_endofrecord Returns TRUE if it succeeds, FALSE otherwise. xdrs The 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, then the record will be sent now. Otherwise, the record will be written to a buffer, and the buffer will be sent when it is full. ---------- xdrrec_eof ---------- XDRREC_EOF goes to the end of the current record, then verifies whether any more data can be read. bool_t xdrrec_eof(xdrs) XDR *xdrs; xdrrec_eof Returns TRUE if it reaches the end of the data stream, and FALSE if it finds more data to read. xdrs The address of the structure containing XDR encoding and decoding information. ---------------- xdrrec_readbytes ---------------- XDRREC_READBYTES reads data from the stream. int xdrrec_readbytes(XDR *xdrs, caddr_t addr, u_int len) XDRREC_READBYTES reads data from the stream. It behaves like the READ(2) system call against a pipe. It returns up to the number of bytes requested. A return value of 0 means end of record, and a return value of -1 indicated a serious error. ----------------- xdrrec_skiprecord ----------------- XDRREC_SKIPRECORD goes to the end of the current record. bool_t xdrrec_skiprecord(xdrs) XDR *xdrs; xdrrec_skiprecord Returns TRUE if it has skipped to the start of a record, and FALSE otherwise. xdrs The address of the structure containing XDR encoding and decoding information. --------------- xdrstdio_create --------------- XDRSTDIO_CREATE initializes the XDR stream object pointed to by XDRS. The XDR stream data is written to, or read from, the standard IO stream FILE. This routine is in the IRIX manual, but not the TCPWARE manual. void xdrstdio_create(xdrs,file,op) XDR *xdrs; FILE *file; enum xdr_op op; xdrs The address of the structure containing XDR encoding and decoding information. file The standard IO stream to or from which data is written or read. op Determines the direction of the stream, either XDR_ENCODE, XDR_DECODE, or XDR_FREE.