diff options
Diffstat (limited to 'lib/lwres/man/lwres_gethostent.3')
| -rw-r--r-- | lib/lwres/man/lwres_gethostent.3 | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_gethostent.3 b/lib/lwres/man/lwres_gethostent.3 new file mode 100644 index 0000000..f88372a --- /dev/null +++ b/lib/lwres/man/lwres_gethostent.3 @@ -0,0 +1,329 @@ +.\" Copyright (C) 2001, 2004, 2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" This Source Code Form is subject to the terms of the Mozilla Public +.\" License, v. 2.0. If a copy of the MPL was not distributed with this +.\" file, You can obtain one at http://mozilla.org/MPL/2.0/. +.\" +.hy 0 +.ad l +'\" t +.\" Title: lwres_gethostent +.\" Author: +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 2007-06-18 +.\" Manual: BIND9 +.\" Source: ISC +.\" Language: English +.\" +.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> +.fi +.ft +.HP \w'struct\ hostent\ *\ lwres_gethostbyname('u +.BI "struct hostent * lwres_gethostbyname(const\ char\ *" "name" ");" +.HP \w'struct\ hostent\ *\ lwres_gethostbyname2('u +.BI "struct hostent * lwres_gethostbyname2(const\ char\ *" "name" ", int\ " "af" ");" +.HP \w'struct\ hostent\ *\ lwres_gethostbyaddr('u +.BI "struct hostent * lwres_gethostbyaddr(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ");" +.HP \w'struct\ hostent\ *\ lwres_gethostent('u +.BI "struct hostent * lwres_gethostent(void);" +.HP \w'void\ lwres_sethostent('u +.BI "void lwres_sethostent(int\ " "stayopen" ");" +.HP \w'void\ lwres_endhostent('u +.BI "void lwres_endhostent(void);" +.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 \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 \w'struct\ hostent\ *\ lwres_gethostent_r('u +.BI "struct hostent * lwres_gethostent_r(struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");" +.HP \w'void\ lwres_sethostent_r('u +.BI "void lwres_sethostent_r(int\ " "stayopen" ");" +.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 +\fBgethostent\fR(3) +functions provided by most operating systems\&. They use a +\fBstruct hostent\fR +which is usually defined in +<namedb\&.h>\&. +.PP +.if n \{\ +.RS 4 +.\} +.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 */ +.fi +.if n \{\ +.RE +.\} +.PP +The members of this structure are: +.PP +\fBh_name\fR +.RS 4 +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\&. +.RE +.PP +\fBh_addrtype\fR +.RS 4 +The type of address being returned \(em +\fBPF_INET\fR +or +\fBPF_INET6\fR\&. +.RE +.PP +\fBh_length\fR +.RS 4 +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\&. +.RE +.PP +For backward compatibility with very old software, +\fBh_addr\fR +is the first address in +\fBh_addr_list\&.\fR +.PP +\fBlwres_gethostent()\fR, +\fBlwres_sethostent()\fR, +\fBlwres_endhostent()\fR, +\fBlwres_gethostent_r()\fR, +\fBlwres_sethostent_r()\fR +and +\fBlwres_endhostent_r()\fR +provide iteration over the known host entries on systems that provide such functionality through facilities like +/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\&. +\fBlwres_gethostbyname()\fR +always looks for an IPv4 address while +\fBlwres_gethostbyname2()\fR +looks for an address of protocol family +\fIaf\fR: either +\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\&. +\fBNULL\fR +is returned if the lookups by +\fBlwres_gethostbyname()\fR +or +\fBlwres_gethostbyname2()\fR +fail\&. +.PP +Reverse lookups of addresses are performed by +\fBlwres_gethostbyaddr()\fR\&. +\fIaddr\fR +is an address of length +\fIlen\fR +bytes and protocol family +\fItype\fR +\(em +\fBPF_INET\fR +or +\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\&. +\fIresbuf\fR +is a pointer to a +\fBstruct hostent\fR +which is initialised by a successful call to +\fBlwres_gethostbyname_r()\fR\&. +\fIbuf\fR +is a buffer of length +\fIlen\fR +bytes which is used to store the +\fBh_name\fR, +\fBh_aliases\fR, and +\fBh_addr_list\fR +elements of the +\fBstruct hostent\fR +returned in +\fIresbuf\fR\&. Successful calls to +\fBlwres_gethostbyname_r()\fR +return +\fIresbuf\fR, which is a pointer to the +\fBstruct hostent\fR +it created\&. +.PP +\fBlwres_gethostbyaddr_r()\fR +is a thread\-safe function that performs a reverse lookup of address +\fIaddr\fR +which is +\fIlen\fR +bytes long and is of protocol family +\fItype\fR +\(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\&. +\fIresbuf\fR +is a pointer to a +\fBstruct hostent\fR +which is initialised by a successful call to +\fBlwres_gethostbyaddr_r()\fR\&. +\fIbuf\fR +is a buffer of length +\fIlen\fR +bytes which is used to store the +\fBh_name\fR, +\fBh_aliases\fR, and +\fBh_addr_list\fR +elements of the +\fBstruct hostent\fR +returned in +\fIresbuf\fR\&. Successful calls to +\fBlwres_gethostbyaddr_r()\fR +return +\fIresbuf\fR, which is a pointer to the +\fBstruct hostent()\fR +it created\&. +.SH "RETURN VALUES" +.PP +The functions +\fBlwres_gethostbyname()\fR, +\fBlwres_gethostbyname2()\fR, +\fBlwres_gethostbyaddr()\fR, and +\fBlwres_gethostent()\fR +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 +<lwres/netdb\&.h>: +.PP +\fBHOST_NOT_FOUND\fR +.RS 4 +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\&. +.RE +.PP +\fBNO_RECOVERY\fR +.RS 4 +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\&. +.RE +.PP +\fBlwres_hstrerror\fR(3) +translates these error codes to suitable error messages\&. +.PP +\fBlwres_gethostent()\fR +and +\fBlwres_gethostent_r()\fR +always return +\fBNULL\fR\&. +.PP +Successful calls to +\fBlwres_gethostbyname_r()\fR +and +\fBlwres_gethostbyaddr_r()\fR +return +\fIresbuf\fR, a pointer to the +\fBstruct hostent\fR +that was initialised by these functions\&. They return +\fBNULL\fR +if the lookups fail or if +\fIbuf\fR +was too small to hold the list of addresses and names referenced by the +\fBh_name\fR, +\fBh_aliases\fR, and +\fBh_addr_list\fR +elements of the +\fBstruct hostent\fR\&. If +\fIbuf\fR +was too small, both +\fBlwres_gethostbyname_r()\fR +and +\fBlwres_gethostbyaddr_r()\fR +set the global variable +\fBerrno\fR +to +\fBERANGE\fR\&. +.SH "SEE ALSO" +.PP +\fBgethostent\fR(3), +\fBlwres_getipnode\fR(3), +\fBlwres_hstrerror\fR(3) +.SH "BUGS" +.PP +\fBlwres_gethostbyname()\fR, +\fBlwres_gethostbyname2()\fR, +\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 +\fBlwres_gethostbyname_r()\fR, and +\fBlwres_gethostbyaddr_r()\fR +respectively\&. +.PP +The resolver daemon does not currently support any non\-DNS name services such as +/etc/hosts +or +\fBNIS\fR, consequently the above functions don\*(Aqt, either\&. +.SH "AUTHOR" +.PP +\fBInternet Systems Consortium, Inc\&.\fR +.SH "COPYRIGHT" +.br +Copyright \(co 2001, 2004, 2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC") +.br |