1INTRODUCTION
2======================
3This directory contains a port of eXternal Data Representation
4(XDR) code from SunRPC (derived from the relicensed -- to
53-clause BSD -- implementation in Fedora 11's libtirpc package
6version 0.1.10-7). It has been adapted for newlib in the
7following ways:
8
91) xdr_* functions for fixed-width integral types have been
10   added, such as xdr_int32_t() and similar. The implementation
11   of stream-specific x_putlong() and x_getlong() functions
12   has been modified to work properly whenever possible, even
13   if sizeof(long) > 32bits -- and to correctly report failure
14   when that is not possible.
152) Use of DEFUN(), EXFUN(), and various other portability
16   macros.
173) Uses of 64bit types, such as xdr_hyper, xdr_u_longlong_t,
18   and xdr_int64_t, as well as the xdr-specific typedefs
19   quad_t and u_quad_t, are guarded by ___int64_t_defined.
204) Out-of-memory conditions are indicated by returning FALSE
21   and setting errno = ENOMEM, rather than by printing error
22   messages to stderr. (See #8, below).
235) Only xdrstdio.c requires stdio support, and it is only
24   compiled if the target supports stdio (see stdio_dir in
25   configure.host)
266) Uses a local implementation of ntohl/htonl, rather than
27   one provided elsewhere. No dependency on any networking
28   functions.
297) Floating point support refactored. Currently supports
30   IEEE single and double precision, and VAX single and
31   double precision.
32   a) Those platforms which use float to represent double
33      do not provide xdr_double().
348) Error reporting can be customized using a private hook.
35   This is described below.
36
37xdr is compiled and supported only for those platforms which
38set xdr_dir nonempty in configure.host. At present, the list
39of platforms which do this is:
40   cygwin
41
42
43PORTING
44======================
45To port XDR to a new newlib target, first enable building it
46by modifying configure.host.  Search for the 'case' statement
47where various *_dir= variables are set, and look for your
48target's entry (or add one if not present).  Set xdr_dir:
49
50  *-*-myplatform*)
51        xdr_dir=xdr
52	;;
53
54If your platform does not use IEEE754 standard formats for
55floating point values (floats, doubles) you may need to add
56a new xdr_float_*.c implementation, and modify the bottom of
57xdr_float.c:
58
59  ...
60  #elif defined(__vax__)
61  #include "xdr_float_vax.c"
62 +#elif defined(__my_platform__)
63 +#include "xdr_float_my_platform.c"
64  #endif
65
66You may want to customize your platform's startup objects to set
67the error reporting callback for xdr (not likely, but see ERROR
68MESSAGES section).
69
70You may also want to customize the memory allocation semantics
71employed by the xdr routines.  As stated in the xdr.h header:
72
73  XDR_DECODE may allocate space if the pointer [to the location
74  at which the decoded data is to be stored] is NULL. This
75  data can be freed with the XDR_FREE operation.
76
77The default implementation defines the following macros in
78rpc/types.h, used throughout xdr/ to deal with memory
79allocation:
80
81  #ifndef mem_alloc
82  #define mem_alloc(bsize)        calloc(1, bsize)
83  #endif
84  #ifndef mem_free
85  #define mem_free(ptr, bsize)    free(ptr)
86  #endif
87
88By arranging that these symbols are #defined to some other
89memory allocation functions, different memory semantics can be
90imposed. To disallow memory allocation entirely, use the
91following:
92
93  -D'mem_alloc(a)'=NULL -D'mem_free(a,b)'='do { ; } while(0)'
94
95In this case, any operations which would otherwise require
96memory to be allocated, will instead fail (return FALSE),
97and set errno=ENOMEM.
98
99
100ERROR MESSAGES
101======================
102This implementation of xdr provides a special hook, so that
103error messages generated by xdr may be captured by a user-
104defined facility. For certain error conditions, the internal
105printf-like function
106  xdr_warnx (fmt, ...)
107is called.  However, that function simply delegates to an
108internal function pointer to a callback function if set;
109otherwise, xdr_warnx does nothing.
110
111By setting this function pointer to a user-defined callback,
112the user can enable these messages to go to a syslog, stderr,
113or some other facility.  The function should match the
114following typedef (see xdr_private.h):
115
116  typedef void (* xdr_vprintf_t) (const char *, va_list);
117
118The desired callback can be registered by calling:
119
120  xdr_vprintf_t xdr_set_vprintf (xdr_vprintf_t fnptr);
121
122The return value is the "old" function pointer, which may
123be NULL.
124
125However, neither the typedef nor the registration function
126are declared in the public headers. Clients wishing to use
127them must either declare the necessary symbols manually,
128or #include "xdr_private.h". More on this point, below.
129
130For instance:
131  #include <stdarg.h>
132  #include <stdio.h>
133  typedef void (* xdr_vprintf_t) (const char *, va_list);
134  xdr_vprintf_t xdr_set_vprintf (xdr_vprintf_t fnptr);
135
136  void my_vwarnx (const char * fmt, va_list ap)
137  {
138    (void) fprintf (stderr, fmt, ap);
139  }
140
141  main()
142  {
143    (void) xdr_set_vprintf (&my_vwarnx);
144    ...
145  }
146
147will cause xdr-generated error messages to go to stderr.
148
149It is not expected that end-user applications will make use
150of this facility.  Rather, it is expected that IF certain
151*platforms* desire that these error messages be recorded,
152instead of expecting client apps to print error messages as
153necessary (*), then those platforms will, in their startup
154objects or static initialization, direct these messages to
155a logging facility, strace debug facility, etc.
156
157Therefore, the platform startup code, if part of newlib, can
158#include "xdr_private.h", or simply copy the two declarations
159from that file.
160
161However, most newlib targets will probably be satisfied with
162the default (silent) behavior. Note that the original Sun RPC
163implementation of XDR, as well as the glibc implementation,
164print these error messages to stderr.  Cygwin, for greater
165similarity to glibc, registers an error message handler similar
166to the example above, within its startup code.
167
168(*) Client apps should already check for FALSE return values.
169    In this case when xdr function return FALSE, the client
170    app would then check errno and act appropriately.
171
172
173LICENSING AND PEDIGREE
174======================
175For years, the Sun RPC code, and the XDR implementation, was in
176legal license limbo
177  http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=181493
178as its license terms, while open, were of debatable compatibility
179with the GPL. In February of 2009, that changed:
180  http://blogs.sun.com/webmink/entry/old_code_and_old_licenses
181  http://lwn.net/Articles/319648/
182
183As documented in the libtirpc rpm.spec file from Fedora 11:
184* Tue May 19 2009 Tom "spot" Callaway <xxxx@redhat.com> 0.1.10-7
185  - Replace the Sun RPC license with the BSD license, with the
186    explicit permission of Sun Microsystems
187
188So, in the XDR implementation from Fedora 11's libtirpc package,
189after the modification above by Tom Callaway, each file carries
190the 3-clause BSD license and not the so-called "SunRPC" license.
191It is from this version that the newlib implementation here was
192derived, with the modifications described in the introduction,
193above.
194
195