2 .\" The contents of this file are subject to the terms of the
3 .\" Common Development and Distribution License (the "License").
4 .\" You may not use this file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7 .\" or http://www.opensolaris.org/os/licensing.
8 .\" See the License for the specific language governing permissions
9 .\" and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each
12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13 .\" If applicable, add the following below this CDDL HEADER, with the
14 .\" fields enclosed by brackets "[]" replaced with your own identifying
15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\" Copyright 1989 AT&T
19 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
20 .\" Copyright 2018 Nexenta Systems, Inc.
37 .Nd Internet address manipulation
48 .Fa "const void *addr"
61 .Fa "struct in_addr *addr"
78 .Fa "const struct in_addr in"
82 .Fa "const struct in_addr in"
86 .Fa "const struct in_addr in"
93 functions can manipulate both IPv4 and IPv6 addresses.
103 functions can only manipulate IPv4 addresses.
107 function converts a numeric address into a string suitable for presentation.
110 argument specifies the family of the address which can be
116 argument points to a buffer that holds an IPv4 address if the
122 argument points to a buffer that holds an IPv6 address if the
126 The address must be in network byte order.
129 argument points to a buffer where the function stores the resulting string.
130 The application must specify a non-NULL
135 argument specifies the size of this buffer.
136 For IPv6 addresses, the buffer must be at least 46-octets.
137 For IPv4 addresses, the buffer must be at least 16-octets.
138 To allow applications to easily declare buffers of the proper size to store IPv4
139 and IPv6 addresses in string form, the following two constants are defined in
142 #define INET_ADDRSTRLEN 16
143 #define INET6_ADDRSTRLEN 46
148 function converts the standard text presentation form of a function to the
152 argument specifies the family of the address.
157 address families are supported.
160 argument points to the string being passed in.
163 argument points to a buffer where the function stores the numeric address.
164 The calling application must ensure that the buffer referred to by
166 is large enough to hold the numeric address, at least 4 bytes for
176 functions interpret character strings that represent numbers expressed in the
179 notation, returning numbers suitable for use as IPv4 addresses and IPv4 network
180 numbers, respectively.
183 function uses an IPv4 network number and a local network address to construct
189 functions break apart IPv4 host addresses, then return the network number and
190 local network address, respectively.
194 function returns a pointer to a string in the base 256 notation
196 See the following section on IPv4 addresses.
198 Internet addresses are returned in network order, bytes ordered from left to
200 Network numbers and local address parts are returned as machine format integer
203 There are three conventional forms for representing IPv6 addresses as strings:
206 The preferred form is
207 .Ql x:x:x:x:x:x:x:x ,
211 hexadecimal values of the eight 16-bit pieces of the address.
213 .Ql 1080:0:0:0:8:800:200C:417A .
215 It is not necessary to write the leading zeros in an individual field.
216 There must be at least one numeral in every field, except when the special
217 syntax described in the following is used.
219 It is common for addresses to contain long strings of zero bits in some
220 methods used to allocate certain IPv6 address styles.
221 A special syntax is available to compress the zeros.
224 indicates multiple groups of 16 bits of zeros.
227 may only appear once in an address.
230 can also be used to compress the leading and trailing zeros in an address.
232 .Ql 1080::8:800:200C:417A .
235 .Ql x:x:x:x:x:x:d.d.d.d
236 is sometimes more convenient when dealing with a mixed environment of IPv4 and
240 in this form represent the hexadecimal values of the six high-order 16-bit
241 pieces of the address.
244 represent the decimal values of the four low-order 8-bit pieces of the standard
248 ::FFFF:129.144.52.38 .
256 pieces are the general forms of an IPv4-mapped IPv6 address and an
257 IPv4-compatible IPv6 address.
259 The IPv4 portion must be in the
262 The following forms are invalid:
272 form is a valid but unconventional representation of the IPv4-compatible IPv6
278 form corresponds to the general IPv6 address
279 .Ql 0:0:0:0:0:0:0:d .
282 Values specified using
284 notation take one of the following forms:
292 When four parts are specified, each part is interpreted as a byte of data and
293 assigned from left to right to the four bytes of an IPv4 address.
295 When a three-part address is specified, the last part is interpreted as a
296 16-bit quantity and placed in the right most two bytes of the network address.
297 The three part address format is convenient for specifying Class B network
301 When a two-part address is supplied, the last part is interpreted as a 24-bit
302 quantity and placed in the right most three bytes of the network address.
303 The two part address format is convenient for specifying Class A network
307 When only one part is given, the value is stored directly in the network
308 address without any byte rearrangement.
310 With the exception of
312 numbers supplied as parts in
314 notation may be decimal, octal, or hexadecimal, as specified in C language.
315 For example, a leading
323 Otherwise, the number is interpreted as decimal.
327 accepts only a string in standard IPv4 dot notation
330 Each number has one to three digits with a decimal value between 0 and 255.
334 function has been obsoleted by
339 function returns nonzero if the address is valid,
341 if the address is invalid.
345 function returns a pointer to the buffer that contains a string if the
356 argument is invalid or
358 if the size of the result buffer is inadequate.
364 if the conversion succeeds,
366 if the input is not a valid IPv4 dotted-decimal string or a valid IPv6
380 which is equivalent to
381 .Li (in_addr_t)(-1) ,
386 for malformed requests.
392 break apart IPv4 host addresses, returning the network number and local network
393 address part, respectively.
397 returns a pointer to a string in the base 256 notation
399 described in the section on IPv4 addresses.
402 .Sh INTERFACE STABILITY
419 .Sy Obsolete Committed .
422 .Xr gethostbyname 3C ,
423 .Xr getipnodebyname 3C ,
424 .Xr getnetbyname 3C ,
429 The return value from
431 points to a buffer which is overwritten on each call.
432 This buffer is implemented as thread-specific data in multithreaded
435 IPv4-mapped addresses are not recommended.
437 The problem of host byte ordering versus network byte ordering is confusing.
439 A simple way to specify Class C network addresses in a manner similar to that
440 for Class B and Class A is needed.