aboutsummaryrefslogtreecommitdiffstats
path: root/lib/libc/net/gethostbyname.3
diff options
context:
space:
mode:
authorPeter Wemm <peter@FreeBSD.org>1996-08-29 22:13:00 +0000
committerPeter Wemm <peter@FreeBSD.org>1996-08-29 22:13:00 +0000
commitfdf4c7af0417c1a22e9d0d8eadaf456c54e3834f (patch)
treeefd22ab091f05c17f90dcbb1401a1b87835f7277 /lib/libc/net/gethostbyname.3
parentd72ca8598d573f3b39b17bb3dfde6d481643e080 (diff)
downloadsrc-fdf4c7af0417c1a22e9d0d8eadaf456c54e3834f.tar.gz
src-fdf4c7af0417c1a22e9d0d8eadaf456c54e3834f.zip
The last commit failed part-way through, re-add the generated
resolver man pages.
Notes
Notes: svn path=/head/; revision=17917
Diffstat (limited to 'lib/libc/net/gethostbyname.3')
-rw-r--r--lib/libc/net/gethostbyname.3226
1 files changed, 226 insertions, 0 deletions
diff --git a/lib/libc/net/gethostbyname.3 b/lib/libc/net/gethostbyname.3
new file mode 100644
index 000000000000..e1d5050b1da3
--- /dev/null
+++ b/lib/libc/net/gethostbyname.3
@@ -0,0 +1,226 @@
+.\" Copyright (c) 1983, 1987 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms are permitted provided
+.\" that: (1) source distributions retain this entire copyright notice and
+.\" comment, and (2) distributions including binaries display the following
+.\" acknowledgement: ``This product includes software developed by the
+.\" University of California, Berkeley and its contributors'' in the
+.\" documentation or other materials provided with the distribution and in
+.\" all advertising materials mentioning features or use of this software.
+.\" 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.
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
+.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" @(#)gethostbyname.3 6.12 (Berkeley) 6/23/90
+.\"
+.TH GETHOSTBYNAME 3 "June 23, 1990"
+.UC 5
+.SH NAME
+gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry
+.SH SYNOPSIS
+.B "#include <netdb.h>
+.PP
+.B "extern int h_errno;
+.PP
+.B "struct hostent *gethostbyname(name)
+.br
+.B "char *name;
+.PP
+.B "struct hostent *gethostbyname2(name, af)
+.br
+.B "char *name; int af;
+.PP
+.B "struct hostent *gethostbyaddr(addr, len, type)
+.br
+.B "char *addr; int len, type;
+.PP
+.B "struct hostent *gethostent()
+.PP
+.B "sethostent(stayopen)
+.br
+.B "int stayopen;
+.PP
+.B "endhostent()
+.PP
+.B "herror(string)
+.br
+.B "char *string;
+.PP
+.SH DESCRIPTION
+.IR Gethostbyname ,
+.IR gethostbyname2 ,
+and
+.I gethostbyaddr
+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,
+.IR named (8),
+or broken-out fields from a line in
+.IR /etc/hosts .
+If the local name server is not running these routines do a lookup in
+.IR /etc/hosts .
+.RS
+.PP
+.nf
+struct hostent {
+ char *h_name; /* official name of host */
+ char **h_aliases; /* alias list */
+ int h_addrtype; /* host address type */
+ int h_length; /* length of address */
+ char **h_addr_list; /* list of addresses from name server */
+};
+#define h_addr h_addr_list[0] /* address, for backward compatibility */
+.ft R
+.ad
+.fi
+.RE
+.PP
+The members of this structure are:
+.TP \w'h_addr_list'u+2n
+h_name
+Official name of the host.
+.TP \w'h_addr_list'u+2n
+h_aliases
+A zero terminated array of alternate names for the host.
+.TP \w'h_addr_list'u+2n
+h_addrtype
+The type of address being returned; usually AF_INET.
+.TP \w'h_addr_list'u+2n
+h_length
+The length, in bytes, of the address.
+.TP \w'h_addr_list'u+2n
+h_addr_list
+A zero terminated array of network addresses for the host.
+Host addresses are returned in network byte order.
+.TP \w'h_addr_list'u+2n
+h_addr
+The first address in h_addr_list; this is for backward compatibility.
+.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 Gethostbyname2
+is an evolution of
+.I gethostbyname
+intended to allow lookups in address families other than AF_INET, for example
+AF_INET6. Currently the
+.I af
+argument must be specified as
+.I AF_INET
+else the function will return \s-2NULL\s+2 after having set
+.I h_errno
+to \s-2NETDB_INTERNAL\s+2.
+.PP
+.I Sethostent
+may be used to request the use of a connected TCP socket for queries.
+If the
+.I stayopen
+flag is non-zero,
+this sets the option to send all queries to the name server using TCP
+and to retain the connection after each call to
+.I gethostbyname
+or
+.IR gethostbyaddr .
+Otherwise, queries are performed using UDP datagrams.
+.PP
+.I Endhostent
+closes the TCP connection.
+.SH DIAGNOSTICS
+.PP
+Error return status from
+.I gethostbyname
+and
+.I gethostbyaddr
+is indicated by return of a null pointer.
+The external integer
+.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:
+.RS
+.IP NETDB_INTERNAL \w'HOST_NOT_FOUND'u+2n
+This indicates an internal error in the library, unrelated to the network
+or name service.
+.I errno
+will be valid in this case; see
+.IR perror (3).
+.IP HOST_NOT_FOUND \w'HOST_NOT_FOUND'u+2n
+No such host is known.
+.IP TRY_AGAIN \w'HOST_NOT_FOUND'u+2n
+This is usually a temporary error
+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
+Some unexpected server failure was encountered.
+This is a non-recoverable error.
+.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.
+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"
+resolver(3), hosts(5), hostname(7), named(8)
+.SH CAVEAT
+.PP
+.I Gethostent
+is defined, and
+.I sethostent
+and
+.I endhostent
+are redefined,
+when
+.IR libc
+is built to use only the routines to lookup in
+.IR /etc/hosts
+and not the name server.
+.PP
+.I Gethostent
+reads the next line of
+.IR /etc/hosts ,
+opening the file if necessary.
+.PP
+.I Sethostent
+is redefined to open and rewind the file. If the
+.I stayopen
+argument is non-zero,
+the hosts data base will not be closed after each call to
+.I gethostbyname
+or
+.IR gethostbyaddr .
+.I Endhostent
+is redefined to close the file.
+.SH BUGS
+All information
+is contained in a static area
+so it must be copied if it is
+to be saved. Only the Internet
+address format is currently understood.