INTRODUCTION ====================== This directory contains a port of eXternal Data Representation (XDR) code from SunRPC (derived from the relicensed -- to 3-clause BSD -- implementation in Fedora 11's libtirpc package version 0.1.10-7). It has been adapted for newlib in the following ways: 1) xdr_* functions for fixed-width integral types have been added, such as xdr_int32_t() and similar. The implementation of stream-specific x_putlong() and x_getlong() functions has been modified to work properly whenever possible, even if sizeof(long) > 32bits -- and to correctly report failure when that is not possible. 2) Use of DEFUN(), EXFUN(), and various other portability macros. 3) Uses of 64bit types, such as xdr_hyper, xdr_u_longlong_t, and xdr_int64_t, as well as the xdr-specific typedefs quad_t and u_quad_t, are guarded by ___int64_t_defined. 4) Out-of-memory conditions are indicated by returning FALSE and setting errno = ENOMEM, rather than by printing error messages to stderr. (See #8, below). 5) Only xdrstdio.c requires stdio support, and it is only compiled if the target supports stdio (see stdio_dir in configure.host) 6) Uses a local implementation of ntohl/htonl, rather than one provided elsewhere. No dependency on any networking functions. 7) Floating point support refactored. Currently supports IEEE single and double precision, and VAX single and double precision. a) Those platforms which use float to represent double do not provide xdr_double(). 8) Error reporting can be customized using a private hook. This is described below. xdr is compiled and supported only for those platforms which set xdr_dir nonempty in configure.host. At present, the list of platforms which do this is: cygwin PORTING ====================== To port XDR to a new newlib target, first enable building it by modifying configure.host. Search for the 'case' statement where various *_dir= variables are set, and look for your target's entry (or add one if not present). Set xdr_dir: *-*-myplatform*) xdr_dir=xdr ;; If your platform does not use IEEE754 standard formats for floating point values (floats, doubles) you may need to add a new xdr_float_*.c implementation, and modify the bottom of xdr_float.c: ... #elif defined(__vax__) #include "xdr_float_vax.c" +#elif defined(__my_platform__) +#include "xdr_float_my_platform.c" #endif You may want to customize your platform's startup objects to set the error reporting callback for xdr (not likely, but see ERROR MESSAGES section). You may also want to customize the memory allocation semantics employed by the xdr routines. As stated in the xdr.h header: XDR_DECODE may allocate space if the pointer [to the location at which the decoded data is to be stored] is NULL. This data can be freed with the XDR_FREE operation. The default implementation defines the following macros in rpc/types.h, used throughout xdr/ to deal with memory allocation: #ifndef mem_alloc #define mem_alloc(bsize) calloc(1, bsize) #endif #ifndef mem_free #define mem_free(ptr, bsize) free(ptr) #endif By arranging that these symbols are #defined to some other memory allocation functions, different memory semantics can be imposed. To disallow memory allocation entirely, use the following: -D'mem_alloc(a)'=NULL -D'mem_free(a,b)'='do { ; } while(0)' In this case, any operations which would otherwise require memory to be allocated, will instead fail (return FALSE), and set errno=ENOMEM. ERROR MESSAGES ====================== This implementation of xdr provides a special hook, so that error messages generated by xdr may be captured by a user- defined facility. For certain error conditions, the internal printf-like function xdr_warnx (fmt, ...) is called. However, that function simply delegates to an internal function pointer to a callback function if set; otherwise, xdr_warnx does nothing. By setting this function pointer to a user-defined callback, the user can enable these messages to go to a syslog, stderr, or some other facility. The function should match the following typedef (see xdr_private.h): typedef void (* xdr_vprintf_t) (const char *, va_list); The desired callback can be registered by calling: xdr_vprintf_t xdr_set_vprintf (xdr_vprintf_t fnptr); The return value is the "old" function pointer, which may be NULL. However, neither the typedef nor the registration function are declared in the public headers. Clients wishing to use them must either declare the necessary symbols manually, or #include "xdr_private.h". More on this point, below. For instance: #include #include typedef void (* xdr_vprintf_t) (const char *, va_list); xdr_vprintf_t xdr_set_vprintf (xdr_vprintf_t fnptr); void my_vwarnx (const char * fmt, va_list ap) { (void) fprintf (stderr, fmt, ap); } main() { (void) xdr_set_vprintf (&my_vwarnx); ... } will cause xdr-generated error messages to go to stderr. It is not expected that end-user applications will make use of this facility. Rather, it is expected that IF certain *platforms* desire that these error messages be recorded, instead of expecting client apps to print error messages as necessary (*), then those platforms will, in their startup objects or static initialization, direct these messages to a logging facility, strace debug facility, etc. Therefore, the platform startup code, if part of newlib, can #include "xdr_private.h", or simply copy the two declarations from that file. However, most newlib targets will probably be satisfied with the default (silent) behavior. Note that the original Sun RPC implementation of XDR, as well as the glibc implementation, print these error messages to stderr. Cygwin, for greater similarity to glibc, registers an error message handler similar to the example above, within its startup code. (*) Client apps should already check for FALSE return values. In this case when xdr function return FALSE, the client app would then check errno and act appropriately. LICENSING AND PEDIGREE ====================== For years, the Sun RPC code, and the XDR implementation, was in legal license limbo http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=181493 as its license terms, while open, were of debatable compatibility with the GPL. In February of 2009, that changed: http://blogs.sun.com/webmink/entry/old_code_and_old_licenses http://lwn.net/Articles/319648/ As documented in the libtirpc rpm.spec file from Fedora 11: * Tue May 19 2009 Tom "spot" Callaway 0.1.10-7 - Replace the Sun RPC license with the BSD license, with the explicit permission of Sun Microsystems So, in the XDR implementation from Fedora 11's libtirpc package, after the modification above by Tom Callaway, each file carries the 3-clause BSD license and not the so-called "SunRPC" license. It is from this version that the newlib implementation here was derived, with the modifications described in the introduction, above.