--- name: "lwres_sethostent" section: "3" platform: "linux" package: "libbind-dev" version: "1:9.11.5.P4+dfsg-5.1+deb10u7" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/lwres_sethostent" --- # lwres\_sethostent(3) lightweight resolver get network host entry ## 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 ## SYNOPSIS ``` #include ``` **struct hostent \* lwres\_gethostbyname(const char \****name***);** **struct hostent \* lwres\_gethostbyname2(const char \****name***, int** *af***);** **struct hostent \* lwres\_gethostbyaddr(const char \****addr***, int** *len***, int** *type***);** **struct hostent \* lwres\_gethostent(void);** **void lwres\_sethostent(int** *stayopen***);** **void lwres\_endhostent(void);** **struct hostent \* lwres\_gethostbyname\_r(const char \****name***, struct hostent \****resbuf***, char \****buf***, int** *buflen***, int \****error***);** **struct hostent \* lwres\_gethostbyaddr\_r(const char \****addr***, int** *len***, int** *type***, struct hostent \****resbuf***, char \****buf***, int** *buflen***, int \****error***);** **struct hostent \* lwres\_gethostent\_r(struct hostent \****resbuf***, char \****buf***, int** *buflen***, int \****error***);** **void lwres\_sethostent\_r(int** *stayopen***);** **void lwres\_endhostent\_r(void);** ## DESCRIPTION These functions provide hostname-to-address and address-to-hostname lookups by means of the lightweight resolver. They are similar to the standard [**gethostent**(3)](/gethostent/3.md) functions provided by most operating systems. They use a **struct hostent** which is usually defined in \. ``` 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 */ ``` The members of this structure are: **h\_name** The official (canonical) name of the host. **h\_aliases** A NULL-terminated array of alternate names (nicknames) for the host. **h\_addrtype** The type of address being returned — **PF\_INET** or **PF\_INET6**. **h\_length** The length of the address in bytes. **h\_addr\_list** A **NULL** terminated array of network addresses for the host. Host addresses are returned in network byte order. For backward compatibility with very old software, **h\_addr** is the first address in **h\_addr\_list.** **lwres\_gethostent()**, **lwres\_sethostent()**, **lwres\_endhostent()**, **lwres\_gethostent\_r()**, **lwres\_sethostent\_r()** and **lwres\_endhostent\_r()** 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. **lwres\_gethostbyname()** and **lwres\_gethostbyname2()** look up the hostname *name*. **lwres\_gethostbyname()** always looks for an IPv4 address while **lwres\_gethostbyname2()** looks for an address of protocol family *af*: either **PF\_INET** or **PF\_INET6** — IPv4 or IPV6 addresses respectively. Successful calls of the functions return a **struct hostent**for the name that was looked up. **NULL** is returned if the lookups by **lwres\_gethostbyname()** or **lwres\_gethostbyname2()** fail. Reverse lookups of addresses are performed by **lwres\_gethostbyaddr()**. *addr* is an address of length *len* bytes and protocol family *type* — **PF\_INET** or **PF\_INET6**. **lwres\_gethostbyname\_r()** is a thread-safe function for forward lookups. If an error occurs, an error code is returned in *\*error*. *resbuf* is a pointer to a **struct hostent** which is initialised by a successful call to **lwres\_gethostbyname\_r()**. *buf* is a buffer of length *len* bytes which is used to store the **h\_name**, **h\_aliases**, and **h\_addr\_list** elements of the **struct hostent** returned in *resbuf*. Successful calls to **lwres\_gethostbyname\_r()** return *resbuf*, which is a pointer to the **struct hostent** it created. **lwres\_gethostbyaddr\_r()** is a thread-safe function that performs a reverse lookup of address *addr* which is *len* bytes long and is of protocol family *type* — **PF\_INET** or **PF\_INET6**. If an error occurs, the error code is returned in *\*error*. The other function parameters are identical to those in **lwres\_gethostbyname\_r()**. *resbuf* is a pointer to a **struct hostent** which is initialised by a successful call to **lwres\_gethostbyaddr\_r()**. *buf* is a buffer of length *len* bytes which is used to store the **h\_name**, **h\_aliases**, and **h\_addr\_list** elements of the **struct hostent** returned in *resbuf*. Successful calls to **lwres\_gethostbyaddr\_r()** return *resbuf*, which is a pointer to the **struct hostent()** it created. ## RETURN VALUES The functions **lwres\_gethostbyname()**, **lwres\_gethostbyname2()**, **lwres\_gethostbyaddr()**, and **lwres\_gethostent()** return NULL to indicate an error. In this case the global variable **lwres\_h\_errno** will contain one of the following error codes defined in \: **HOST\_NOT\_FOUND** The host or address was not found. **TRY\_AGAIN** A recoverable error occurred, e.g., a timeout. Retrying the lookup may succeed. **NO\_RECOVERY** A non-recoverable error occurred. **NO\_DATA** 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. [**lwres\_hstrerror**(3)](/lwres_hstrerror/3.md) translates these error codes to suitable error messages. **lwres\_gethostent()** and **lwres\_gethostent\_r()** always return **NULL**. Successful calls to **lwres\_gethostbyname\_r()** and **lwres\_gethostbyaddr\_r()** return *resbuf*, a pointer to the **struct hostent** that was initialised by these functions. They return **NULL** if the lookups fail or if *buf* was too small to hold the list of addresses and names referenced by the **h\_name**, **h\_aliases**, and **h\_addr\_list** elements of the **struct hostent**. If *buf* was too small, both **lwres\_gethostbyname\_r()** and **lwres\_gethostbyaddr\_r()** set the global variable **errno** to **ERANGE**. ## SEE ALSO [**gethostent**(3)](/gethostent/3.md), [**lwres\_getipnode**(3)](/lwres_getipnode/3.md), [**lwres\_hstrerror**(3)](/lwres_hstrerror/3.md) ## BUGS **lwres\_gethostbyname()**, **lwres\_gethostbyname2()**, **lwres\_gethostbyaddr()** and **lwres\_endhostent()** 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 **lwres\_gethostbyname\_r()**, and **lwres\_gethostbyaddr\_r()** respectively. The resolver daemon does not currently support any non-DNS name services such as /etc/hosts or **NIS**, consequently the above functions don't, either. ## AUTHOR **Internet Systems Consortium, Inc.** ## COPYRIGHT Copyright © 2001, 2004, 2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC")\