aboutsummaryrefslogtreecommitdiffstats
path: root/lib/libc/net/gethostbyname.3
diff options
context:
space:
mode:
authorPeter Wemm <peter@FreeBSD.org>1996-11-01 06:29:00 +0000
committerPeter Wemm <peter@FreeBSD.org>1996-11-01 06:29:00 +0000
commitc293d821b3220de377d5bedc2d4452a7f0c1858f (patch)
tree58bbf766db3c172803a17c29ef522324ae3fcab6 /lib/libc/net/gethostbyname.3
parentdf9c30afec75a16c7cf5772dd4728ce3387e70f4 (diff)
downloadsrc-c293d821b3220de377d5bedc2d4452a7f0c1858f.tar.gz
src-c293d821b3220de377d5bedc2d4452a7f0c1858f.zip
Doc updates and cleanups made with the bind-4.9.4 update some time ago.
I thought I had committed these, but it seems not.
Notes
Notes: svn path=/head/; revision=19302
Diffstat (limited to 'lib/libc/net/gethostbyname.3')
-rw-r--r--lib/libc/net/gethostbyname.374
1 files changed, 63 insertions, 11 deletions
diff --git a/lib/libc/net/gethostbyname.3 b/lib/libc/net/gethostbyname.3
index 59cf30875735..af5e369eb496 100644
--- a/lib/libc/net/gethostbyname.3
+++ b/lib/libc/net/gethostbyname.3
@@ -29,18 +29,20 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" @(#)gethostbyname.3 8.2 (Berkeley) 4/19/94
+.\" @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
.\"
-.Dd April 19, 1994
+.Dd May 25, 1995
.Dt GETHOSTBYNAME 3
.Os BSD 4.2
.Sh NAME
.Nm gethostbyname ,
+.Nm gethostbyname2 ,
.Nm gethostbyaddr ,
.Nm gethostent ,
.Nm sethostent ,
.Nm endhostent ,
-.Nm herror
+.Nm herror ,
+.Nm hstrerror
.Nd get network host entry
.Sh SYNOPSIS
.Fd #include <netdb.h>
@@ -48,15 +50,20 @@
.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
.Fn sethostent "int stayopen"
.Fn endhostent void
.Fn herror "const char *string"
+.Ft const char *
+.Fn hstrerror "int err"
.Sh DESCRIPTION
The
-.Fn gethostbyname
+.Fn gethostbyname ,
+.Fn gethostbyname2
and
.Fn gethostbyaddr
functions
@@ -85,22 +92,25 @@ The members of this structure are:
.It Fa h_name
Official name of the host.
.It Fa h_aliases
-A zero terminated array of alternate names for the host.
+A NULL-terminated array of alternate names for the host.
.It Fa h_addrtype
-The type of address being returned; currently always
+The type of address being returned; usually
.Dv AF_INET .
.It Fa h_length
The length, in bytes, of the address.
.It Fa h_addr_list
-A zero terminated array of network addresses for the host.
+A NULL-terminated array of network addresses for the host.
Host addresses are returned in network byte order.
.It Fa h_addr
The first address in
.Fa h_addr_list ;
this is for backward compatibility.
+.El
.Pp
When using the nameserver,
.Fn gethostbyname
+and
+.Fn gethostbyname
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
@@ -112,6 +122,25 @@ See
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
+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
@@ -123,7 +152,8 @@ 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 gethostbyname ,
+.Fn gethostbyname2
or
.Fn gethostbyaddr .
Otherwise, queries are performed using
@@ -136,13 +166,31 @@ 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 ,
+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
+.Bl -tag -width /etc/resolv.conf -compact
.It Pa /etc/hosts
+.It Pa /etc/host.conf
+.It Pa /etc/resolv.conf
.El
.Sh DIAGNOSTICS
Error return status from
-.Fn gethostbyname
+.Fn gethostbyname ,
+.Fn gethostbyname2
and
.Fn gethostbyaddr
is indicated by return of a null pointer.
@@ -219,7 +267,8 @@ If the
.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
@@ -241,6 +290,9 @@ and
.Fn sethostent
functions appeared in
.Bx 4.2 .
+The
+.Fn gethostbyname2
+functrion first appeared in bind-4.9.4.
.Sh BUGS
These functions use static data storage;
if the data is needed for future use, it should be