From 44d9059e6aaae4716cbe1d7ea4dd7e061bbc9016 Mon Sep 17 00:00:00 2001 From: guenther Date: Sat, 19 Apr 2014 11:18:01 +0000 Subject: [PATCH] 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_addr.3 | 197 ++++++++++++++++++++++++++ lib/libc/net/inet_lnaof.3 | 90 ++++++++++++ lib/libc/net/{inet.3 => inet_ntop.3} | 201 ++++----------------------- 4 files changed, 320 insertions(+), 183 deletions(-) create mode 100644 lib/libc/net/inet_addr.3 create mode 100644 lib/libc/net/inet_lnaof.3 rename lib/libc/net/{inet.3 => inet_ntop.3} (55%) 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_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.3 b/lib/libc/net/inet_ntop.3 similarity index 55% rename from lib/libc/net/inet.3 rename to lib/libc/net/inet_ntop.3 index e56ca0a59a5..a5bd5076feb 100644 --- a/lib/libc/net/inet.3 +++ b/lib/libc/net/inet_ntop.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: inet.3,v 1.26 2013/06/05 03:39:23 tedu Exp $ +.\" $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 @@ -30,72 +30,20 @@ .\" .\" @(#)inet.3 8.1 (Berkeley) 6/4/93 .\" -.Dd $Mdocdate: June 5 2013 $ -.Dt INET 3 +.Dd $Mdocdate: April 19 2014 $ +.Dt INET_NTOP 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 +.Nm inet_pton +.Nd convert Internet addresses between presentation and network formats .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" +.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 -.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 @@ -114,10 +62,7 @@ and .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). +converts an address from network format to presentation format. It returns .Dv NULL if a system @@ -125,74 +70,15 @@ 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: +Values must be specified using the standard dot notation: .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). +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 @@ -271,23 +157,30 @@ or in compressed form: .Ed .El .Sh SEE ALSO -.Xr byteorder 3 , .Xr gethostbyname 3 , -.Xr getnetent 3 , +.Xr inet_addr 3 , .Xr inet_net 3 , -.Xr hosts 5 , -.Xr networks 5 +.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. +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. +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 @@ -309,47 +202,3 @@ This is a narrower input set than that accepted by .%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. -- 2.20.1