gethostbyname()

get a network host entry, given a name

Synopsis:

#include <netdb.h>

struct hostent *gethostbyname( char *name );

Description:

The gethostbyname() routine gets a network host entry by name. It returns a pointer to a structure of type hostent that describes an Internet host. This structure contains either the information obtained from the name server, named, or broken-out fields from a line in /etc/hosts.

When using the name server, gethostbyname() searches for the named host in the current domain and in the domain's parents, unless the name ends in a dot.


Note: If the name contains no dot, and if the environment variable HOSTALIASES contains the name of an alias file, the alias file is first searched for an alias matching the input name. This file has the same form as /etc/hosts.

You can use sethostent() to request the use of a connected TCP socket for queries. If the stayopen flag is nonzero, all queries to the name server will use TCP and the connection will be retained after each call to gethostbyname() or gethostbyaddr(). If the stayopen flag is zero, queries use UDP datagrams.

Returns:

A pointer to a valid hostent structure, or NULL if an error occurs (h_errno is set).

Errors:

See herror().

Files:

/etc/hosts
Host database file.

Environment variables:

HOSTALIASES
The name of an alias file to be searched first by gethostbyname() when the hostname contains no dot.

Classification:

POSIX 1003.1g (draft)

Safety:
Interrupt handler No
Signal handler No
Thread No

Caveats:

This function uses static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Currently, only the Internet address format is understood.

See also:

endhostent(), gethostbyaddr() gethostent(), herror(), hostent, sethostent()

/etc/hosts, named, /etc/resolv.conf