diff options
Diffstat (limited to 'newlib/libc/sys/linux/net/getipnodebyname.3')
| -rw-r--r-- | newlib/libc/sys/linux/net/getipnodebyname.3 | 461 |
1 files changed, 461 insertions, 0 deletions
diff --git a/newlib/libc/sys/linux/net/getipnodebyname.3 b/newlib/libc/sys/linux/net/getipnodebyname.3 new file mode 100644 index 000000000..5b8ea1ecb --- /dev/null +++ b/newlib/libc/sys/linux/net/getipnodebyname.3 @@ -0,0 +1,461 @@ +.\" $FreeBSD: src/lib/libc/net/getipnodebyname.3,v 1.8 2001/10/01 16:08:55 ru Exp $ +.\" $KAME: getipnodebyname.3,v 1.6 2000/08/09 21:16:17 itojun Exp $ +.\" +.\" Copyright (c) 1983, 1987, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 +.\" +.Dd May 25, 1995 +.Dt GETIPNODEBYNAME 3 +.Os +.\" +.Sh NAME +.Nm getipnodebyname , +.Nm getipnodebyaddr , +.Nm freehostent +.Nd nodename-to-address and address-to-nodename translation +.\" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netdb.h +.Ft "struct hostent *" +.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error_num" +.Ft "struct hostent *" +.Fn getipnodebyaddr "const void *src" "size_t len" "int af" "int *error_num" +.Ft void +.Fn freehostent "struct hostent *ptr" +.\" +.Sh DESCRIPTION +.Fn getipnodebyname +and +.Fn getipnodebyaddr +functions are very similar to +.Xr gethostbyname 3 , +.Xr gethostbyname2 3 +and +.Xr gethostbyaddr 3 . +The functions cover all the functionalities provided by the older ones, +and provide better interface to programmers. +The functions require additional arguments, +.Ar af , +and +.Ar flags , +for specifying address family and operation mode. +The additional arguments allow programmer to get address for a nodename, +for specific address family +(such as +.Dv AF_INET +or +.Dv AF_INET6 ) . +The functions also require an additional pointer argument, +.Ar error_num +to return the appropriate error code, +to support thread safe error code returns. +.Pp +The type and usage of the return value, +.Li "struct hostent" +is described in +.Xr gethostbyname 3 . +.Pp +For +.Fn getipnodebyname , +the +.Ar name +argument can be either a node name or a numeric address +string +(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). +The +.Ar af +argument specifies the address family, either +.Dv AF_INET +or +.Dv AF_INET6 . +The +.Ar flags +argument specifies the types of addresses that are searched for, +and the types of addresses that are returned. +We note that a special flags value of +.Dv AI_DEFAULT +(defined below) +should handle most applications. +That is, porting simple applications to use IPv6 replaces the call +.Bd -literal -offset + hptr = gethostbyname(name); +.Ed +.Pp +with +.Bd -literal -offset + hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num); +.Ed +.Pp +Applications desiring finer control over the types of addresses +searched for and returned, can specify other combinations of the +.Ar flags +argument. +.Pp +A +.Ar flags +of +.Li 0 +implies a strict interpretation of the +.Ar af +argument: +.Bl -bullet +.It +If +.Ar flags +is 0 and +.Ar af +is +.Dv AF_INET , +then the caller wants only IPv4 addresses. +A query is made for +.Li A +records. +If successful, the IPv4 addresses are returned and the +.Li h_length +member of the +.Li hostent +structure will be 4, else the function returns a +.Dv NULL +pointer. +.It +If +.Ar flags +is 0 and if +.Ar af +is +.Li AF_INET6 , +then the caller wants only IPv6 addresses. +A query is made for +.Li AAAA +records. +If successful, the IPv6 addresses are returned and the +.Li h_length +member of the +.Li hostent +structure will be 16, else the function returns a +.Dv NULL +pointer. +.El +.Pp +Other constants can be logically-ORed into the +.Ar flags +argument, to modify the behavior of the function. +.Bl -bullet +.It +If the +.Dv AI_V4MAPPED +flag is specified along with an +.Ar af +of +.Dv AF_INET6 , +then the caller will accept IPv4-mapped IPv6 addresses. +That is, if no +.Li AAAA +records are found then a query is made for +.Li A +records and any found are returned as IPv4-mapped IPv6 addresses +.Li ( h_length +will be 16). +The +.Dv AI_V4MAPPED +flag is ignored unless +.Ar af +equals +.Dv AF_INET6 . +.It +The +.Dv AI_V4MAPPED_CFG +flag is exact same as the +.Dv AI_V4MAPPED +flag only if the kernel supports IPv4-mapped IPv6 address. +.It +If the +.Dv AI_ALL +flag is used in conjunction with the +.Dv AI_V4MAPPED +flag, and only used with the IPv6 address family. +When +.Dv AI_ALL +is logically or'd with +.Dv AI_V4MAPPED +flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6. +A query is first made for +.Li AAAA +records and if successful, the +IPv6 addresses are returned. Another query is then made for +.Li A +records and any found are returned as IPv4-mapped IPv6 addresses. +.Li h_length +will be 16. Only if both queries fail does the function +return a +.Dv NULL +pointer. This flag is ignored unless af equals +AF_INET6. If both +.Dv AI_ALL +and +.Dv AI_V4MAPPED +are specified, +.Dv AI_ALL +takes precedence. +.It +The +.Dv AI_ADDRCONFIG +flag specifies that a query for +.Li AAAA +records +should occur only if the node has at least one IPv6 source +address configured and a query for +.Li A +records should occur only if the node has at least one IPv4 source address +configured. +.Pp +For example, if the node has no IPv6 source addresses configured, +and +.Ar af +equals AF_INET6, and the node name being looked up has both +.Li AAAA +and +.Li A +records, then: +(a) if only +.Dv AI_ADDRCONFIG +is +specified, the function returns a +.Dv NULL +pointer; +(b) if +.Dv AI_ADDRCONFIG +| +.Dv AI_V4MAPPED +is specified, the +.Li A +records are returned as IPv4-mapped IPv6 addresses; +.El +.Pp +The special flags value of +.Dv AI_DEFAULT +is defined as +.Bd -literal -offset + #define AI_DEFAULT (AI_V4MAPPED_CFG | AI_ADDRCONFIG) +.Ed +.Pp +We noted that the +.Fn getipnodebyname +function must allow the +.Ar name +argument to be either a node name or a literal address string +(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). +This saves applications from having to call +.Xr inet_pton 3 +to handle literal address strings. +When the +.Ar name +argument is a literal address string, +the +.Ar flags +argument is always ignored. +.Pp +There are four scenarios based on the type of literal address string +and the value of the +.Ar af +argument. +The two simple cases are when +.Ar name +is a dotted-decimal IPv4 address and +.Ar af +equals +.Dv AF_INET , +or when +.Ar name +is an IPv6 hex address and +.Ar af +equals +.Dv AF_INET6 . +The members of the +returned hostent structure are: +.Li h_name +points to a copy of the +.Ar name +argument, +.Li h_aliases +is a +.Dv NULL +pointer, +.Li h_addrtype +is a copy of the +.Ar af +argument, +.Li h_length +is either 4 +(for +.Dv AF_INET ) +or 16 +(for +.Dv AF_INET6 ) , +.Li h_addr_list[0] +is a pointer to the 4-byte or 16-byte binary address, +and +.Li h_addr_list[1] +is a +.Dv NULL +pointer. +.Pp +When +.Ar name +is a dotted-decimal IPv4 address and +.Ar af +equals +.Dv AF_INET6 , +and +.Dv AI_V4MAPPED +is specified, +an IPv4-mapped IPv6 address is returned: +.Li h_name +points to an IPv6 hex address containing the IPv4-mapped IPv6 address, +.Li h_aliases +is a +.Dv NULL +pointer, +.Li h_addrtype +is +.Dv AF_INET6 , +.Li h_length +is 16, +.Li h_addr_list[0] +is a pointer to the 16-byte binary address, and +.Li h_addr_list[1] +is a +.Dv NULL +pointer. +.Pp +It is an error when +.Ar name +is an IPv6 hex address and +.Ar af +equals +.Dv AF_INET . +The function's return value is a +.Dv NULL +pointer and the value pointed to by +.Ar error_num +equals +.Dv HOST_NOT_FOUND . +.Pp +.Fn getipnodebyaddr +takes almost the same argument as +.Xr gethostbyaddr 3 , +but adds a pointer to return an error number. +Additionally it takes care of IPv4-mapped IPv6 addresses, +and IPv4-compatible IPv6 addresses. +.Pp +.Fn getipnodebyname +and +.Fn getipnodebyaddr +dynamically allocate the structure to be returned to the caller. +.Fn freehostent +reclaims memory region allocated and returned by +.Fn getipnodebyname +or +.Fn getipnodebyaddr . +.\" +.Sh FILES +.Bl -tag -width /etc/nsswitch.conf -compact +.It Pa /etc/hosts +.It Pa /etc/nsswitch.conf +.It Pa /etc/resolv.conf +.El +.\" +.Sh DIAGNOSTICS +.Fn getipnodebyname +and +.Fn getipnodebyaddr +returns +.Dv NULL +on errors. +The integer values pointed to by +.Ar error_num +may then be checked to see whether this is a temporary failure +or an invalid or unknown host. +The meanings of each error code are described in +.Xr gethostbyname 3 . +.\" +.Sh SEE ALSO +.Xr gethostbyaddr 3 , +.Xr gethostbyname 3 , +.Xr hosts 5 , +.Xr nsswitch.conf 5 , +.Xr services 5 , +.Xr hostname 7 , +.Xr named 8 +.Pp +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A W. Stevens +.%T Basic Socket Interface Extensions for IPv6 +.%R RFC2553 +.%D March 1999 +.Re +.\" +.Sh HISTORY +The implementation first appeared in KAME advanced networking kit. +.\" +.Sh STANDARDS +.Fn getipnodebyname +and +.Fn getipnodebyaddr +are documented in +.Dq Basic Socket Interface Extensions for IPv6 +(RFC2553). +.\" +.Sh BUGS +.Fn getipnodebyname +and +.Fn getipnodebyaddr +do not handle scoped IPv6 address properly. +If you use these functions, +your program will not be able to handle scoped IPv6 addresses. +For IPv6 address manipulation, +.Fn getaddrinfo 3 +and +.Fn getnameinfo 3 +are recommended. +.Pp +The current implementation is not thread-safe. +.Pp +The text was shamelessly copied from RFC2553. |