date and time created 91/04/12 13:40:31 by bostic

[unix-history] / usr / src / lib / libc / net / gethostbyname.3

diff --git a/usr/src/lib/libc/net/gethostbyname.3 b/usr/src/lib/libc/net/gethostbyname.3
index 533ffe3..aefdf29 100644 (file)
--- a/usr/src/lib/libc/net/gethostbyname.3
+++ b/usr/src/lib/libc/net/gethostbyname.3
@@ -1,13 +1,14 @@
-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1983, 1987 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)gethostbyname.3     6.6 (Berkeley) %G%
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.TH GETHOSTBYNAME 3N ""
+.\"    @(#)gethostbyname.3     6.12 (Berkeley) %G%
+.\"
+.TH GETHOSTBYNAME 3 ""

 .UC 5
 .SH NAME
 .UC 5
 .SH NAME

-gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent \- get network host entry
+gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry

 .SH SYNOPSIS
 .B "#include <netdb.h>
 .PP
 .SH SYNOPSIS
 .B "#include <netdb.h>
 .PP


@@ -29,12 +30,17 @@ gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent \- get network
 .PP
 .B "endhostent()
 .PP
 .PP
 .B "endhostent()
 .PP

+.B "herror(string)
+.br
+.B "char *string;
+.PP

 .SH DESCRIPTION
 .I Gethostbyname
 and
 .I gethostbyaddr
 each return a pointer to an object with the
 .SH DESCRIPTION
 .I Gethostbyname
 and
 .I gethostbyaddr
 each return a pointer to an object with the

-following structure.
+following structure describing an internet host
+referenced by name or by address, respectively.

 This structure contains either the information obtained from the name server,
 .IR named (8),
 or broken-out fields from a line in 
 This structure contains either the information obtained from the name server,
 .IR named (8),
 or broken-out fields from a line in 


@@ -78,8 +84,19 @@ Host addresses are returned in network byte order.
 h_addr
 The first address in h_addr_list; this is for backward compatiblity.
 .PP
 h_addr
 The first address in h_addr_list; this is for backward compatiblity.
 .PP

+When using the nameserver,
+.I 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 ``HOSTALAIASES''
+contains the name of an alias file, the alias file will first be searched
+for an alias matching the input name.
+See
+.IR hostname (7)
+for the domain search procedure and the alias file format.
+.PP

 .I Sethostent
 .I Sethostent

-allows a request for the use of a connected socket using TCP for queries.
+may be used to request the use of a connected TCP socket for queries.

 If the
 .I stayopen
 flag is non-zero,
 If the
 .I stayopen
 flag is non-zero,


@@ -88,6 +105,7 @@ and to retain the connection after each call to
 .I gethostbyname
 or
 .IR gethostbyaddr .
 .I gethostbyname
 or
 .IR gethostbyaddr .

+Otherwise, queries are performed using UDP datagrams.

 .PP
 .I Endhostent
 closes the TCP connection.
 .PP
 .I Endhostent
 closes the TCP connection.


@@ -102,6 +120,13 @@ The external integer
 .IR h_errno
 may then be checked to see whether this is a temporary failure
 or an invalid or unknown host.
 .IR h_errno
 may then be checked to see whether this is a temporary failure
 or an invalid or unknown host.

+The routine
+.I herror
+can be used to print an error message describing the failure.
+If its argument
+.I string
+is non-NULL, it is printed, followed by a colon and a space.
+The error message is printed with a trailing newline.

 .PP
 .IR h_errno
 can have the following values:
 .PP
 .IR h_errno
 can have the following values:


@@ -114,17 +139,21 @@ and means that the local server did not receive
 a response from an authoritative server.
 A retry at some later time may succeed.
 .IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n
 a response from an authoritative server.
 A retry at some later time may succeed.
 .IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n

+Some unexpected server failure was encountered.

 This is a non-recoverable error.
 This is a non-recoverable error.

-.IP NO_ADDRESS \w'HOST_NOT_FOUND'u+2n
+.IP NO_DATA \w'HOST_NOT_FOUND'u+2n

 The requested name is valid but does not have an IP address; 
 this is not a temporary error.  
 The requested name is valid but does not have an IP address; 
 this is not a temporary error.  

-This means another type
-of request to the name server will result in an answer.
+This means that the name is known to the name server but there is no address
+associated with this name.
+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.

 .RE
 .SH FILES
 /etc/hosts
 .SH "SEE ALSO"
 .RE
 .SH FILES
 /etc/hosts
 .SH "SEE ALSO"

-hosts(5), resolver(3), named(8)
+resolver(3), hosts(5), hostname(7), named(8)

 .SH CAVEAT
 .PP
 .I Gethostent
 .SH CAVEAT
 .PP
 .I Gethostent