inet_addr()

The inet_addr() call constructs an internet address from character strings representing numbers expressed in standard dotted-decimal notation.

Syntax

#include <arpa\inet.h>
u_long inet_addr(cp)
char *cp;

Parameters

A character string in standard dotted-decimal notation

Description

The inet_addr() call converts an ASCII string containing a valid internet address using dotted-decimal notation into an internet address number typed as an unsigned long value. An example of dotted-decimal notation is 120.121.5.123. The inet_addr() call returns an error value if the internet address notation in the ASCII string supplied by the application is not valid.

Note:

Although inet_addr() call and inet_network() call both convert internet addresses in dotted-decimal notation, they process ASCII strings differently. When an application gives the inet_addr() call a string containing an internet address value without a delimiter, the call returns the logical product of the value represented by the string and 0xFFFFFFFF. For any other internet address, if the value of the fields exceeds the previously defined limits, the inet_addr() call returns an error value of -1.

When an application gives the inet_network() call a string containing an internet address value without a delimiter, the inet_network() call returns the logical product of the value represented by the string and 0xFF. For any other internet address, the call returns an error value of -1 if the value of the fields exceeds the previously defined limits.

Sample return values for each call are as follows:

 Application string       inet_addr() returns   inet_network()
                                                returns

 0x1234567890abcdef       0x090abcdef           0x000000ef

 0x1234567890abcdef       0xFFFFFFFF (= -1)     0x0000ef00

 256.257.258.259          0xFFFFFFFF (= -1)     0x00010203

The ASCII string for the inet_addr() call must conform to the following format:

string::= field | field delimited_field^1-3 | delimited_field^1-3delimited_field::= delimiter field | delimiter
delimiter::= .
field::= 0X | 0x | 0Xhexadecimal* | 0x hexadecimal* | decimal* | 0 octal
hexadecimal::= decimal |a|b|c|d|e|f|A|B|C|D|E|F
decimal::= octal |8|9
octal::= 0|1|2|3|4|5|6|7

Notes:

n indicates n repetitions of a pattern.
n-m indicates n to m repetitions of a pattern.
indicates 0 or more repetitions of a pattern, up to environmental limits.
The Backus Naur form (BNF) description states the space character, if one is used. Text indicates text, not a BNF symbol.

The inet_addr() call requires an application to terminate the string with a null terminator (0x00) or a space (0x30). The string is considered invalid if the application does not end it with a null terminator or a space. The call ignores characters trailing a space.

The following describes the restrictions on the field values for the inet_addr() call:

Format

Field Restrictions (in decimal)

Value _ a

a . b

Value _ a

Value _ b

a . b . c

Value _ a

Value _ b

Value _ c

a . b . c . d

Value _ a

Value _ b

Value _ c

Value _ d

When a four-part address is specified, each part is interpreted as a byte of data and assigned, from left to right, to one of the 4 bytes of an internet address.

When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the two rightmost bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as 128.net.host.

When a two-part address is specified, the last part is interpreted as a 24-bit quantity and placed in the three rightmost bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as net.host.

When a one-part address is specified, the value is stored directly in the network address space without any rearrangement of its bytes.

Numbers supplied as address parts in standard dotted-decimal notation can be decimal, hexadecimal, or octal. Numbers are interpreted in C language syntax. A leading 0x implies hexadecimal; a leading 0 implies octal. A number without a leading 0 implies decimal.

Applications that use the inet_addr() call can enter field values exceeding the above restrictions. The call accepts the least significant bits up to an integer in length, then checks whether the truncated value exceeds the maximum field value. For example, if an application enters a field value of 0x1234567890 and the system uses 16 bits per integer, then the inet_addr() call uses bits 0-15. The call returns 0x34567890.

Applications can omit field values between delimiters. The inet_addr() call interprets empty fields as 0.

Notes:

The inet_addr() call does not check the pointer to the ASCII string. The user must ensure the validity of the address in the ASCII string.
The application must verify that the network and host IDs for the internet address conform to either a Class A, B, or C internet address. The inet_attr() call processes any other class of address as a Class C address.

Return Values

The internet address is returned in network-byte order. The return value points to static data that subsequent API calls can modify.

For valid input strings, the inet_addr() call returns an unsigned long value comprised of the bit patterns of the input fields concatenated together. The call places the first pattern in the most significant position and appends any subsequent patterns to the next most significant positions.

The inet_addr() call returns an error value of -1 for invalid strings.

Note: An internet address with a dotted-decimal notation value of 255.255.255.255 or its equivalent in a different base format causes the inet_addr() call to return an unsigned long value of 4294967295. This value is identical to the unsigned representation of the error value. Otherwise, the inet_addr() call considers 255.255.255.255 a valid internet address.

[Back: htons()]
[Next: inet_lnaof()]