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.

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.

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).


© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004