inet_addr Subroutine

Purpose

Converts Internet addresses to Internet numbers.

Library

Standard C Library (libc.a)

Syntax

#include <sys/socket.h>
#include <sys/socketvar.h>
#include <netinet/in.h>
#include <arpa/inet.h>
 
unsigned long inet_addr (CharString)
char *CharString;

Description

The inet_addr subroutine converts an ASCII string containing a valid Internet address using dot notation into an Internet address number typed as an unsigned long value. An example of dot notation is 120.121.5.123. The inet_addr subroutine returns an error value if the Internet address notation in the ASCII string supplied by the application is not valid.

Note: Although they both convert Internet addresses in dot notation to Internet numbers, the inet_addr subroutine and inet_network process ASCII strings differently. When an application gives the inet_addr subroutine a string containing an Internet address value without a delimiter, the subroutine 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 subroutine returns an error value of -1.

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

Sample return values for each subroutine are as follows:

The ASCII string for the inet_addr subroutine must conform to the following format:

string::= field | field delimited_field^1-3 | delimited_field^1-3
delimited_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:

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

The inet_addr subroutine 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 subroutine ignores characters trailing a space.

The following describes the restrictions on the field values for the inet_addr subroutine:

Applications that use the inet_addr subroutine can enter field values exceeding these restrictions. The subroutine 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 subroutine uses bits 0 -15. The subroutine returns 0x34567890.

Applications can omit field values between delimiters. The inet_addr subroutine interprets empty fields as 0.

Notes:

1. The inet_addr subroutine does not check the pointer to the ASCII string. The user must ensure the validity of the address in the ASCII string.
2. 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 subroutine processes any other number as a Class C address.

Parameters

Return Values

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

The inet_addr subroutine returns an error value of -1 for invalid strings.

Note: An Internet address with a dot notation value of 255.255.255.255 or its equivalent in a different base format causes the inet_addr subroutine to return an unsigned long value of 4294967295. This value is identical to the unsigned representation of the error value. Otherwise, the inet_addr subroutine considers 255.255.255.255 a valid Internet address.

Implementation Specifics

The inet_addr subroutine is part of Base Operating System (BOS) Runtime.

All applications containing the inet_addr subroutine must be compiled with _BSD set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

Files

Related Information

The endhostent subroutine, endnetent subroutine, gethostbyaddr subroutine, gethostbyname subroutine, getnetbyaddr subroutine, getnetbyname subroutine, getnetent subroutine, inet_Inaof subroutine, inet_makeaddr subroutine, inet_netof subroutine, inet_network subroutine, inet_ntoa subroutine, sethostent subroutine, setnetent subroutine.

Sockets Overview and Understanding Network Address Translation in AIX Version 4.3 Communications Programming Concepts.