Libinfo-517.30.1.tar.gz

[apple/libinfo.git] / gen.subproj / gethostbyname.3

diff --git a/gen.subproj/gethostbyname.3 b/gen.subproj/gethostbyname.3
index 1789cb51e006e535a1b4ec104763a481a8b44507..d791b3693d92dbe47d49f2b6190dce65e08047ce 100644 (file)
--- a/gen.subproj/gethostbyname.3
+++ b/gen.subproj/gethostbyname.3
@@ -9,10 +9,6 @@
 .\" 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.
 .\" 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.
 .\" 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.


@@ -30,62 +26,56 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     From: @(#)gethostbyname.3      8.4 (Berkeley) 5/25/95
 .\" 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
 .Dt GETHOSTBYNAME 3
 .Os
 .Sh NAME

-.Nm endhostent ,
-.Nm gethostbyaddr ,

 .Nm gethostbyname ,
 .Nm gethostbyname2 ,
 .Nm gethostbyname ,
 .Nm gethostbyname2 ,

+.Nm gethostbyaddr ,

 .Nm gethostent ,
 .Nm gethostent ,

+.Nm sethostent ,
+.Nm endhostent ,

 .Nm herror ,
 .Nm herror ,

-.Nm hstrerror ,
-.Nm sethostent
+.Nm hstrerror

 .Nd get network host entry
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .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 *
 .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 *
 .Ft struct hostent *

-.Fo gethostbyname
-.Fa "const char *name"
-.Fc
+.Fn gethostbyname2 "const char *name" "int af"

 .Ft struct hostent *
 .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 *
 .Ft struct hostent *

-.Fo gethostent
-.Fa void
-.Fc
+.Fn gethostent void

 .Ft 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
 .Ft void

-.Fo sethostent
-.Fa "int stayopen"
-.Fc
+.Fn herror "const char *string"
+.Ft const char *
+.Fn hstrerror "int err"

 .Sh DESCRIPTION
 .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
 The
 .Fn gethostbyname ,
 .Fn gethostbyname2


@@ -95,12 +85,50 @@ functions
 each return a pointer to an object with the
 following structure describing an internet host
 referenced by name or by address, respectively.
 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 .
 .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 */
 .Bd -literal
 struct hostent {
        char    *h_name;        /* official name of host */


@@ -142,13 +170,13 @@ and
 .Fn gethostbyname2
 will search for the named host in the current domain and its parents
 unless the name ends in a dot.
 .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
 .Pp
 The
 .Fn gethostbyname2


@@ -158,40 +186,39 @@ which is intended to allow lookups in address families other than
 .Dv AF_INET ,
 for example
 .Dv AF_INET6 .
 .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
 .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
 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
 the constant string
 .Qq Li ":\ " ,
 and a message corresponding to the value of


@@ -202,13 +229,40 @@ The
 function returns a string which is the message text corresponding to the
 value of the
 .Fa err
 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
 .Sh FILES

-.Bl -tag -width /etc/resolv.conf -compact
+.Bl -tag -width /etc/nsswitch.conf -compact

 .It Pa /etc/hosts
 .It Pa /etc/hosts

-.It Pa /etc/host.conf
+.\".It Pa /etc/nsswitch.conf

 .It Pa /etc/resolv.conf
 .El
 .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 ,
 .Sh DIAGNOSTICS
 Error return status from
 .Fn gethostbyname ,


@@ -218,7 +272,7 @@ and
 is indicated by return of a
 .Dv NULL
 pointer.
 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.
 .Va h_errno
 may then be checked to see whether this is a temporary failure
 or an invalid or unknown host.


@@ -255,28 +309,15 @@ Another type of request to the name server using this domain name
 will result in an answer;
 for example, a mail-forwarder may be registered for this domain.
 .El
 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 ,
 .Sh SEE ALSO
 .Xr getaddrinfo 3 ,

+.Xr getnameinfo 3 ,
+.Xr inet_aton 3 ,

 .Xr resolver 3 ,
 .Xr hosts 5 ,
 .Xr hostname 7 ,
 .Xr resolver 3 ,
 .Xr hosts 5 ,
 .Xr hostname 7 ,

-.Xr named 8
+.Xr mDNSResponder 8
+.\".Xr named 8

 .Sh CAVEAT
 The
 .Fn gethostent
 .Sh CAVEAT
 The
 .Fn gethostent


@@ -286,7 +327,9 @@ is defined, and
 and
 .Fn endhostent
 are redefined,
 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
 .Pa /etc/hosts
 and not the name server.
 .Pp


@@ -335,8 +378,14 @@ function first appeared in
 .Tn BIND
 version 4.9.4.
 .Sh BUGS
 .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.
 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.
 Only the Internet
 address format is currently understood.