source: trunk/libs/newlib/src/newlib/libc/xdr/README @ 543

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 <stdarg.h>
  #include <stdio.h>
  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 <xxxx@redhat.com> 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.