.\" Copyright (C) 2001, 2004, 2005, 2007, 2014-2016, 2018-2020 Internet Systems Consortium, Inc. ("ISC")
.\" 
.\" This Source Code Form is subject to the terms of the Mozilla Public
.\" License, v. 2.0. If a copy of the MPL was not distributed with this
.\" file, You can obtain one at http://mozilla.org/MPL/2.0/.
.\"
.hy 0
.ad l
'\" t
.\"     Title: lwres_gethostent
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 2007-06-18
.\"    Manual: BIND9
.\"    Source: ISC
.\"  Language: English
.\"
.TH "LWRES_GETHOSTENT" "3" "2007\-06\-18" "ISC" "BIND9"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r \- lightweight resolver get network host entry
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <lwres/netdb\&.h>
.fi
.ft
.HP \w'struct\ hostent\ *\ lwres_gethostbyname('u
.BI "struct hostent * lwres_gethostbyname(const\ char\ *" "name" ");"
.HP \w'struct\ hostent\ *\ lwres_gethostbyname2('u
.BI "struct hostent * lwres_gethostbyname2(const\ char\ *" "name" ", int\ " "af" ");"
.HP \w'struct\ hostent\ *\ lwres_gethostbyaddr('u
.BI "struct hostent * lwres_gethostbyaddr(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ");"
.HP \w'struct\ hostent\ *\ lwres_gethostent('u
.BI "struct hostent * lwres_gethostent(void);"
.HP \w'void\ lwres_sethostent('u
.BI "void lwres_sethostent(int\ " "stayopen" ");"
.HP \w'void\ lwres_endhostent('u
.BI "void lwres_endhostent(void);"
.HP \w'struct\ hostent\ *\ lwres_gethostbyname_r('u
.BI "struct hostent * lwres_gethostbyname_r(const\ char\ *" "name" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");"
.HP \w'struct\ hostent\ *\ lwres_gethostbyaddr_r('u
.BI "struct hostent * lwres_gethostbyaddr_r(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");"
.HP \w'struct\ hostent\ *\ lwres_gethostent_r('u
.BI "struct hostent * lwres_gethostent_r(struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");"
.HP \w'void\ lwres_sethostent_r('u
.BI "void lwres_sethostent_r(int\ " "stayopen" ");"
.HP \w'void\ lwres_endhostent_r('u
.BI "void lwres_endhostent_r(void);"
.SH "DESCRIPTION"
.PP
These functions provide hostname\-to\-address and address\-to\-hostname lookups by means of the lightweight resolver\&. They are similar to the standard
\fBgethostent\fR(3)
functions provided by most operating systems\&. They use a
\fBstruct hostent\fR
which is usually defined in
<namedb\&.h>\&.
.PP
.if n \{\
.RS 4
.\}
.nf
struct  hostent {
        char    *h_name;        /* official 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 from name server */
};
#define h_addr  h_addr_list[0]  /* address, for backward compatibility */
.fi
.if n \{\
.RE
.\}
.PP
The members of this structure are:
.PP
\fBh_name\fR
.RS 4
The official (canonical) name of the host\&.
.RE
.PP
\fBh_aliases\fR
.RS 4
A NULL\-terminated array of alternate names (nicknames) for the host\&.
.RE
.PP
\fBh_addrtype\fR
.RS 4
The type of address being returned \(em
\fBPF_INET\fR
or
\fBPF_INET6\fR\&.
.RE
.PP
\fBh_length\fR
.RS 4
The length of the address in bytes\&.
.RE
.PP
\fBh_addr_list\fR
.RS 4
A
\fBNULL\fR
terminated array of network addresses for the host\&. Host addresses are returned in network byte order\&.
.RE
.PP
For backward compatibility with very old software,
\fBh_addr\fR
is the first address in
\fBh_addr_list\&.\fR
.PP
\fBlwres_gethostent()\fR,
\fBlwres_sethostent()\fR,
\fBlwres_endhostent()\fR,
\fBlwres_gethostent_r()\fR,
\fBlwres_sethostent_r()\fR
and
\fBlwres_endhostent_r()\fR
provide iteration over the known host entries on systems that provide such functionality through facilities like
/etc/hosts
or NIS\&. The lightweight resolver does not currently implement these functions; it only provides them as stub functions that always return failure\&.
.PP
\fBlwres_gethostbyname()\fR
and
\fBlwres_gethostbyname2()\fR
look up the hostname
\fIname\fR\&.
\fBlwres_gethostbyname()\fR
always looks for an IPv4 address while
\fBlwres_gethostbyname2()\fR
looks for an address of protocol family
\fIaf\fR: either
\fBPF_INET\fR
or
\fBPF_INET6\fR
\(em IPv4 or IPV6 addresses respectively\&. Successful calls of the functions return a
\fBstruct hostent\fRfor the name that was looked up\&.
\fBNULL\fR
is returned if the lookups by
\fBlwres_gethostbyname()\fR
or
\fBlwres_gethostbyname2()\fR
fail\&.
.PP
Reverse lookups of addresses are performed by
\fBlwres_gethostbyaddr()\fR\&.
\fIaddr\fR
is an address of length
\fIlen\fR
bytes and protocol family
\fItype\fR
\(em
\fBPF_INET\fR
or
\fBPF_INET6\fR\&.
\fBlwres_gethostbyname_r()\fR
is a thread\-safe function for forward lookups\&. If an error occurs, an error code is returned in
\fI*error\fR\&.
\fIresbuf\fR
is a pointer to a
\fBstruct hostent\fR
which is initialised by a successful call to
\fBlwres_gethostbyname_r()\fR\&.
\fIbuf\fR
is a buffer of length
\fIlen\fR
bytes which is used to store the
\fBh_name\fR,
\fBh_aliases\fR, and
\fBh_addr_list\fR
elements of the
\fBstruct hostent\fR
returned in
\fIresbuf\fR\&. Successful calls to
\fBlwres_gethostbyname_r()\fR
return
\fIresbuf\fR, which is a pointer to the
\fBstruct hostent\fR
it created\&.
.PP
\fBlwres_gethostbyaddr_r()\fR
is a thread\-safe function that performs a reverse lookup of address
\fIaddr\fR
which is
\fIlen\fR
bytes long and is of protocol family
\fItype\fR
\(em
\fBPF_INET\fR
or
\fBPF_INET6\fR\&. If an error occurs, the error code is returned in
\fI*error\fR\&. The other function parameters are identical to those in
\fBlwres_gethostbyname_r()\fR\&.
\fIresbuf\fR
is a pointer to a
\fBstruct hostent\fR
which is initialised by a successful call to
\fBlwres_gethostbyaddr_r()\fR\&.
\fIbuf\fR
is a buffer of length
\fIlen\fR
bytes which is used to store the
\fBh_name\fR,
\fBh_aliases\fR, and
\fBh_addr_list\fR
elements of the
\fBstruct hostent\fR
returned in
\fIresbuf\fR\&. Successful calls to
\fBlwres_gethostbyaddr_r()\fR
return
\fIresbuf\fR, which is a pointer to the
\fBstruct hostent()\fR
it created\&.
.SH "RETURN VALUES"
.PP
The functions
\fBlwres_gethostbyname()\fR,
\fBlwres_gethostbyname2()\fR,
\fBlwres_gethostbyaddr()\fR, and
\fBlwres_gethostent()\fR
return NULL to indicate an error\&. In this case the global variable
\fBlwres_h_errno\fR
will contain one of the following error codes defined in
<lwres/netdb\&.h>:
.PP
\fBHOST_NOT_FOUND\fR
.RS 4
The host or address was not found\&.
.RE
.PP
\fBTRY_AGAIN\fR
.RS 4
A recoverable error occurred, e\&.g\&., a timeout\&. Retrying the lookup may succeed\&.
.RE
.PP
\fBNO_RECOVERY\fR
.RS 4
A non\-recoverable error occurred\&.
.RE
.PP
\fBNO_DATA\fR
.RS 4
The name exists, but has no address information associated with it (or vice versa in the case of a reverse lookup)\&. The code NO_ADDRESS is accepted as a synonym for NO_DATA for backwards compatibility\&.
.RE
.PP
\fBlwres_hstrerror\fR(3)
translates these error codes to suitable error messages\&.
.PP
\fBlwres_gethostent()\fR
and
\fBlwres_gethostent_r()\fR
always return
\fBNULL\fR\&.
.PP
Successful calls to
\fBlwres_gethostbyname_r()\fR
and
\fBlwres_gethostbyaddr_r()\fR
return
\fIresbuf\fR, a pointer to the
\fBstruct hostent\fR
that was initialised by these functions\&. They return
\fBNULL\fR
if the lookups fail or if
\fIbuf\fR
was too small to hold the list of addresses and names referenced by the
\fBh_name\fR,
\fBh_aliases\fR, and
\fBh_addr_list\fR
elements of the
\fBstruct hostent\fR\&. If
\fIbuf\fR
was too small, both
\fBlwres_gethostbyname_r()\fR
and
\fBlwres_gethostbyaddr_r()\fR
set the global variable
\fBerrno\fR
to
\fBERANGE\fR\&.
.SH "SEE ALSO"
.PP
\fBgethostent\fR(3),
\fBlwres_getipnode\fR(3),
\fBlwres_hstrerror\fR(3)
.SH "BUGS"
.PP
\fBlwres_gethostbyname()\fR,
\fBlwres_gethostbyname2()\fR,
\fBlwres_gethostbyaddr()\fR
and
\fBlwres_endhostent()\fR
are not thread safe; they return pointers to static data and provide error codes through a global variable\&. Thread\-safe versions for name and address lookup are provided by
\fBlwres_gethostbyname_r()\fR, and
\fBlwres_gethostbyaddr_r()\fR
respectively\&.
.PP
The resolver daemon does not currently support any non\-DNS name services such as
/etc/hosts
or
\fBNIS\fR, consequently the above functions don\*(Aqt, either\&.
.SH "AUTHOR"
.PP
\fBInternet Systems Consortium, Inc\&.\fR
.SH "COPYRIGHT"
.br
Copyright \(co 2001, 2004, 2005, 2007, 2014-2016, 2018-2020 Internet Systems Consortium, Inc. ("ISC")
.br