diff options
Diffstat (limited to 'static/netbsd/man3/inet.3')
| -rw-r--r-- | static/netbsd/man3/inet.3 | 410 |
1 files changed, 410 insertions, 0 deletions
diff --git a/static/netbsd/man3/inet.3 b/static/netbsd/man3/inet.3 new file mode 100644 index 00000000..506dd098 --- /dev/null +++ b/static/netbsd/man3/inet.3 @@ -0,0 +1,410 @@ +.\" $NetBSD: inet.3,v 1.7 2023/01/18 23:16:05 riastradh Exp $ +.\" +.\" Copyright (c) 1983, 1990, 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. 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. +.\" +.\" @(#)inet.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd July 25, 2012 +.Dt INET 3 +.Os +.Sh NAME +.Nm inet_addr , +.Nm inet_aton , +.Nm inet_lnaof , +.Nm inet_makeaddr , +.Nm inet_netof , +.Nm inet_network , +.Nm inet_ntoa , +.Nm inet_ntop , +.Nm inet_pton , +.Nm addr , +.Nm ntoa , +.Nm network +.Nd Internet address manipulation routines +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In arpa/inet.h +.Ft in_addr_t +.Fn inet_addr "const char *cp" +.Ft int +.Fn inet_aton "const char *cp" "struct in_addr *addr" +.Ft in_addr_t +.Fn inet_lnaof "struct in_addr in" +.Ft struct in_addr +.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna" +.Ft in_addr_t +.Fn inet_netof "struct in_addr in" +.Ft in_addr_t +.Fn inet_network "const char *cp" +.Ft char * +.Fn inet_ntoa "struct in_addr in" +.Ft const char * +.Fn inet_ntop "int af" "const void * restrict src" "char * restrict dst" "socklen_t size" +.Ft int +.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst" +.Sh DESCRIPTION +The routines +.Fn inet_aton , +.Fn inet_addr +and +.Fn inet_network +interpret character strings representing +numbers expressed in the Internet standard +.Qq dotted quad +notation. +.Pp +The +.Fn inet_pton +function converts a presentation format address (that is, printable form +as held in a character string) to network format (usually a +.Ft struct in_addr +or some other internal binary representation, in network byte order). +It returns 1 if the address was valid for the specified address family, or +0 if the address wasn't parsable in the specified address family, or -1 +if some system error occurred (in which case +.Va errno +will have been set). +This function is presently valid for +.Dv AF_INET +and +.Dv AF_INET6 . +.Pp +The +.Fn inet_aton +routine interprets the specified character string as an Internet address, +placing the address into the structure provided. +It returns 1 if the string was successfully interpreted, +or 0 if the string is invalid. +.Pp +The +.Fn inet_addr +and +.Fn inet_network +functions return numbers suitable for use +as Internet addresses and Internet network +numbers, respectively. +.Pp +The function +.Fn inet_ntop +converts an address from network format (usually a +.Ft struct in_addr +or some other binary form, in network byte order) to presentation format +(suitable for external display purposes). +It returns NULL if a system error occurs (in which case, +.Va errno +will have been set), or it returns a pointer to the destination string. +The +.Fa size +parameter is the size of the +.Fa dst +buffer. +For +.Dv AF_INET , +this must have space for +.Dv INET_ADDRSTRLEN Pq 16 +bytes; for +.Dv AF_INET6 , +this must have space for +.Dv INET6_ADDRSTRLEN Pq 46 +bytes. +.Pp +The routine +.Fn inet_ntoa +takes an Internet address and returns an +.Tn ASCII +string representing the address in +.Qq dotted quad +notation. +.Pp +The routine +.Fn inet_makeaddr +takes an Internet network number and a local network address (both in +host order) and constructs an Internet address from it. +Note that to convert only a single value to a +.Ft struct in_addr +form that value should be passed as the first parameter and +.Ql 0L +should be given for the second parameter. +.Pp +The routines +.Fn inet_netof +and +.Fn inet_lnaof +break apart Internet host addresses, returning the network number and +local network address part, respectively (both in host order). +.Pp +All Internet addresses are returned in network +order (bytes ordered from left to right). +All network numbers and local address parts are +returned as machine format integer values. +.Sh INTERNET ADDRESSES (IP VERSION 4) +Values specified using the +.Qq dotted quad +notation take one +of the following forms: +.Bd -literal -offset indent +a.b.c.d +a.b.c +a.b +a +.Ed +.Pp +When four parts are specified, each is interpreted +as a byte of data and assigned, from left to right, +to the four bytes of an Internet address. +Note that when an Internet address is viewed as a 32-bit +integer quantity on a system that uses little-endian +byte order (e.g. +.Tn Intel i386, i486 +and +.Tn Pentium +processors) the bytes referred to above appear as +.Dq Li d.c.b.a . +That is, little-endian bytes are ordered from right to left. +.Pp +When a three part address is specified, the last +part is interpreted as a 16-bit quantity and placed +in the right-most two bytes of the network address. +This makes the three part address format convenient +for specifying Class B network addresses as +.Dq Li 128.net.host . +.Pp +When a two part address is supplied, the last part +is interpreted as a 24-bit quantity and placed in +the right most three bytes of the network address. +This makes the two part address format convenient +for specifying Class A network addresses as +.Dq Li net.host . +.Pp +When only one part is given, the value is stored +directly in the network address without any byte +rearrangement. +.Pp +All numbers supplied as +.Dq parts +in a +.Qq dotted quad +notation +may be decimal, octal, or hexadecimal, as specified +in the C language (i.e., a leading 0x or 0X implies +hexadecimal; otherwise, a leading 0 implies octal; +otherwise, the number is interpreted as decimal). +.Sh INTERNET ADDRESSES (IP VERSION 6) +In order to support scoped IPv6 addresses, +the use of +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 +is recommended rather than the functions presented here. +.Pp +The presentation format of an IPv6 address is given in RFC 2373: +.Pp +There are three conventional forms for representing IPv6 addresses as +text strings: +.Bl -enum +.It +The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the +hexadecimal values of the eight 16-bit pieces of the address. +Examples: +.Bd -literal -offset indent +FEDC:BA98:7654:3210:FEDC:BA98:7654:3210 +1080:0:0:0:8:800:200C:417A +.Ed +.Pp +Note that it is not necessary to write the leading zeros in an +individual field, but there must be at least one numeral in +every field (except for the case described in 2). +.It +Due to the method of allocating certain styles of IPv6 +addresses, it will be common for addresses to contain long +strings of zero bits. +In order to make writing addresses +containing zero bits easier, a special syntax is available to +compress the zeros. +The use of ``::'' indicates multiple groups of 16-bits of zeros. +The ``::'' can only appear once in an address. +The ``::'' can also be used to compress the leading +and/or trailing zeros in an address. +.Pp +For example the following addresses: +.Bd -literal -offset indent +1080:0:0:0:8:800:200C:417A a unicast address +FF01:0:0:0:0:0:0:43 a multicast address +0:0:0:0:0:0:0:1 the loopback address +0:0:0:0:0:0:0:0 the unspecified addresses +.Ed +.Pp +may be represented as: +.Bd -literal -offset indent +1080::8:800:200C:417A a unicast address +FF01::43 a multicast address +::1 the loopback address +:: the unspecified addresses +.Ed +.It +An alternative form that is sometimes more convenient when +dealing with a mixed environment of IPv4 and IPv6 nodes is +x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values +of the six high-order 16-bit pieces of the address, and the 'd's +are the decimal values of the four low-order 8-bit pieces of the +address (standard IPv4 representation). +Examples: +.Bd -literal -offset indent +0:0:0:0:0:0:13.1.68.3 +0:0:0:0:0:FFFF:129.144.52.38 +.Ed +.Pp +or in compressed form: +.Bd -literal -offset indent +::13.1.68.3 +::FFFF:129.144.52.38 +.Ed +.El +.Sh RETURN VALUES +The constant +.Dv INADDR_NONE +is returned by +.Fn inet_addr +and +.Fn inet_network +for malformed requests. +.Sh ERRORS +The +.Fn inet_ntop +and +.Fn inet_pton +functions may fail with +.Bl -tag -width Er +.It Bq Er EAFNOSUPPORT +The value of +.Fa af +was not +.Dv AF_INET +or +.Dv AF_INET6 . +.El +.Pp +The +.Fn inet_ntop +function may fail with +.Bl -tag -width Er +.It Bq Er ENOSPC +The +.Fa size +indicated for +.Fa dst +was too small to store the presentation form of the network address. +.El +.Sh SEE ALSO +.Xr byteorder 3 , +.Xr gethostbyname 3 , +.Xr getnetent 3 , +.Xr inet_net 3 , +.Xr hosts 5 , +.Xr networks 5 +.Rs +.%R RFC 2373 +.%D July 1998 +.%T "IP Version 6 Addressing Architecture" +.Re +.Rs +.%R RFC 3493 +.%D February 2003 +.%T "Basic Socket Interface Extensions for IPv6" +.Re +.Sh STANDARDS +The +.Fn inet_ntop +and +.Fn inet_pton +functions conform to +.St -p1003.1-2001 . +Note that +.Fn inet_pton +does not accept 1-, 2-, or 3-part dotted addresses; all four parts +must be specified. +Additionally all four parts of a dotted address must be decimal. +This is a narrower input set than that accepted by +.Fn inet_aton . +.Sh HISTORY +The +.Fn inet_addr , +.Fn inet_network , +.Fn inet_makeaddr , +.Fn inet_lnaof +and +.Fn inet_netof +functions appeared in +.Bx 4.2 . +They were changed to use +.Vt in_addr_t +in place of +.Vt unsigned long +in +.Nx 2.0 . +The +.Fn inet_aton +and +.Fn inet_ntoa +functions appeared in +.Bx 4.3 . +The +.Fn inet_pton +and +.Fn inet_ntop +functions appeared in BIND 4.9.4 and thence +.Nx 1.3 ; +they were also in +.St -xns5.2 . +.Sh BUGS +The value +.Dv INADDR_NONE +(0xffffffff) is a valid broadcast address, but +.Fn inet_addr +cannot return that value without indicating failure. +The newer +.Fn inet_aton +function does not share this problem. +.Pp +The problem of host byte ordering versus network byte ordering is +confusing. +.Pp +The string returned by +.Fn inet_ntoa +resides in a static memory area. +.Pp +The function +.Fn inet_addr +should return a +.Vt struct in_addr . +.Pp +The function +.Fn inet_network +does not support byte rearrangement for one, two, and three +part addresses. |