lib/libc/inet/inet_net.3

   1 .\"     $NetBSD: inet_net.3,v 1.5 2012/07/20 20:48:59 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd July 20, 2012
  31 .Dt INET_NET 3
  32 .Os
  33 .Sh NAME
  34 .Nm inet_net_ntop ,
  35 .Nm inet_net_pton
  36 .Nd Internet network number manipulation routines
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/socket.h
  41 .In netinet/in.h
  42 .In arpa/inet.h
  43 .Ft char *
  44 .Fn inet_net_ntop "int af" "const void *src" "int bits" "char *dst" "size_t size"
  45 .Ft int
  46 .Fn inet_net_pton "int af" "const char *src" "void *dst" "size_t size"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn inet_net_ntop
  50 function converts an Internet network number from network format (usually a
  51 .Vt struct in_addr
  52 or some other binary form, in network byte order) to CIDR presentation format
  53 (suitable for external display purposes).
  54 The
  55 .Fa bits
  56 argument is the number of bits in
  57 .Fa src
  58 that are the network number.
  59 It returns
  60 .Dv NULL
  61 if an error occurs (in which case
  62 .Va errno
  63 will have been set), or it returns a pointer to the destination string.
  64 .Pp
  65 The
  66 .Fn inet_net_pton
  67 function converts a presentation format Internet network number (that is,
  68 printable form as held in a character string) to network format (usually a
  69 .Vt struct in_addr
  70 or some other internal binary representation, in network byte order).
  71 It returns the number of bits (either computed based on the class, or
  72 specified with /CIDR), or \-1 if a failure occurred
  73 (in which case
  74 .Va errno
  75 will have been set).
  76 .Pp
  77 The currently supported values for
  78 .Fa af
  79 are
  80 .Dv AF_INET
  81 and
  82 .Dv AF_INET6 .
  83 The
  84 .Fa size
  85 argument is the size of the result buffer
  86 .Fa dst .
  87 .Sh NETWORK NUMBERS (IP VERSION 4)
  88 Internet network numbers may be specified in one of the following forms:
  89 .Bd -literal -offset indent
  90 a.b.c.d/bits
  91 a.b.c.d
  92 a.b.c
  93 a.b
  94 a
  95 .Ed
  96 .Pp
  97 When four parts are specified, each is interpreted
  98 as a byte of data and assigned, from left to right,
  99 to the four bytes of an Internet network number.
 100 Note that when an Internet network number is viewed as a 32-bit
 101 integer quantity on a system that uses little-endian
 102 byte order (such as the
 103 .Tn Intel 386 , 486 ,
 104 and
 105 .Tn Pentium
 106 processors) the bytes referred to above appear as
 107 .Dq Li d.c.b.a .
 108 That is, little-endian bytes are ordered from right to left.
 109 .Pp
 110 When a three part number is specified, the last
 111 part is interpreted as a 16-bit quantity and placed
 112 in the rightmost two bytes of the Internet network number.
 113 This makes the three part number format convenient
 114 for specifying Class B network numbers as
 115 .Dq Li 128.net.host .
 116 .Pp
 117 When a two part number is supplied, the last part
 118 is interpreted as a 24-bit quantity and placed in
 119 the rightmost three bytes of the Internet network number.
 120 This makes the two part number format convenient
 121 for specifying Class A network numbers as
 122 .Dq Li net.host .
 123 .Pp
 124 When only one part is given, the value is stored
 125 directly in the Internet network number without any byte
 126 rearrangement.
 127 .Pp
 128 All numbers supplied as
 129 .Dq parts
 130 in a
 131 .Ql \&.
 132 notation
 133 may be decimal, octal, or hexadecimal, as specified
 134 in the C language (i.e., a leading 0x or 0X implies
 135 hexadecimal; otherwise, a leading 0 implies octal;
 136 otherwise, the number is interpreted as decimal).
 137 .\"
 138 .\" .Sh NETWORK NUMBERS (IP VERSION 6)
 139 .\" XXX - document this!
 140 .\"
 141 .Sh ERRORS
 142 The
 143 .Fn inet_net_ntop
 144 and
 145 .Fn inet_net_pton
 146 functions may fail with
 147 .Bl -tag -width Er
 148 .It Bq Er EAFNOSUPPORT
 149 The value of
 150 .Fa af
 151 was not
 152 .Dv AF_INET
 153 or
 154 .Dv AF_INET6 .
 155 .It Bq Er EMSGSIZE
 156 The conversion of
 157 .Fa src
 158 overflows
 159 .Fa size
 160 of
 161 .Fa dst .
 162 .El
 163 .Pp
 164 The
 165 .Fn inet_net_ntop
 166 function may fail with
 167 .Bl -tag -width Er
 168 .It Bq Er EINVAL
 169 The
 170 .Fa bits
 171 argument contains an invalid number of bits
 172 for the requested address family.
 173 .El
 174 .Pp
 175 The
 176 .Fn inet_net_pton
 177 function may fail with
 178 .Bl -tag -width Er
 179 .It Bq Er ENOENT
 180 The
 181 .Fa src
 182 was not a valid Internet network number.
 183 .El
 184 .Sh SEE ALSO
 185 .Xr byteorder 3 ,
 186 .Xr inet 3 ,
 187 .Xr networks 5
 188 .Sh HISTORY
 189 The
 190 .Fn inet_net_ntop
 191 and
 192 .Fn inet_net_pton
 193 functions appeared in BIND 4.9.4 and thence
 194 .Nx 1.3 .
 195 Support for
 196 .Dv AF_INET6
 197 appeared in
 198 .Nx 1.6 .