diff options
Diffstat (limited to 'lib/lwres/man/lwres_gethostent.3')
| -rw-r--r-- | lib/lwres/man/lwres_gethostent.3 | 153 |
1 files changed, 89 insertions, 64 deletions
diff --git a/lib/lwres/man/lwres_gethostent.3 b/lib/lwres/man/lwres_gethostent.3 index e53aa33c17556..36e249431fae2 100644 --- a/lib/lwres/man/lwres_gethostent.3 +++ b/lib/lwres/man/lwres_gethostent.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and/or distribute this software for any @@ -13,60 +13,80 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id$ -.\" .hy 0 .ad l +'\" t .\" Title: lwres_gethostent .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> -.\" Date: June 18, 2007 +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 2007-06-18 .\" Manual: BIND9 -.\" Source: BIND9 +.\" Source: ISC +.\" Language: English .\" -.TH "LWRES_GETHOSTENT" "3" "June 18, 2007" "BIND9" "BIND9" +.TH "LWRES_GETHOSTENT" "3" "2007\-06\-18" "ISC" "BIND9" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- .SH "NAME" lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r \- lightweight resolver get network host entry .SH "SYNOPSIS" +.sp +.ft B .nf -#include <lwres/netdb.h> +#include <lwres/netdb\&.h> .fi -.HP 37 +.ft +.HP \w'struct\ hostent\ *\ lwres_gethostbyname('u .BI "struct hostent * lwres_gethostbyname(const\ char\ *" "name" ");" -.HP 38 +.HP \w'struct\ hostent\ *\ lwres_gethostbyname2('u .BI "struct hostent * lwres_gethostbyname2(const\ char\ *" "name" ", int\ " "af" ");" -.HP 37 +.HP \w'struct\ hostent\ *\ lwres_gethostbyaddr('u .BI "struct hostent * lwres_gethostbyaddr(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ");" -.HP 34 +.HP \w'struct\ hostent\ *\ lwres_gethostent('u .BI "struct hostent * lwres_gethostent(void);" -.HP 22 +.HP \w'void\ lwres_sethostent('u .BI "void lwres_sethostent(int\ " "stayopen" ");" -.HP 22 +.HP \w'void\ lwres_endhostent('u .BI "void lwres_endhostent(void);" -.HP 39 +.HP \w'struct\ hostent\ *\ lwres_gethostbyname_r('u .BI "struct hostent * lwres_gethostbyname_r(const\ char\ *" "name" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");" -.HP 39 +.HP \w'struct\ hostent\ *\ lwres_gethostbyaddr_r('u .BI "struct hostent * lwres_gethostbyaddr_r(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");" -.HP 36 +.HP \w'struct\ hostent\ *\ lwres_gethostent_r('u .BI "struct hostent * lwres_gethostent_r(struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");" -.HP 24 +.HP \w'void\ lwres_sethostent_r('u .BI "void lwres_sethostent_r(int\ " "stayopen" ");" -.HP 24 +.HP \w'void\ lwres_endhostent_r('u .BI "void lwres_endhostent_r(void);" .SH "DESCRIPTION" .PP -These functions provide hostname\-to\-address and address\-to\-hostname lookups by means of the lightweight resolver. They are similar to the standard +These functions provide hostname\-to\-address and address\-to\-hostname lookups by means of the lightweight resolver\&. They are similar to the standard \fBgethostent\fR(3) -functions provided by most operating systems. They use a +functions provided by most operating systems\&. They use a \fBstruct hostent\fR which is usually defined in -\fI<namedb.h>\fR. +<namedb\&.h>\&. .PP +.if n \{\ .RS 4 +.\} .nf struct hostent { char *h_name; /* official name of host */ @@ -77,19 +97,20 @@ struct hostent { }; #define h_addr h_addr_list[0] /* address, for backward compatibility */ .fi +.if n \{\ .RE -.sp +.\} .PP The members of this structure are: .PP \fBh_name\fR .RS 4 -The official (canonical) name of the host. +The official (canonical) name of the host\&. .RE .PP \fBh_aliases\fR .RS 4 -A NULL\-terminated array of alternate names (nicknames) for the host. +A NULL\-terminated array of alternate names (nicknames) for the host\&. .RE .PP \fBh_addrtype\fR @@ -97,25 +118,25 @@ A NULL\-terminated array of alternate names (nicknames) for the host. The type of address being returned \(em \fBPF_INET\fR or -\fBPF_INET6\fR. +\fBPF_INET6\fR\&. .RE .PP \fBh_length\fR .RS 4 -The length of the address in bytes. +The length of the address in bytes\&. .RE .PP \fBh_addr_list\fR .RS 4 A \fBNULL\fR -terminated array of network addresses for the host. Host addresses are returned in network byte order. +terminated array of network addresses for the host\&. Host addresses are returned in network byte order\&. .RE .PP For backward compatibility with very old software, \fBh_addr\fR is the first address in -\fBh_addr_list.\fR +\fBh_addr_list\&.\fR .PP \fBlwres_gethostent()\fR, \fBlwres_sethostent()\fR, @@ -125,14 +146,14 @@ is the first address in and \fBlwres_endhostent_r()\fR provide iteration over the known host entries on systems that provide such functionality through facilities like -\fI/etc/hosts\fR -or NIS. The lightweight resolver does not currently implement these functions; it only provides them as stub functions that always return failure. +/etc/hosts +or NIS\&. The lightweight resolver does not currently implement these functions; it only provides them as stub functions that always return failure\&. .PP \fBlwres_gethostbyname()\fR and \fBlwres_gethostbyname2()\fR look up the hostname -\fIname\fR. +\fIname\fR\&. \fBlwres_gethostbyname()\fR always looks for an IPv4 address while \fBlwres_gethostbyname2()\fR @@ -141,17 +162,17 @@ looks for an address of protocol family \fBPF_INET\fR or \fBPF_INET6\fR -\(em IPv4 or IPV6 addresses respectively. Successful calls of the functions return a -\fBstruct hostent\fRfor the name that was looked up. +\(em IPv4 or IPV6 addresses respectively\&. Successful calls of the functions return a +\fBstruct hostent\fRfor the name that was looked up\&. \fBNULL\fR is returned if the lookups by \fBlwres_gethostbyname()\fR or \fBlwres_gethostbyname2()\fR -fail. +fail\&. .PP Reverse lookups of addresses are performed by -\fBlwres_gethostbyaddr()\fR. +\fBlwres_gethostbyaddr()\fR\&. \fIaddr\fR is an address of length \fIlen\fR @@ -160,15 +181,15 @@ bytes and protocol family \(em \fBPF_INET\fR or -\fBPF_INET6\fR. +\fBPF_INET6\fR\&. \fBlwres_gethostbyname_r()\fR -is a thread\-safe function for forward lookups. If an error occurs, an error code is returned in -\fI*error\fR. +is a thread\-safe function for forward lookups\&. If an error occurs, an error code is returned in +\fI*error\fR\&. \fIresbuf\fR is a pointer to a \fBstruct hostent\fR which is initialised by a successful call to -\fBlwres_gethostbyname_r()\fR. +\fBlwres_gethostbyname_r()\fR\&. \fIbuf\fR is a buffer of length \fIlen\fR @@ -179,12 +200,12 @@ bytes which is used to store the elements of the \fBstruct hostent\fR returned in -\fIresbuf\fR. Successful calls to +\fIresbuf\fR\&. Successful calls to \fBlwres_gethostbyname_r()\fR return \fIresbuf\fR, which is a pointer to the \fBstruct hostent\fR -it created. +it created\&. .PP \fBlwres_gethostbyaddr_r()\fR is a thread\-safe function that performs a reverse lookup of address @@ -196,14 +217,14 @@ bytes long and is of protocol family \(em \fBPF_INET\fR or -\fBPF_INET6\fR. If an error occurs, the error code is returned in -\fI*error\fR. The other function parameters are identical to those in -\fBlwres_gethostbyname_r()\fR. +\fBPF_INET6\fR\&. If an error occurs, the error code is returned in +\fI*error\fR\&. The other function parameters are identical to those in +\fBlwres_gethostbyname_r()\fR\&. \fIresbuf\fR is a pointer to a \fBstruct hostent\fR which is initialised by a successful call to -\fBlwres_gethostbyaddr_r()\fR. +\fBlwres_gethostbyaddr_r()\fR\&. \fIbuf\fR is a buffer of length \fIlen\fR @@ -214,12 +235,12 @@ bytes which is used to store the elements of the \fBstruct hostent\fR returned in -\fIresbuf\fR. Successful calls to +\fIresbuf\fR\&. Successful calls to \fBlwres_gethostbyaddr_r()\fR return \fIresbuf\fR, which is a pointer to the \fBstruct hostent()\fR -it created. +it created\&. .SH "RETURN VALUES" .PP The functions @@ -227,39 +248,39 @@ The functions \fBlwres_gethostbyname2()\fR, \fBlwres_gethostbyaddr()\fR, and \fBlwres_gethostent()\fR -return NULL to indicate an error. In this case the global variable +return NULL to indicate an error\&. In this case the global variable \fBlwres_h_errno\fR will contain one of the following error codes defined in -\fI<lwres/netdb.h>\fR: +<lwres/netdb\&.h>: .PP \fBHOST_NOT_FOUND\fR .RS 4 -The host or address was not found. +The host or address was not found\&. .RE .PP \fBTRY_AGAIN\fR .RS 4 -A recoverable error occurred, e.g., a timeout. Retrying the lookup may succeed. +A recoverable error occurred, e\&.g\&., a timeout\&. Retrying the lookup may succeed\&. .RE .PP \fBNO_RECOVERY\fR .RS 4 -A non\-recoverable error occurred. +A non\-recoverable error occurred\&. .RE .PP \fBNO_DATA\fR .RS 4 -The name exists, but has no address information associated with it (or vice versa in the case of a reverse lookup). The code NO_ADDRESS is accepted as a synonym for NO_DATA for backwards compatibility. +The name exists, but has no address information associated with it (or vice versa in the case of a reverse lookup)\&. The code NO_ADDRESS is accepted as a synonym for NO_DATA for backwards compatibility\&. .RE .PP \fBlwres_hstrerror\fR(3) -translates these error codes to suitable error messages. +translates these error codes to suitable error messages\&. .PP \fBlwres_gethostent()\fR and \fBlwres_gethostent_r()\fR always return -\fBNULL\fR. +\fBNULL\fR\&. .PP Successful calls to \fBlwres_gethostbyname_r()\fR @@ -268,7 +289,7 @@ and return \fIresbuf\fR, a pointer to the \fBstruct hostent\fR -that was initialised by these functions. They return +that was initialised by these functions\&. They return \fBNULL\fR if the lookups fail or if \fIbuf\fR @@ -277,7 +298,7 @@ was too small to hold the list of addresses and names referenced by the \fBh_aliases\fR, and \fBh_addr_list\fR elements of the -\fBstruct hostent\fR. If +\fBstruct hostent\fR\&. If \fIbuf\fR was too small, both \fBlwres_gethostbyname_r()\fR @@ -286,7 +307,7 @@ and set the global variable \fBerrno\fR to -\fBERANGE\fR. +\fBERANGE\fR\&. .SH "SEE ALSO" .PP \fBgethostent\fR(3), @@ -299,17 +320,21 @@ to \fBlwres_gethostbyaddr()\fR and \fBlwres_endhostent()\fR -are not thread safe; they return pointers to static data and provide error codes through a global variable. Thread\-safe versions for name and address lookup are provided by +are not thread safe; they return pointers to static data and provide error codes through a global variable\&. Thread\-safe versions for name and address lookup are provided by \fBlwres_gethostbyname_r()\fR, and \fBlwres_gethostbyaddr_r()\fR -respectively. +respectively\&. .PP The resolver daemon does not currently support any non\-DNS name services such as -\fI/etc/hosts\fR +/etc/hosts or -\fBNIS\fR, consequently the above functions don't, either. +\fBNIS\fR, consequently the above functions don\*(Aqt, either\&. +.SH "AUTHOR" +.PP +\fBInternet Systems Consortium, Inc\&.\fR .SH "COPYRIGHT" -Copyright \(co 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC") .br Copyright \(co 2001 Internet Software Consortium. .br |