Manual update for get.*_r functions

[Mark Kettenis]

   From: Ulrich Drepper <drepper@cygnus.com>
   Date: 30 Jun 1999 12:47:26 -0700

   Andreas Jaeger <aj@arthur.rhein-neckar.de> writes:

   > I've checked POSIX and my understanding of POSIX is that the check for 
   > NULL is necessary.

   POSIX says:

	   If successful, the getpwuid_r() and getpwnam_r() functions shall
	   return zero.  Otherwise, an error number shall be returned to
	   indicate the error.


   I.e., the return value is != 0 in all error cases and no found entry
   is an error case.

Yep, but Andreas is talking about gethostbyname_r().  The case he
illustrates with his example is the case where gethostbyname() sets
h_errno to HOST_NOT_FOUND, but errno is not set.  Therefore,
gethostbyname_r() returns 0 and stores HOST_NOT_FOUND in h_errnop.  So
instead of checking both the return value and the value stored in
h_errnop, Andreas suggests to check the result pointer.

AFAIK gethostbyname_r() is not standardized by POSIX.  If you look at
the code in bind 8.2 (src/include/netdb.h) you see that there are
two flavours of the various getXXbyYY_r functions.  Solaris and BSDI
return a pointer to the resul buffer on success (and NULL on some sort
of failure, which sets errno or stores something in h_errnop).  HPUX
and OSF return -1 on error and use a special data structure to
guarantee thread-safety.

While looking into these things, I came across a message apparently
written by one of the people who did the origional implementation of
gethostbyname_r on Solaris, where he said that returning a pointer to
the struct was a bit silly (since the same pointer is already stored
in a location specified by the user) and that returning an error value
would be the right thing to do (which is what we do for glibc right now).

Mark