.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the University of
-.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\" SUCH DAMAGE.
.\"
.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
-.\" $FreeBSD: src/lib/libc/net/gethostbyname.3,v 1.12.2.6 2001/08/17 15:42:38 ru Exp $
+.\" $FreeBSD: src/lib/libc/net/gethostbyname.3,v 1.38 2007/01/09 00:28:02 imp Exp $
.\"
-.Dd May 25, 1995
+.Dd May 12, 2006
.Dt GETHOSTBYNAME 3
.Os
.Sh NAME
-.Nm endhostent ,
-.Nm gethostbyaddr ,
.Nm gethostbyname ,
.Nm gethostbyname2 ,
+.Nm gethostbyaddr ,
.Nm gethostent ,
+.Nm sethostent ,
+.Nm endhostent ,
.Nm herror ,
-.Nm hstrerror ,
-.Nm sethostent
+.Nm hstrerror
.Nd get network host entry
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
-.Fd #include <netdb.h>
-.Vt extern int h_errno ;
-.Ft void
-.Fo endhostent
-.Fa void
-.Fc
+.In netdb.h
+.Vt int h_errno ;
.Ft struct hostent *
-.Fo gethostbyaddr
-.Fa "const void *addr"
-.Fa "socklen_t len"
-.Fa "int type"
-.Fc
+.Fn gethostbyname "const char *name"
.Ft struct hostent *
-.Fo gethostbyname
-.Fa "const char *name"
-.Fc
+.Fn gethostbyname2 "const char *name" "int af"
.Ft struct hostent *
-.Fo gethostbyname2
-.Fa "const char *name"
-.Fa "int af"
-.Fc
+.Fn gethostbyaddr "const void *addr" "socklen_t len" "int type"
.Ft struct hostent *
-.Fo gethostent
-.Fa void
-.Fc
+.Fn gethostent void
.Ft void
-.Fo herror
-.Fa "const char *string"
-.Fc
-.Ft const char *
-.Fo hstrerror
-.Fa "int err"
-.Fc
+.Fn sethostent "int stayopen"
+.Ft void
+.Fn endhostent void
.Ft void
-.Fo sethostent
-.Fa "int stayopen"
-.Fc
+.Fn herror "const char *string"
+.Ft const char *
+.Fn hstrerror "int err"
.Sh DESCRIPTION
+.Bf -symbolic
+The
+.Xr getaddrinfo 3
+and
+.Xr getnameinfo 3
+functions are preferred over the
+.Fn gethostbyname ,
+.Fn gethostbyname2 ,
+and
+.Fn gethostbyaddr
+functions.
+.Ef
+.Pp
The
.Fn gethostbyname ,
.Fn gethostbyname2
each return a pointer to an object with the
following structure describing an internet host
referenced by name or by address, respectively.
-This structure contains either the information obtained from the name server,
-.Xr named 8 ,
-or broken-out fields from a line in
-.Pa /etc/hosts .
-If the local name server is not running these routines do a lookup in
+.Pp
+The
+.Fa name
+argument passed to
+.Fn gethostbyname
+or
+.Fn gethostbyname2
+should point to a
+.Dv NUL Ns -terminated
+hostname.
+The
+.Fa addr
+argument passed to
+.Fn gethostbyaddr
+should point to an address which is
+.Fa len
+bytes long,
+in binary form
+(i.e., not an IP address in human readable
+.Tn ASCII
+form).
+The
+.Fa type
+argument specifies the address family
+(e.g.\&
+.Dv AF_INET , AF_INET6 ,
+etc.) of this address.
+.Pp
+The structure returned contains information obtained from
+.Xr mDNSResponder 8 ,
+including records in
.Pa /etc/hosts .
+.\"The structure returned contains either the information obtained from the name
+.\"server,
+.\".Xr named 8 ,
+.\"broken-out fields from a line in
+.\".Pa /etc/hosts ,
+.\"or database entries supplied by the
+.\".Xr yp 8
+.\"system.
+.\"The order of the lookups is controlled by the
+.\".Sq hosts
+.\"entry in
+.\".Xr nsswitch.conf 5 .
.Bd -literal
struct hostent {
char *h_name; /* official name of host */
.Fn gethostbyname2
will search for the named host in the current domain and its parents
unless the name ends in a dot.
-If the name contains no dot, and if the environment variable
-.Dq Ev HOSTALIASES
-contains the name of an alias file, the alias file will first be searched
-for an alias matching the input name.
-See
-.Xr hostname 7
-for the domain search procedure and the alias file format.
+.\"If the name contains no dot, and if the environment variable
+.\".Dq Ev HOSTALIASES
+.\"contains the name of an alias file, the alias file will first be searched
+.\"for an alias matching the input name.
+.\"See
+.\".Xr hostname 7
+.\"for the domain search procedure and the alias file format.
.Pp
The
.Fn gethostbyname2
.Dv AF_INET ,
for example
.Dv AF_INET6 .
-Both of these address families are supported in the Mac OS X implemention.
-.Pp
-The
-.Fn sethostent
-function
-may be used to request the use of a connected
-.Tn TCP
-socket for queries.
-If the
-.Fa stayopen
-flag is non-zero,
-this sets the option to send all queries to the name server using
-.Tn TCP
-and to retain the connection after each call to
-.Fn gethostbyname ,
-.Fn gethostbyname2
-or
-.Fn gethostbyaddr .
-Otherwise, queries are performed using
-.Tn UDP
-datagrams.
-.Pp
-The
-.Fn endhostent
-function
-closes the
-.Tn TCP
-connection.
.Pp
+.\"The
+.\".Fn sethostent
+.\"function
+.\"may be used to request the use of a connected
+.\".Tn TCP
+.\"socket for queries.
+.\"If the
+.\".Fa stayopen
+.\"flag is non-zero,
+.\"this sets the option to send all queries to the name server using
+.\".Tn TCP
+.\"and to retain the connection after each call to
+.\".Fn gethostbyname ,
+.\".Fn gethostbyname2
+.\"or
+.\".Fn gethostbyaddr .
+.\"Otherwise, queries are performed using
+.\".Tn UDP
+.\"datagrams.
+.\".Pp
+.\"The
+.\".Fn endhostent
+.\"function
+.\"closes the
+.\".Tn TCP
+.\"connection.
+.\".Pp
The
.Fn herror
function writes a message to the diagnostic output consisting of the
-string parameter
-.Fa s ,
+string argument
+.Fa string ,
the constant string
.Qq Li ":\ " ,
and a message corresponding to the value of
function returns a string which is the message text corresponding to the
value of the
.Fa err
-parameter.
+argument.
+.Pp
+Historically, passing a host's own hostname to
+.Fn gethostbyname
+or
+.Fn gethostbyname2
+has been a popular
+technique for determining that host's IP address(es), but this is fragile,
+and doesn't work reliably in all cases. The appropriate way for software to
+discover the IP address(es) of the host it is running on is to use
+.Xr getifaddrs 3 .
+.Pp
.Sh FILES
-.Bl -tag -width /etc/resolv.conf -compact
+.Bl -tag -width /etc/nsswitch.conf -compact
.It Pa /etc/hosts
-.It Pa /etc/host.conf
+.\".It Pa /etc/nsswitch.conf
.It Pa /etc/resolv.conf
.El
+.Sh EXAMPLES
+Print out the hostname associated with a specific IP address:
+.Bd -literal -offset indent
+const char *ipstr = "127.0.0.1";
+struct in_addr ip;
+struct hostent *hp;
+
+if (!inet_aton(ipstr, &ip))
+ errx(1, "can't parse IP address %s", ipstr);
+
+if ((hp = gethostbyaddr((const void *)&ip,
+ sizeof ip, AF_INET)) == NULL)
+ errx(1, "no name associated with %s", ipstr);
+
+printf("name associated with %s is %s\en", ipstr, hp->h_name);
+.Ed
.Sh DIAGNOSTICS
Error return status from
.Fn gethostbyname ,
is indicated by return of a
.Dv NULL
pointer.
-The external integer
+The integer
.Va h_errno
may then be checked to see whether this is a temporary failure
or an invalid or unknown host.
will result in an answer;
for example, a mail-forwarder may be registered for this domain.
.El
-.Sh LEGACY SYNOPSIS
-.Fd #include <netdb.h>
-.Pp
-.Vt extern int h_errno ;
-.Pp
-.Ft struct hostent *
-.br
-.Fo gethostbyaddr
-.Fa "const void *addr"
-.Fa "socklen_t len"
-.Fa "int type"
-.Fc ;
-.Pp
-The type of
-.Fa addr
-has changed slightly.
.Sh SEE ALSO
.Xr getaddrinfo 3 ,
+.Xr getnameinfo 3 ,
+.Xr inet_aton 3 ,
.Xr resolver 3 ,
.Xr hosts 5 ,
.Xr hostname 7 ,
-.Xr named 8
+.Xr mDNSResponder 8
+.\".Xr named 8
.Sh CAVEAT
The
.Fn gethostent
and
.Fn endhostent
are redefined,
-when libc is built to use only the routines to lookup in
+when
+.Lb libc
+is built to use only the routines to lookup in
.Pa /etc/hosts
and not the name server.
.Pp
.Tn BIND
version 4.9.4.
.Sh BUGS
-These functions use static data storage;
+These functions use a thread-specific data storage;
if the data is needed for future use, it should be
copied before any subsequent calls overwrite it.
+.Pp
+Though these functions are thread-safe,
+still it is recommended to use the
+.Xr getaddrinfo 3
+family of functions, instead.
+.Pp
Only the Internet
address format is currently understood.
projects / apple / libinfo.git / blobdiff