Re: incorrect return value in gethostbyname_r() ?

[Greg Herlein]

> > OK, then tell me where the correct documentation is.  I am using:
> > 
> > http://www.gnu.org/manual/glibc-2.0.6/html_chapter/libc_25.html#SEC443
> 
> This is the documentation of the internal NSS interface, not of
> gethostbyname_r.
> 
> > I'd love to know what you are referring to.  
> 
> Install "libcinfo" on SuSE Linux 6.4. The glibc 2.1 info pages
> descripes the gethostbyname_r function.

This seems very wrong.  From the html glibc manual:

Now we know about the functions contained in the modules. It is
now time to describe the types. When we mentioned the reentrant
versions of the functions above, this means there are some
additional
arguments (compared with the standard, non-reentrant
version). The prototypes for the non-reentrant and reentrant
versions of our function above are: 

struct hostent *gethostbyname (const char *name)

int gethostbyname_r (const char *name, struct hostent
*result_buf,
                     char *buf, size_t buflen, struct hostent
**result,
                     int *h_errnop)

The actual prototype of the function in the NSS modules in this
case is 

enum nss_status _nss_files_gethostbyname_r (const char *name,
                                            struct hostent
*result_buf,
                                            char *buf, size_t
buflen,
                                            int *h_errnop)

I.e., the interface function is in fact the reentrant function
with the change of the return value and the omission of the
result parameter. While the user-level function returns a pointer
to the result the reentrant function return an enum nss_status
value: 

NSS_STATUS_TRYAGAIN 
       numeric value -2 
NSS_STATUS_UNAVAIL 
       numeric value -1 
NSS_STATUS_NOTFOUND 
       numeric value 0 
NSS_STATUS_SUCCESS 
       numeric value 1 


This is pretty clear, to me.  It's not discussing the
"internal" nss function if it's directly comparing it to the
normal (non-reentrant) gethostbyname.

Also, why is the glibc gethostbyname_r() so radically different
than on other unixes?  From the man page from a Solaris box:

RETURN VALUES
     Host entries are represented by the struct hostent structure
     defined in <netdb.h>:

          struct hostent {
               char   *h_name;         /* canonical name of host
*/
               char   **h_aliases;     /* alias list */
               int    h_addrtype;      /* host address type */
               int    h_length;        /* length of address */
               char   **h_addr_list;   /* list of addresses */
          };

     See the EXAMPLES section below for information about how  to
     retrieve  a  ``.'' separated Internet IP address string from
     the h_addr_list field of struct hostent.

     The functions gethostbyname(),  gethostbyname_r(),  gethost-
     byaddr(),  and  gethostbyaddr_r() each return a pointer to a
     struct hostent if they  successfully  locate  the  requested
     entry; otherwise they return NULL.
                                                              

Who is the person "in charge" of this area?  Who is keeping the
docs up to date.  I'll help with the docs if you'll help me clear
up the "right" way for this function.

Greg

/**************************************************************
Greg Herlein                                   address@hidden
Herlein Engineering                             www.herlein.com
***************************************************************/