AN_GETHOSTBYNAME

Section: Antinat Programmer's Manual (3)
Updated: 2005-01-03
Index Return to Main Contents

NAME

an_gethostbyname - resolve hostname to address with threadsafety

SYNOPSIS

#include <antinat.h>

int an_gethostbyname(const char * hostname, struct hostent * destination, char * buf, int buf_length, struct hostent ** ret, int * thread_errno);

DESCRIPTION

The an_gethostbyname(3) function is a thread-safe, portable replacement for gethostbyname. Some platforms have a gethostbyname_r function; if this is found, an_gethostbyname(3) will use it. Some platforms use thread-local storage for gethostbyname; in these cases, an_gethostbyname(3) will wrap gethostbyname. Some platforms don't have any form of thread-safe gethostbyname; in which case, it will be implemented using locks. Beware on platforms without a built-in threadsafety mechanism: all calls to gethostbyname within your application must use this function, or else there is a possibility of corruption. This includes calls made from libraries to which your application links. If you are using one of these platforms, please lobby your vendor to support an implementation of gethostbyname_r.

The hostent structure contains pointers to external data within it. In order to implement this without requiring a corresponding deallocation call, memory is allocated out of the user-supplied buf array. This array should be at least 1024 bytes in length. If the function succeeds, the value of ret will point to destination; otherwise, it will be NULL. Finally, if determining the reason of an error is required, thread_errno contains the errno of the failed gethostbyname call; this avoids another thread overwriting an application-wide errno.

hostname A null-terminated array that contains the hostname that needs to be resolved into an IP address.

destination is a pointer to the structure that should be filled out with address information. This buffer will be used as the primary destination, although additional memory will be allocated from the user-supplied buffer, as described above.

buf is a pointer to a block of memory. This should be at least 1024 bytes in length. If there is insufficient space in this buffer, the call will fail.

buf_length is the number of bytes in the buf parameter, described above.

ret is a pointer to a struct hostent *. This will be modified to point to the hostent structure being used to store the data if the function succeeds; otherwise, it will be NULL. This value is analagous to the return value from gethostbyname.

thread_errno is the value of errno that was generated by the gethostbyname call. The exact meaning of this value is platform-dependent.

NOTES

As mentioned previously, be very careful using this function on platforms that do not have a native gethostbyname_r or thread-safe lookups. You must ensure that all calls to gethostbyname, including by libraries, are replaced by calls to this function or you will have race conditions. Where it is not possible to replace all instances of gethostbyname, you must implement your own locking around all functions that may potentially cause calls to gethostbyname, which will include an_bind_tohostname(3), an_bind_tosockaddr(3), an_connect_tohostname(3),and an_connect_tosockaddr(3). Given the difficulty of determining which functions may call gethostbyname, especially as libraries may change, please lobby your vendor to support gethostbyname_r or some better method for threadsafety than userspace locks. Platforms affected include BSD and Mac OS X.

RETURN VALUE

This call returns AN_ERROR_SUCCESS to indicate successful completion.

ERRORS

AN_ERROR_NETWORK: Could not resolve the hostname because the system gethostbyname call failed. In this case, you should check the thread_errno value for a better description of the error.
AN_ERROR_NOMEM: There was not enough space in the supplied buffer to allocate memory for all of the required hostent fields.

AUTHOR

Malcolm Smith <malxau@users.sourceforge.net>

Time: 14:19:44 GMT, January 09, 2005