diff options
Diffstat (limited to 'lib/lwres/man/lwres_getipnode.3')
| -rw-r--r-- | lib/lwres/man/lwres_getipnode.3 | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_getipnode.3 b/lib/lwres/man/lwres_getipnode.3 new file mode 100644 index 0000000..7bd1b5c --- /dev/null +++ b/lib/lwres/man/lwres_getipnode.3 @@ -0,0 +1,220 @@ +.\" Copyright (C) 2000, 2001, 2003-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_getipnode +.\" Author: +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 2007-06-18 +.\" Manual: BIND9 +.\" Source: ISC +.\" Language: English +.\" +.TH "LWRES_GETIPNODE" "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_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent \- lightweight resolver nodename / address translation API +.SH "SYNOPSIS" +.sp +.ft B +.nf +#include <lwres/netdb\&.h> +.fi +.ft +.HP \w'struct\ hostent\ *\ lwres_getipnodebyname('u +.BI "struct hostent * lwres_getipnodebyname(const\ char\ *" "name" ", int\ " "af" ", int\ " "flags" ", int\ *" "error_num" ");" +.HP \w'struct\ hostent\ *\ lwres_getipnodebyaddr('u +.BI "struct hostent * lwres_getipnodebyaddr(const\ void\ *" "src" ", size_t\ " "len" ", int\ " "af" ", int\ *" "error_num" ");" +.HP \w'void\ lwres_freehostent('u +.BI "void lwres_freehostent(struct\ hostent\ *" "he" ");" +.SH "DESCRIPTION" +.PP +These functions perform thread safe, protocol independent nodename\-to\-address and address\-to\-nodename translation as defined in RFC2553\&. +.PP +They use a +\fBstruct hostent\fR +which is 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 \- usually +\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 +\fBlwres_getipnodebyname()\fR +looks up addresses of protocol family +\fIaf\fR +for the hostname +\fIname\fR\&. The +\fIflags\fR +parameter contains ORed flag bits to specify the types of addresses that are searched for, and the types of addresses that are returned\&. The flag bits are: +.PP +\fBAI_V4MAPPED\fR +.RS 4 +This is used with an +\fIaf\fR +of AF_INET6, and causes IPv4 addresses to be returned as IPv4\-mapped IPv6 addresses\&. +.RE +.PP +\fBAI_ALL\fR +.RS 4 +This is used with an +\fIaf\fR +of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned\&. If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped IPv6 addresses\&. +.RE +.PP +\fBAI_ADDRCONFIG\fR +.RS 4 +Only return an IPv6 or IPv4 address if here is an active network interface of that type\&. This is not currently implemented in the BIND 9 lightweight resolver, and the flag is ignored\&. +.RE +.PP +\fBAI_DEFAULT\fR +.RS 4 +This default sets the +\fBAI_V4MAPPED\fR +and +\fBAI_ADDRCONFIG\fR +flag bits\&. +.RE +.PP +\fBlwres_getipnodebyaddr()\fR +performs a reverse lookup of address +\fIsrc\fR +which is +\fIlen\fR +bytes long\&. +\fIaf\fR +denotes the protocol family, typically +\fBPF_INET\fR +or +\fBPF_INET6\fR\&. +.PP +\fBlwres_freehostent()\fR +releases all the memory associated with the +\fBstruct hostent\fR +pointer +\fIhe\fR\&. Any memory allocated for the +\fBh_name\fR, +\fBh_addr_list\fR +and +\fBh_aliases\fR +is freed, as is the memory for the +\fBhostent\fR +structure itself\&. +.SH "RETURN VALUES" +.PP +If an error occurs, +\fBlwres_getipnodebyname()\fR +and +\fBlwres_getipnodebyaddr()\fR +set +\fI*error_num\fR +to an appropriate error code and the function returns a +\fBNULL\fR +pointer\&. The error codes and their meanings are defined in +<lwres/netdb\&.h>: +.PP +\fBHOST_NOT_FOUND\fR +.RS 4 +No such host is known\&. +.RE +.PP +\fBNO_ADDRESS\fR +.RS 4 +The server recognised the request and the name but no address is available\&. Another type of request to the name server for the domain might return an answer\&. +.RE +.PP +\fBTRY_AGAIN\fR +.RS 4 +A temporary and possibly transient error occurred, such as a failure of a server to respond\&. The request may succeed if retried\&. +.RE +.PP +\fBNO_RECOVERY\fR +.RS 4 +An unexpected failure occurred, and retrying the request is pointless\&. +.RE +.PP +\fBlwres_hstrerror\fR(3) +translates these error codes to suitable error messages\&. +.SH "SEE ALSO" +.PP +\fBRFC2553\fR(), +\fBlwres\fR(3), +\fBlwres_gethostent\fR(3), +\fBlwres_getaddrinfo\fR(3), +\fBlwres_getnameinfo\fR(3), +\fBlwres_hstrerror\fR(3)\&. +.SH "AUTHOR" +.PP +\fBInternet Systems Consortium, Inc\&.\fR +.SH "COPYRIGHT" +.br +Copyright \(co 2000, 2001, 2003-2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC") +.br |