From 997358a6c475c8886cce388ab325184a1ff733c9 Mon Sep 17 00:00:00 2001 From: Martin Willi Date: Fri, 28 Apr 2006 07:14:48 +0000 Subject: - import of strongswan-2.7.0 - applied patch for charon --- lib/liblwres/man/lwres_gethostent.3 | 270 ++++++++++++++++++++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 lib/liblwres/man/lwres_gethostent.3 (limited to 'lib/liblwres/man/lwres_gethostent.3') diff --git a/lib/liblwres/man/lwres_gethostent.3 b/lib/liblwres/man/lwres_gethostent.3 new file mode 100644 index 000000000..44811ef4d --- /dev/null +++ b/lib/liblwres/man/lwres_gethostent.3 @@ -0,0 +1,270 @@ +.\" +.\" Copyright (C) 2000, 2001 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.TH "LWRES_GETHOSTENT" "3" "Jun 30, 2000" "BIND9" "" +.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 +\fB#include +.sp +.na +struct hostent * +lwres_gethostbyname(const char *name); +.ad +.sp +.na +struct hostent * +lwres_gethostbyname2(const char *name, int af); +.ad +.sp +.na +struct hostent * +lwres_gethostbyaddr(const char *addr, int len, int type); +.ad +.sp +.na +struct hostent * +lwres_gethostent(void); +.ad +.sp +.na +void +lwres_sethostent(int stayopen); +.ad +.sp +.na +void +lwres_endhostent(void); +.ad +.sp +.na +struct hostent * +lwres_gethostbyname_r(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error); +.ad +.sp +.na +struct hostent * +lwres_gethostbyaddr_r(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, int *error); +.ad +.sp +.na +struct hostent * +lwres_gethostent_r(struct hostent *resbuf, char *buf, int buflen, int *error); +.ad +.sp +.na +void +lwres_sethostent_r(int stayopen); +.ad +.sp +.na +void +lwres_endhostent_r(void); +.ad +\fR.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 +\fI\fR. +.sp +.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 */ +.sp +.fi +.PP +The members of this structure are: +.TP +\fBh_name\fR +The official (canonical) name of the host. +.TP +\fBh_aliases\fR +A NULL-terminated array of alternate names (nicknames) for the host. +.TP +\fBh_addrtype\fR +The type of address being returned \(em +\fBPF_INET\fR +or +\fBPF_INET6\fR. +.TP +\fBh_length\fR +The length of the address in bytes. +.TP +\fBh_addr_list\fR +A \fBNULL\fR +terminated array of network addresses for the host. +Host addresses are returned in network byte order. +.PP +For backward compatibility with very old software, +h_addr +is the first address in +h_addr_list. +.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 +\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. +.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 +h_name, h_aliases, and +h_addr_list 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 +h_name, h_aliases, and +h_addr_list 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 +\fI\fR: +.TP +\fBHOST_NOT_FOUND\fR +The host or address was not found. +.TP +\fBTRY_AGAIN\fR +A recoverable error occurred, e.g., a timeout. +Retrying the lookup may succeed. +.TP +\fBNO_RECOVERY\fR +A non-recoverable error occurred. +.TP +\fBNO_DATA\fR +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. +.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 h_name, h_aliases, and +h_addr_list 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 ERANGE. +.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 +\fI/etc/hosts\fR +or +\fBNIS\fR, +consequently the above functions don't, either. -- cgit v1.2.3