Networking Services Library Functions gethostbyname(3NSL)
NAME
gethostbyname, gethostbynamer, gethostbyaddr,
gethostbyaddrr, gethostent, gethostentr, sethostent,
endhostent - get network host entry
SYNOPSIS
cc [ flag... ] file... -lnsl [ library... ]
#include
struct hostent *gethostbyname(const char *name);
struct hostent *gethostbynamer(const char *name,
struct hostent *result, char *buffer, int buflen,
int *herrnop);
struct hostent *gethostbyaddr(const char *addr, int len,
int type);
struct hostent *gethostbyaddrr(const char *addr, int length,
int type, struct hostent *result, char *buffer,
int buflen, int *herrnop);
struct hostent *gethostent(void);
struct hostent *gethostentr(struct hostent *result,
char *buffer, int buflen, int *herrnop);
int sethostent(int stayopen);
int endhostent(void);
DESCRIPTION
These functions are used to obtain entries describing hosts.
An entry can come from any of the sources for hosts speci-
fied in the /etc/nsswitch.conf file. See nsswitch.conf(4).
These functions have been superseded by
getipnodebyname(3SOCKET), getipnodebyaddr(3SOCKET), and
getaddrinfo(3SOCKET), which provide greater portability to
applications when multithreading is performed or technolo-
gies such as IPv6 are used. For example, the functions
described in the following cannot be used with applications
targeted to work with IPv6.
SunOS 5.11 Last change: 24 Aug 2007 1
Networking Services Library Functions gethostbyname(3NSL)
The gethostbyname() function searches for information for a
host with the hostname specified by the character-string
parameter name.
The gethostbyaddr() function searches for information for a
host with a given host address. The parameter type specifies
the family of the address. This should be one of the address
families defined in . See the NOTES section
for more information. Also see the EXAMPLES section for
information on how to convert an Internet IP address nota-
tion that is separated by periods (.) into an addr parame-
ter. The parameter len specifies the length of the buffer
indicated by addr.
All addresses are returned in network order. In order to
interpret the addresses, byteorder(3SOCKET) must be used for
byte order conversion.
The sethostent(), gethostent(), and endhostent() functions
are used to enumerate host entries from the database.
The sethostent() function sets or resets the enumeration to
the beginning of the set of host entries. This function
should be called before the first call to gethostent().
Calls to gethostbyname() and gethostbyaddr() leave the
enumeration position in an indeterminate state. If the stay-
open flag is non-zero, the system can keep allocated
resources such as open file descriptors until a subsequent
call to endhostent().
Successive calls to the gethostent() function return either
successive entries or NUL, indicating the end of the
enumeration.
The endhostent() function can be called to indicate that the
caller expects to do no further host entry retrieval opera-
tions; the system can then deallocate resources it was
using. It is still allowed, but possibly less efficient, for
the process to call more host retrieval functions after cal-
ling endhostent().
Reentrant Interfaces
The gethostbyname(), gethostbyaddr(), and gethostent() func-
tions use static storage that is reused in each call, making
these functions unsafe for use in multithreaded applica-
tions.
SunOS 5.11 Last change: 24 Aug 2007 2
Networking Services Library Functions gethostbyname(3NSL)
The gethostbynamer(), gethostbyaddrr(), and gethostentr()
functions provide reentrant interfaces for these operations.
Each reentrant interface performs the same operation as its
non-reentrant counterpart, named by removing the r suffix.
The reentrant interfaces, however, use buffers supplied by
the caller to store returned results and the interfaces are
safe for use in both single-threaded and multithreaded
applications.
Each reentrant interface takes the same parameters as its
non-reentrant counterpart, as well as the following addi-
tional parameters. The parameter result must be a pointer to
a struct hostent structure allocated by the caller. On suc-
cessful completion, the function returns the host entry in
this structure. The parameter buffer must be a pointer to a
buffer supplied by the caller. This buffer is used as
storage space for the host data. All of the pointers within
the returned struct hostent result point to data stored
within this buffer. See the RETURN VALUES section for more
information. The buffer must be large enough to hold all of
the data associated with the host entry. The parameter
buflen should give the size in bytes of the buffer indicated
by buffer. The parameter herrnop should be a pointer to an
integer. An integer error status value is stored there on
certain error conditions. See the ERORS section for more
information.
For enumeration in multithreaded applications, the position
within the enumeration is a process-wide property shared by
all threads. The sethostent() function can be used in a mul-
tithreaded application but resets the enumeration position
for all threads. If multiple threads interleave calls to
gethostentr(), the threads will enumerate disjoint subsets
of the host database.
Like their non-reentrant counterparts, gethostbynamer() and
gethostbyaddrr() leave the enumeration position in an
indeterminate state.
RETURN VALUES
Host entries are represented by the struct hostent structure
defined in :
struct hostent {
char *hname; /* canonical name of host */
char **haliases; /* alias list */
int haddrtype; /* host address type */
SunOS 5.11 Last change: 24 Aug 2007 3
Networking Services Library Functions gethostbyname(3NSL)
int hlength; /* length of address */
char **haddrlist; /* list of addresses */
};
See the EXAMPLES section for information about how to
retrieve a ``.'' separated Internet IP address string from
the haddrlist field of struct hostent.
The gethostbyname(), gethostbynamer(), gethostbyaddr(), and
gethostbyaddrr() functions each return a pointer to a
struct hostent if they successfully locate the requested
entry; otherwise they return NUL.
The gethostent() and gethostentr() functions each return a
pointer to a struct hostent if they successfully enumerate
an entry; otherwise they return NUL, indicating the end of
the enumeration.
The gethostbyname(), gethostbyaddr(), and gethostent() func-
tions use static storage, so returned data must be copied
before a subsequent call to any of these functions if the
data is to be saved.
When the pointer returned by the reentrant functions
gethostbynamer(), gethostbyaddrr(), and gethostentr() is
not NUL, it is always equal to the result pointer that was
supplied by the caller.
The sethostent() and endhostent() functions return 0 on suc-
cess.
ERORS
The reentrant functions gethostbynamer(),
gethostbyaddrr(), and gethostentr() will return NUL and
set errno to ERANGE if the length of the buffer supplied by
caller is not large enough to store the result. See Intro(2)
for the proper usage and interpretation of errno in mul-
tithreaded applications.
The reentrant functions gethostbynamer() and
gethostbyaddrr() set the integer pointed to by herrnop to
one of these values in case of error.
SunOS 5.11 Last change: 24 Aug 2007 4
Networking Services Library Functions gethostbyname(3NSL)
On failures, the non-reentrant functions gethostbyname() and
gethostbyaddr() set a global integer herrno to indicate one
of these error codes (defined in ): HOSTNOTFOUND,
TRYAGAIN, NORECOVERY, NODATA, and NOADRES.
If a resolver is provided with a malformed address, or if
any other error occurs before gethostbyname() is resolved,
then gethostbyname() returns an internal error with a value
of -1.
The gethostbyname() function will set herrno to
NETDBINTERNAL when it returns a NUL value.
EXAMPLES
Example 1 Using gethostbyaddr()
Here is a sample program that gets the canonical name,
aliases, and ``.'' separated Internet IP addresses for a
given ``.'' separated IP address:
#include
#include
#include
#include
#include
#include
#include
int main(int argc, const char **argv)
{
inaddrt addr;
struct hostent *hp;
char **p;
if (argc != 2) {
(void) printf("usage: %s IP-address\n", argv[0]);
exit (1);
}
if ((int)(addr = inetaddr(argv[1])) == -1) {
(void) printf("IP-address must be of the form a.b.c.d\n");
exit (2);
}
hp = gethostbyaddr((char *)&addr, 4, AFINET);
if (hp == NUL) {
(void) printf("host information for %s not found\n", argv[1]);
exit (3);
}
for (p = hp->haddrlist; *p != 0; p]) {
struct inaddr in;
SunOS 5.11 Last change: 24 Aug 2007 5
Networking Services Library Functions gethostbyname(3NSL)
char **q;
(void) memcpy(&in.saddr, *p, sizeof (in.saddr));
(void) printf("%s%s", inetntoa(in), hp->hname);
for (q = hp->haliases; *q != 0; q])
(void) printf(" %s", *q);
(void) putchar('0);
}
exit (0);
}
Note that the preceding sample program is unsafe for use in
multithreaded applications.
FILES
/etc/hosts hosts file that associates the names
of hosts with their Internet Protocol
(IP) addresses
/etc/netconfig network configuration database
/etc/nsswitch.conf configuration file for the name ser-
vice switch
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level See Reentrant Interfaces in
the DESCRIPTION section.
SEE ALSO
Intro(2), Intro(3), byteorder(3SOCKET), inet(3SOCKET),
netdb.h(3HEAD), netdir(3NSL), hosts(4), netconfig(4),
nss(4), nsswitch.conf(4), attributes(5)
WARNINGS
The reentrant interfaces gethostbynamer(),
gethostbyaddrr(), and gethostentr() are included in this
release on an uncommitted basis only and are subject to
SunOS 5.11 Last change: 24 Aug 2007 6
Networking Services Library Functions gethostbyname(3NSL)
change or removal in future minor releases.
NOTES
To ensure that they all return consistent results, gethost-
byname(), gethostbynamer(), and netdirgetbyname() are
implemented in terms of the same internal library function.
This function obtains the system-wide source lookup policy
based on the inet family entries in netconfig(4) and the
hosts: entry in nsswitch.conf(4). Similarly, gethost-
byaddr(), gethostbyaddrr(), and netdirgetbyaddr() are
implemented in terms of the same internal library function.
If the inet family entries in netconfig(4) have a ``-'' in
the last column for nametoaddr libraries, then the entry for
hosts in nsswitch.conf will be used; nametoaddr libraries in
that column will be used, and nsswitch.conf will not be con-
sulted.
There is no analogue of gethostent() and gethostentr() in
the netdir functions, so these enumeration functions go
straight to the hosts entry in nsswitch.conf. Thus enumera-
tion can return results from a different source than that
used by gethostbyname(), gethostbynamer(), gethostbyaddr(),
and gethostbyaddrr().
All the functions that return a struct hostent must always
return the canonical name in the hname field. This name, by
definition, is the well-known and official hostname shared
between all aliases and all addresses. The underlying source
that satisfies the request determines the mapping of the
input name or address into the set of names and addresses in
hostent. Different sources might do that in different ways.
If there is more than one alias and more than one address in
hostent, no pairing is implied between them.
The system attempts to put those addresses that are on the
same subnet as the caller before addresses that are on dif-
ferent subnets. However, if address sorting is disabled by
setting SORTADRS to FALSE in the /etc/default/nss file,
the system does not put the local subnet addresses first.
See nss(4) for more information.
When compiling multithreaded applications, see Intro(3),
MULTITHREADED APLICATIONS, for information about the use of
the RENTRANT flag.
Use of the enumeration interfaces gethostent() and
gethostentr() is discouraged; enumeration might not be
SunOS 5.11 Last change: 24 Aug 2007 7
Networking Services Library Functions gethostbyname(3NSL)
supported for all database sources. The semantics of
enumeration are discussed further in nsswitch.conf(4).
The current implementations of these functions only return
or accept addresses for the Internet address family (type
AFINET).
The form for an address of type AFINET is a struct inaddr
defined in . The functions described in
inet(3SOCKET), and illustrated in the EXAMPLES section, are
helpful in constructing and manipulating addresses in this
form.
SunOS 5.11 Last change: 24 Aug 2007 8
|
