From 040cde4c2a229a54547aa80565c66e99b0ad0ccf Mon Sep 17 00:00:00 2001 From: Philip Guenther Date: Sat, 19 Apr 2014 11:18:02 +0000 Subject: Split inet(3) into three pages by decade: 1980s -> inet_lnaof(3), 1990s -> inet_addr(3), 2000s and beyond -> inet_ntop(3). ok tedu@ (who also noted the timeline) deraadt@ jmc@ --- lib/libc/net/Makefile.inc | 15 +- lib/libc/net/inet.3 | 355 ---------------------------------------------- lib/libc/net/inet_addr.3 | 197 +++++++++++++++++++++++++ lib/libc/net/inet_lnaof.3 | 90 ++++++++++++ lib/libc/net/inet_ntop.3 | 204 ++++++++++++++++++++++++++ 5 files changed, 499 insertions(+), 362 deletions(-) delete mode 100644 lib/libc/net/inet.3 create mode 100644 lib/libc/net/inet_addr.3 create mode 100644 lib/libc/net/inet_lnaof.3 create mode 100644 lib/libc/net/inet_ntop.3 (limited to 'lib/libc/net') diff --git a/lib/libc/net/Makefile.inc b/lib/libc/net/Makefile.inc index f4153bbfb4e..a619fe4ed94 100644 --- a/lib/libc/net/Makefile.inc +++ b/lib/libc/net/Makefile.inc @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.inc,v 1.51 2014/04/07 17:57:56 schwarze Exp $ +# $OpenBSD: Makefile.inc,v 1.52 2014/04/19 11:18:01 guenther Exp $ # net sources .PATH: ${LIBCSRCDIR}/arch/${MACHINE_CPU}/net ${LIBCSRCDIR}/net @@ -27,8 +27,9 @@ SRCS+= ip6opt.c rthdr.c vars6.c MAN+= byteorder.3 ethers.3 gai_strerror.3 getaddrinfo.3 gethostbyname.3 \ getifaddrs.3 getnameinfo.3 getnetent.3 getpeereid.3 getprotoent.3 \ - getrrsetbyname.3 getservent.3 if_indextoname.3 inet.3 \ - inet_net.3 inet6_option_space.3 inet6_rthdr_space.3 \ + getrrsetbyname.3 getservent.3 if_indextoname.3 \ + inet_addr.3 inet_lnaof.3 inet_net.3 inet_ntop.3 \ + inet6_option_space.3 inet6_rthdr_space.3 \ inet6_opt_init.3 inet6_rth_space.3 link_addr.3 \ rcmd.3 rcmdsh.3 resolver.3 @@ -61,10 +62,10 @@ MLINKS+=getservent.3 endservent.3 getservent.3 getservbyname.3 \ getservent.3 endservent_r.3 MLINKS+= if_indextoname.3 if_nametoindex.3 if_indextoname.3 if_nameindex.3 \ if_indextoname.3 if_freenameindex.3 -MLINKS+=inet.3 inet_addr.3 inet.3 inet_aton.3 \ - inet.3 inet_lnaof.3 inet.3 inet_makeaddr.3 inet.3 inet_netof.3 \ - inet.3 inet_network.3 inet.3 inet_ntoa.3 \ - inet.3 inet_ntop.3 inet.3 inet_pton.3 +MLINKS+=inet_addr.3 inet_aton.3 inet_addr.3 inet_network.3 \ + inet_addr.3 inet_ntoa.3 \ +MLINKS+=inet_lnaof.3 inet_makeaddr.3 inet_lnaof.3 inet_netof.3 +MLINKS+=inet_ntop.3 inet_pton.3 MLINKS+=inet_net.3 inet_net_ntop.3 inet_net.3 inet_net_pton.3 MLINKS+=link_addr.3 link_ntoa.3 MLINKS+=rcmd.3 iruserok.3 rcmd.3 rresvport.3 rcmd.3 ruserok.3 \ diff --git a/lib/libc/net/inet.3 b/lib/libc/net/inet.3 deleted file mode 100644 index e56ca0a59a5..00000000000 --- a/lib/libc/net/inet.3 +++ /dev/null @@ -1,355 +0,0 @@ -.\" $OpenBSD: inet.3,v 1.26 2013/06/05 03:39:23 tedu Exp $ -.\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem 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 $Mdocdate: June 5 2013 $ -.Dt INET 3 -.Os -.Sh NAME -.Nm inet_aton , -.Nm inet_addr , -.Nm inet_network , -.Nm inet_pton , -.Nm inet_ntop , -.Nm inet_ntoa , -.Nm inet_makeaddr , -.Nm inet_netof , -.Nm inet_lnaof -.Nd Internet address manipulation routines -.Sh SYNOPSIS -.In sys/types.h -.In sys/socket.h -.In netinet/in.h -.In arpa/inet.h -.Ft int -.Fn inet_aton "const char *cp" "struct in_addr *addr" -.Ft in_addr_t -.Fn inet_addr "const char *cp" -.Ft in_addr_t -.Fn inet_network "const char *cp" -.Ft int -.Fn inet_pton "int af" "const char *src" "void *dst" -.Ft const char * -.Fn inet_ntop "int af" "const void *src" "char *dst" "socklen_t size" -.Ft char * -.Fn inet_ntoa "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_lnaof "struct in_addr in" -.Sh DESCRIPTION -The routines -.Fn inet_aton , -.Fn inet_addr , -and -.Fn inet_network -interpret character strings representing -numbers expressed in the Internet standard -.Dq dot -notation. -.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 was invalid. -.Pp -The -.Fn inet_addr -and -.Fn inet_network -functions return numbers suitable for use -as Internet addresses and Internet network -numbers, respectively. -Both functions return the constant -.Dv INADDR_NONE -if the specified character string is malformed. -.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 -.Li 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; -0 if the address wasn't parseable 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 function -.Fn inet_ntop -converts an address from network format (usually a -.Li struct in_addr -or some other binary form, in network byte order) to presentation format -(suitable for external display purposes). -It returns -.Dv NULL -if a system -error occurs (in which case, -.Va errno -will have been set), or it returns a pointer to the destination string. -.Pp -The routine -.Fn inet_ntoa -takes an Internet address and returns an -ASCII string representing the address in dot notation. -.Pp -The routine -.Fn inet_makeaddr -takes an Internet network number and a local -network address and constructs an Internet address -from it. -.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. -.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 dot 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 -(such as the Intel 386, 486 and 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 rightmost 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 rightmost 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 dot notation -may be decimal, octal, or hexadecimal, as specified -in the C language (i.e., a leading 0x or 0X implies -hexadecimal; 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, -.Xr getaddrinfo 3 -and -.Xr getnameinfo 3 -are recommended rather than the functions presented here. -.Pp -The presentation format of an IPv6 address is given in RFC 4291: -.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 -.Dq \&:\&: -indicates multiple groups -of 16 bits of zeros. -The -.Dq \&:\&: -can only appear once in an -address. -The -.Dq \&:\&: -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 SEE ALSO -.Xr byteorder 3 , -.Xr gethostbyname 3 , -.Xr getnetent 3 , -.Xr inet_net 3 , -.Xr hosts 5 , -.Xr networks 5 -.Sh STANDARDS -The -.Nm inet_ntop -and -.Nm inet_pton -functions conform to the IETF IPv6 BSD API and address formatting -specifications. -Note that -.Nm inet_pton -does not accept 1-, 2-, or 3-part dotted addresses; all four parts -must be specified. -This is a narrower input set than that accepted by -.Nm inet_aton . -.Pp -.Rs -.%A R. Gilligan -.%A S. Thomson -.%A J. Bound -.%A J. McCann -.%A W. Stevens -.%D February 2003 -.%R RFC 3493 -.%T Basic Socket Interface Extensions for IPv6 -.Re -.Pp -.Rs -.%A R. Hinden -.%A S. Deering -.%D February 2006 -.%R RFC 4291 -.%T IP Version 6 Addressing Architecture -.Re -.Sh HISTORY -The -.Nm inet_addr , -.Nm inet_network , -.Nm inet_makeaddr , -.Nm inet_lnaof , -and -.Nm inet_netof -functions appeared in -.Bx 4.2 . -The -.Nm inet_aton -and -.Nm inet_ntoa -functions appeared in -.Bx 4.3 . -The -.Nm inet_pton -and -.Nm inet_ntop -functions appeared in BIND 4.9.4. -.Sh BUGS -The value -.Dv INADDR_NONE -(0xffffffff) is a valid broadcast address, but -.Fn inet_addr -cannot return that value without indicating failure. -Also, -.Fn inet_addr -should have been designed to return a -.Li struct in_addr . -The newer -.Fn inet_aton -function does not share these problems, and almost all existing code -should be modified to use -.Fn inet_aton -instead. -.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. diff --git a/lib/libc/net/inet_addr.3 b/lib/libc/net/inet_addr.3 new file mode 100644 index 00000000000..abe9e5d8c9f --- /dev/null +++ b/lib/libc/net/inet_addr.3 @@ -0,0 +1,197 @@ +.\" $OpenBSD: inet_addr.3,v 1.1 2014/04/19 11:18:01 guenther Exp $ +.\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem 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 $Mdocdate: April 19 2014 $ +.Dt INET_ADDR 3 +.Os +.Sh NAME +.Nm inet_aton , +.Nm inet_addr , +.Nm inet_network , +.Nm inet_ntoa +.Nd Internet Protocol version 4 (IPv4) address manipulation routines +.Sh SYNOPSIS +.In arpa/inet.h +.Ft int +.Fn inet_aton "const char *cp" "struct in_addr *addr" +.Ft in_addr_t +.Fn inet_addr "const char *cp" +.Ft in_addr_t +.Fn inet_network "const char *cp" +.Ft char * +.Fn inet_ntoa "struct in_addr in" +.Sh DESCRIPTION +The functions presented here only support IPv4 addresses. +In order to support IPv6 addresses as well, +.Xr inet_ntop 3 +and +.Xr inet_pton 3 +should be used rather than the functions presented here. +Scoped IPv6 addresses are supported via +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 . +.Pp +The routines +.Fn inet_aton , +.Fn inet_addr , +and +.Fn inet_network +interpret character strings representing +numbers expressed in the Internet standard +.Dq dot +notation. +.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 was invalid. +.Pp +The +.Fn inet_addr +and +.Fn inet_network +functions return numbers suitable for use +as Internet addresses and Internet network +numbers, respectively. +Both functions return the constant +.Dv INADDR_NONE +if the specified character string is malformed. +.Pp +The routine +.Fn inet_ntoa +takes an Internet address and returns an +ASCII string representing the address in dot notation. +.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 dot 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 +(such as the Intel 386, 486 and 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 rightmost 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 rightmost 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 dot notation +may be decimal, octal, or hexadecimal, as specified +in the C language (i.e., a leading 0x or 0X implies +hexadecimal; a leading 0 implies octal; +otherwise, the number is interpreted as decimal). +.Sh SEE ALSO +.Xr byteorder 3 , +.Xr gethostbyname 3 , +.Xr getnetent 3 , +.Xr inet_lnaof 3 , +.Xr inet_net 3 , +.Xr inet_ntop 3 , +.Xr hosts 5 , +.Xr networks 5 +.Sh STANDARDS +The +.Nm inet_addr +and +.Nm inet_aton +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Nm inet_addr +and +.Nm inet_network +functions appeared in +.Bx 4.2 . +The +.Nm inet_aton +and +.Nm inet_ntoa +functions appeared in +.Bx 4.3 . +.Sh BUGS +The value +.Dv INADDR_NONE +(0xffffffff) is a valid broadcast address, but +.Fn inet_addr +cannot return that value without indicating failure. +Also, +.Fn inet_addr +should have been designed to return a +.Li struct in_addr . +The newer +.Fn inet_aton +function does not share these problems, and almost all existing code +should be modified to use +.Fn inet_aton +instead. +.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. diff --git a/lib/libc/net/inet_lnaof.3 b/lib/libc/net/inet_lnaof.3 new file mode 100644 index 00000000000..f3f03514af6 --- /dev/null +++ b/lib/libc/net/inet_lnaof.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: inet_lnaof.3,v 1.1 2014/04/19 11:18:01 guenther Exp $ +.\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem 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 $Mdocdate: April 19 2014 $ +.Dt INET_LNAOF 3 +.Os +.Sh NAME +.Nm inet_makeaddr , +.Nm inet_netof , +.Nm inet_lnaof +.Nd routines for manipulating classful Internet Protocol version 4 (IPv4) addresses +.Sh SYNOPSIS +.In arpa/inet.h +.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_lnaof "struct in_addr in" +.Sh DESCRIPTION +As originally designed, +IP version 4 split each address into a network part and local network +address part, encoding that split into the address itself. +It is frequency-encoded; +the most-significant bit is clear in Class A addresses, +in which the high-order 8 bits are the network number. +Class B addresses use the high-order 16 bits as the network field, +and Class C addresses have a 24-bit network part. +.Pp +The routine +.Fn inet_makeaddr +takes an Internet network number and a local +network address and constructs an Internet address +from it. +.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. +.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 SEE ALSO +.Xr getnetent 3 , +.Xr inet_addr 3 , +.Xr inet_net 3 , +.Xr hosts 5 , +.Xr networks 5 +.Sh HISTORY +The +.Nm inet_makeaddr , +.Nm inet_lnaof , +and +.Nm inet_netof +functions appeared in +.Bx 4.2 . diff --git a/lib/libc/net/inet_ntop.3 b/lib/libc/net/inet_ntop.3 new file mode 100644 index 00000000000..a5bd5076feb --- /dev/null +++ b/lib/libc/net/inet_ntop.3 @@ -0,0 +1,204 @@ +.\" $OpenBSD: inet_ntop.3,v 1.1 2014/04/19 11:18:01 guenther Exp $ +.\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem 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 $Mdocdate: April 19 2014 $ +.Dt INET_NTOP 3 +.Os +.Sh NAME +.Nm inet_ntop , +.Nm inet_pton +.Nd convert Internet addresses between presentation and network formats +.Sh SYNOPSIS +.In arpa/inet.h +.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 +.Fn inet_pton +function converts a presentation format address (that is, printable form +as held in a character string) to network format (usually a +.Li 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; +0 if the address wasn't parseable 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 function +.Fn inet_ntop +converts an address from network format to presentation format. +It returns +.Dv NULL +if a system +error occurs (in which case, +.Va errno +will have been set), or it returns a pointer to the destination string. +.Pp +All Internet addresses are returned in network +order (bytes ordered from left to right). +.Sh INTERNET ADDRESSES (IP VERSION 4) +Values must be specified using the standard dot notation: +.Bd -literal -offset indent +a.b.c.d +.Ed +.Pp +All four parts must be decimal numbers between 0 and 255, inclusive. +.Sh INTERNET ADDRESSES (IP VERSION 6) +In order to support scoped IPv6 addresses, +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 +are recommended rather than the functions presented here. +.Pp +The presentation format of an IPv6 address is given in RFC 4291: +.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 +.Dq \&:\&: +indicates multiple groups +of 16 bits of zeros. +The +.Dq \&:\&: +can only appear once in an +address. +The +.Dq \&:\&: +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 SEE ALSO +.Xr gethostbyname 3 , +.Xr inet_addr 3 , +.Xr inet_net 3 , +.Xr hosts 5 +.Sh STANDARDS +The +.Nm inet_ntop +and +.Nm inet_pton +functions conform to the IETF IPv6 BSD API and address formatting +specifications, as well as +.St -p1003.1-2008 . +.Sh HISTORY +The +.Nm inet_pton +and +.Nm inet_ntop +functions appeared in BIND 4.9.4. +.Sh CAVEATS +Note that +.Nm inet_pton +does not accept 1-, 2-, or 3-part dotted addresses; +all four parts must be specified and must be in decimal +(and not octal or hexadecimal). +This is a narrower input set than that accepted by +.Nm inet_aton . +.Pp +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A J. McCann +.%A W. Stevens +.%D February 2003 +.%R RFC 3493 +.%T Basic Socket Interface Extensions for IPv6 +.Re +.Pp +.Rs +.%A R. Hinden +.%A S. Deering +.%D February 2006 +.%R RFC 4291 +.%T IP Version 6 Addressing Architecture +.Re -- cgit v1.2.3