- along with this program; if not, write to the Free Software Foundation,
- Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
-
-#ifdef HAVE_CONFIG_H
-# include <config.h>
-#endif
-
-#ifdef HAVE_UNISTD_H
-# include <unistd.h>
-#endif
-#ifdef HAVE_STRING_H
-# include <string.h>
-#endif
-#ifdef HAVE_NETDB_H
-# include <netdb.h>
-#endif
-#ifdef HAVE_SYS_SOCKET_H
-# include <sys/socket.h>
-#endif
-
-#ifdef HAVE_NETINET_IN_H
-# include <netinet/in.h>
-#endif
-#ifdef HAVE_ARPA_INET_H
-# include <arpa/inet.h>
-#endif
-
-/* Returns the canonical hostname associated with HOST (allocated in a static
- buffer), or 0 if it can't be determined. */
+ along with this program. If not, see <http://www.gnu.org/licenses/>. */
+
+#include <config.h>
+
+#include "canon-host.h"
+
+#include <string.h>
+
+#include "getaddrinfo.h"
+
+/* Store the last error for the single-threaded version of this function. */
+static int last_cherror;
+
+/* Single-threaded of wrapper for canon_host_r. After a NULL return, error
+ messages may be retrieved via ch_strerror(). */
+char *
+canon_host (const char *host)
+{
+ return canon_host_r (host, &last_cherror);
+}
+
+/* Return a malloc'd string containing the canonical hostname associated with
+ HOST, or NULL if a canonical name cannot be determined. On NULL return,
+ if CHERROR is not NULL, set *CHERROR to an error code as returned by
+ getaddrinfo(). Use ch_strerror_r() or gai_strerror() to convert a *CHERROR
+ value to a string suitable for error messages.
+
+ WARNINGS
+ HOST must be a string representation of a resolvable name for this host.
+ Strings containing an IP address in dotted decimal notation will be
+ returned as-is, without further resolution.
+
+ The use of the word "canonical" in this context is unfortunate but
+ entrenched. The value returned by this function will be the end result
+ of the resolution of any CNAME chains in the DNS. There may only be one
+ such value for any given hostname, though the actual IP address
+ referenced by this value and the device using that IP address may each
+ actually have any number of such "canonical" hostnames. See the POSIX
+ getaddrinfo spec <http://www.opengroup.org/susv3xsh/getaddrinfo.html">,
+ RFC 1034 <http://www.faqs.org/rfcs/rfc1034.html>, & RFC 2181
+ <http://www.faqs.org/rfcs/rfc2181.html> for more on what this confusing
+ term really refers to. */