inet(3N)

inet -- Internet address conversion and testing

Synopsis

cc [options] file -lnsl

#include <netinet/in.h>
#include <arpa/inet.h>

ssize_t inet_pton(int af, const char *cp, void *ap);

char *inet_ntop(int af, const void *ap, char *cp, size_t len);

in_addr_t inet_netof(struct in_addr in);

in_addr_t inet_lnaof(struct in_addr in);

struct in_addr inet_makeaddr(in_addr_t net, in_addr_t lna);

in_addr_t inet_addr(const char *cp);

in_addr_t inet_network(const char *cp);

char *inet_ntoa(struct in_addr in);

/* Macros for testing IPv6 addresses */

int  IN6_IS_ADDR_UNSPECIFIED (const struct in6_addr *addr);
int  IN6_IS_ADDR_LOOPBACK    (const struct in6_addr *addr);
int  IN6_IS_ADDR_MULTICAST   (const struct in6_addr *addr);
int  IN6_IS_ADDR_LINKLOCAL   (const struct in6_addr *addr);
int  IN6_IS_ADDR_SITELOCAL   (const struct in6_addr *addr);
int  IN6_IS_ADDR_V4MAPPED    (const struct in6_addr *addr);
int  IN6_IS_ADDR_V4COMPAT    (const struct in6_addr *addr);

int  IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *addr);
int  IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *addr);
int  IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *addr);
int  IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *addr);
int  IN6_IS_ADDR_MC_GLOBAL   (const struct in6_addr *addr);

Description

inet_pton interprets addresses belonging to either the AF_INET or AF_INET6 address family in standard text format (``p'' - printable) and converts them to their numeric binary (``n'' - numeric network byte order) values suitable for use as Internet addresses. Use the af argument to specify whether the address (cp) belongs to AF_INET or the AF_INET6 address family. ap should be a buffer large enough for struct in_addr (AF_INET) or struct in6_addr (AF_INET6).

NOTE: If the address specified in cp belongs to AF_INET, it should be expressed in the Internet standard dot notation as described in ``Usage''.
If the address specified in cp belongs to AF_INET6, it must be expressed using one of the three available IPv6 notations also described in ``Usage''.

inet_ntop converts IPv4 and IPv6 binary addresses (``n'' - numeric network byte order) into a text string (``p'' - printable) suitable for presentation. Use the af argument to specify if the binary address (*ap) is an IPv4 or IPv6 address. If the address is an IPv4 address use AF_INET, if it is IPv6 use AF_INET6. Use the len argument to specify the length of the address (ap), that is, sizeof(struct in_addr) or sizeof(struct in6_addr) respectively.

The cp argument must point to a buffer large enough to hold the converted address. For IPv4 addresses set the buffer length to INET_ADDRSTRLEN. For IPv6 addresses set the buffer length to INET6_ADDRSTRLEN. cp must always be a pointer to a buffer with such a size.

The following macros can be used to test for special IPv6 addresses.

IN6_IS_ADDR_UNSPECIFIED returns true if the address is an unspecified IPv6 address, or false otherwise.

IN6_IS_ADDR_LOOPBACK returns true if the address is a loopback IPv6 address, or false otherwise.

IN6_IS_ADDR_MULTICAST returns true if the address is a multicast IPv6 address, or false otherwise.

IN6_IS_ADDR_LINKLOCAL returns true if the address is a link local IPv6 address, or false otherwise.

IN6_IS_ADDR_SITELOCAL returns true if the address is a site local IPv6 address, or false otherwise.

IN6_IS_ADDR_V4MAPPED returns true if the address is an IPv4-mapped IPv6 address, or false otherwise.

IN6_IS_ADDR_V4COMPAT returns true if the address is an IPv4-compatible IPv6 address, or false otherwise.

IN6_IS_ADDR_MC_NODELOCAL returns true if the address is an IPv6 multicast address with node local scope, or false otherwise.

IN6_IS_ADDR_MC_LINKLOCAL returns true if the address is an IPv6 multicast address with link local scope, or false otherwise.

IN6_IS_ADDR_MC_SITELOCAL returns true if the address is an IPv6 multicast address with site local scope, or false otherwise.

IN6_IS_ADDR_MC_ORGLOCAL returns true if the address is an IPv6 multicast address with organization local scope, or false otherwise.

IN6_IS_ADDR_MC_GLOBAL returns true if the address is an IPv6 multicast address with global scope, or false otherwise.

NOTE: The following functions are for use with IPv4 only.

inet_netof and inet_lnaof break apart Internet host addresses, returning the network number and local network address part, respectively.

inet_makeaddr takes an Internet network number and a local network address and constructs an Internet address from them.

inet_addr and inet_network each interpret character strings representing numbers expressed in the Internet standard dot notation, returning numbers suitable for use as Internet addresses and Internet network numbers, respectively. Note that these functions cannot be used to convert the IPv4 limited broadcast address 255.255.255.255.

inet_ntoa returns a pointer to a string in the dotted notation described in ``IPv4 address notation''.

NOTE: All Internet addresses are in network byte order. All network numbers and local address parts are in host byte order.

Usage

Two IP address formats are currently defined:

IPv4: The IPv4 format is the original IP address format of the 4-octet (32-bit) addresses used to uniquely identify every host on the Internet.
IPv6: The IPv6 address format is the new IP address format that is to eventually replace the older IPv4 address type. IPv6 addresses consist of 16 octets (128 bits).

The standard notations used to represent addresses in IPv4 and IPv6 address formats are described below.

IPv4 address notation

Values specified using the dot notation take one of the following forms:

a.b.c.d
a.b.c
a.b
a

Each of the four notation types are described below.

a.b.c.d notation
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.
a.b.c notation
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 128.net.host.
a.b notation
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 net.host.
a notation
When only one part is given, the value is stored directly in the network address without any byte rearrangement.

All numbers supplied as parts in dot notation may be decimal, octal, or hexadecimal, as specified in the C language (that is, a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal).

NOTE: For inet_pton and inet_ntop only notation 1 (a.b.c.d) is valid. In addition, each part of the address can only be in decimal.

IPv6 address notation

There are three possible notation types that can be used to represent IPv6 addresses. The notation you use depends on the content of the address you want to represent.

Standard notation
The standard notation for IPv6 addresses is to represent the address as eight 16-bit hexadecimal words separated by ``:'' (colons). For example:

FEDC:BA98:0332:0000:CF8A:000C:2154:7313

NOTE: It is not necessary to specify leading zeros, as long as there is at least one numeric character in each field of the address. the above address could also be represented as FEDC:BA98:332:0:CF8A:C:2154:7313.
Compressed notation
Since a large number of IPv6 addresses contain multiple fields of zeros, there is a notation you can use to represent a single contiguous group of zero fields within an IPv6 address. This notation is a double colon ``::''. Some examples of how to use the ``::'' are shown below:

1762:0:0:0:0:B03:1:AF18
FF01:0:0:0:CA:0:0:2
0:0:0:0:0:0:0:1
0:0:0:0:0:0:0:0
can be represented as:

1762::B03:1:AF18
FF01::CA:0:0:2
::1
::

NOTE: The FF01:0:0:0:CA:0:0:2 example is represented as FF01::CA:0:0:2 because only one ``::'' is allowed in an address.
Mixed notation
IPv4 addresses that are encapsulated in IPv6 addresses can be represented using the original IPv4 dot notation as follows:

0:0:0:0:0:0:127.32.67.15
0:0:0:0:0:FFFF:127.32.67.15
It is also possible to use the compressed notation, so the addresses above would be represented as:

::127.32.67.15
::FFFF:127.32.67.15

Return values

The IN6_IS_ADDR_ macros evaluate to true (non zero) if true, otherwise they evaluate to 0.

inet_pton returns the length of the converted address on successful conclusion. Otherwise, it returns -1.

inet_ntop returns the length of the converted address on successful conclusion. Otherwise, it returns -1.

inet_netof returns the network number.

inet_lnaof returns the local network address part.

inet_makeaddr returns the constructed Internet address.

inet_addr returns the Internet address on successful conclusion. Otherwise, it returns INADDR_NONE on error.

inet_network returns the converted Internet network number on successful conclusion. Otherwise, it returns INADDR_NONE on error.

inet_ntoa returns a pointer to the network address in standard Internet dot notation.

Diagnostics

No errors are defined.

References

gethostent(3N), getnetent(3N), hosts(4tcp), networks(4tcp)

Notices

The return value from inet_ntoa points to static information which is overwritten in each call. For multi-threaded applications, information is maintained on a per-thread basis.

In UnixWare 7 the sockaddr structure has been modified to support variable length sockets. The result of this modification is that the family member has been shortened to 8 bits and a new 8-bit member inserted before it called len. For more information on the new sockaddr structures, see: unix(7sock) and inet(7tcp).