[src/trunk]: src/lib/libc/net document gethostbyname2().

[itojun <itojun%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/91d90dc71655
branches:  trunk
changeset: 474206:91d90dc71655
user:      itojun <itojun%NetBSD.org@localhost>
date:      Thu Jul 01 18:18:27 1999 +0000

description:
document gethostbyname2().

diffstat:

 lib/libc/net/gethostbyname.3 |  68 ++++++++++++++++++++++++++++++++++++-------
 1 files changed, 57 insertions(+), 11 deletions(-)

diffs (158 lines):

diff -r b1658b96349b -r 91d90dc71655 lib/libc/net/gethostbyname.3
--- a/lib/libc/net/gethostbyname.3      Thu Jul 01 18:15:41 1999 +0000
+++ b/lib/libc/net/gethostbyname.3      Thu Jul 01 18:18:27 1999 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: gethostbyname.3,v 1.15 1999/03/22 19:44:50 garbled Exp $
+.\"    $NetBSD: gethostbyname.3,v 1.16 1999/07/01 18:18:27 itojun Exp $
 .\"
 .\" Copyright (c) 1983, 1987, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -38,6 +38,7 @@
 .Os
 .Sh NAME
 .Nm gethostbyname ,
+.Nm gethostbyname2 ,
 .Nm gethostbyaddr ,
 .Nm gethostent ,
 .Nm sethostent ,
@@ -53,6 +54,8 @@
 .Ft struct hostent *
 .Fn gethostbyname "const char *name"
 .Ft struct hostent *
+.Fn gethostbyname2 "const char *name" "int af"
+.Ft struct hostent *
 .Fn gethostbyaddr "const char *addr" "int len" "int type"
 .Ft struct hostent *
 .Fn gethostent void
@@ -66,7 +69,8 @@
 .Fn hstrerror "int err"
 .Sh DESCRIPTION
 The
-.Fn gethostbyname
+.Fn gethostbyname ,
+.Fn gethostbyname2
 and
 .Fn gethostbyaddr
 functions
@@ -117,6 +121,8 @@
 .Pp
 When using the nameserver,
 .Fn gethostbyname
+and
+.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
@@ -128,6 +134,27 @@
 for the domain search procedure and the alias file format.
 .Pp
 The
+.Fn gethostbyname2
+function is an evolution of
+.Fn gethostbyname
+which is intended to allow lookups in address families other than
+.Dv AF_INET ,
+for example
+.Dv AF_INET6 .
+Currently the
+.Fa af
+argument must be specified as
+.Dv AF_INET
+or
+.Dv AF_INET6 ,
+else the fuction will return
+.Dv NULL
+after having set
+.Va h_errno
+to
+.Dv NETDB_INTERNAL
+.Pp
+The
 .Fn sethostent
 function
 may be used to request the use of a connected
@@ -139,7 +166,8 @@
 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 gethostbyname ,
+.Fn gethostbyname2
 or
 .Fn gethostbyaddr .
 Otherwise, queries are performed using
@@ -152,13 +180,29 @@
 closes the
 .Tn TCP
 connection.
+.Pp
+The
+.Fn herror
+function writes a message to the diagnostic output consisting of the
+string parameter
+.Fa s ,
+the constant string ": ", and a message corresponding to the value of
+.Va h_errno .
+.Pp
+The
+.Fn hstrerror
+function returns a string which is the message text corresponding to the
+value of the
+.Fa err
+parameter.
 .Sh FILES
 .Bl -tag -width /etc/hosts -compact
 .It Pa /etc/hosts
 .El
 .Sh DIAGNOSTICS
 Error return status from
-.Fn gethostbyname
+.Fn gethostbyname ,
+.Fn gethostbyname2
 and
 .Fn gethostbyaddr
 is indicated by return of a null pointer.
@@ -175,10 +219,6 @@
 .Pf non Dv -NULL ,
 it is printed, followed by a colon and a space.
 The error message is printed with a trailing newline.
-The routine
-.Fn hstrerror
-returns a pointer to the message string affiliated with an error number.
-The array pointed to is not to be modified by the program.
 .Pp
 The variable
 .Va h_errno
@@ -216,8 +256,9 @@
 .Fn sethostent
 and
 .Fn endhostent
-are redefined, when
-.Pa libc.a
+are redefined,
+when
+.Xr libc 3
 is built to use only the routines to lookup in
 .Pa /etc/hosts
 and not the name server.
@@ -238,7 +279,8 @@
 .Fa stayopen
 argument is non-zero,
 the file will not be closed after each call to
-.Fn gethostbyname
+.Fn gethostbyname ,
+.Fn gethostbyname2
 or
 .Fn gethostbyaddr .
 .Pp
@@ -260,6 +302,10 @@
 .Fn sethostent
 functions appeared in
 .Bx 4.2 .
+The
+.Fn gethostbyname2
+function first appeared in bind-4.9.4.
+IPv6 support was implemented in WIDE Hydrangea IPv6 protocol stack kit.
 .Sh BUGS
 These functions use static data storage;
 if the data is needed for future use, it should be