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, 0 insertions, 461 deletions
diff --git a/newlib/libc/sys/linux/net/getipnodebyname.3 b/newlib/libc/sys/linux/net/getipnodebyname.3 deleted file mode 100644 index 5b8ea1ecb..000000000 --- a/newlib/libc/sys/linux/net/getipnodebyname.3 +++ /dev/null @@ -1,461 +0,0 @@ -.\" $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. |