Subversion Repositories openrisc_2011-10-31

.\" Copyright (c) 1983, 1990, 1991, 1993

.\"     The Regents of the University of California.  All rights reserved.

.\"

.\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted provided that the following conditions

.\" are met:

.\" 1. Redistributions of source code must retain the above copyright

.\"    notice, this list of conditions and the following disclaimer.

.\" 2. Redistributions in binary form must reproduce the above copyright

.\"    notice, this list of conditions and the following disclaimer in the

.\"    documentation and/or other materials provided with the distribution.

.\" 3. All advertising materials mentioning features or use of this software

.\"    must display the following acknowledgement:

.\"     This product includes software developed by the University of

.\"     California, Berkeley and its contributors.

.\" 4. Neither the name of the University nor the names of its contributors

.\"    may be used to endorse or promote products derived from this software

.\"    without specific prior written permission.

.\"

.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

.\" SUCH DAMAGE.

.\"

.\"     From: @(#)inet.3        8.1 (Berkeley) 6/4/93

.\"     $Id: inet.3,v 1.2 2001-09-27 12:01:53 chris Exp $

.\"

.Dd June 17, 1996

.Dt INET 3

.Os BSD 4.2

.Sh NAME

.Nm inet_aton ,

.Nm inet_addr ,

.Nm inet_network ,

.Nm inet_ntoa ,

.Nm inet_makeaddr ,

.Nm inet_lnaof ,

.Nm inet_netof

.Nd Internet address manipulation routines

.Sh SYNOPSIS

.Fd #include 

.Fd #include 

.Fd #include 

.Fd #include 

.Ft int

.Fn inet_aton "const char *cp" "struct in_addr *pin"

.Ft unsigned long

.Fn inet_addr "const char *cp"

.Ft unsigned long

.Fn inet_network "const char *cp"

.Ft char *

.Fn inet_ntoa "struct in_addr in"

.Ft struct in_addr

.Fn inet_makeaddr "unsigned long net" "unsigned long lna"

.Ft unsigned long

.Fn inet_lnaof "struct in_addr in"

.Ft unsigned long

.Fn inet_netof "struct in_addr in"

.Sh DESCRIPTION

The routines

.Fn inet_aton ,

.Fn inet_addr

and

.Fn inet_network

interpret character strings representing

numbers expressed in the Internet standard

.Ql \&.

notation.

The

.Fn inet_aton

routine interprets the specified character string as an Internet address,

placing the address into the structure provided.

It returns 1 if the string was successfully interpreted,

or 0 if the string is invalid.

The

.Fn inet_addr

and

.Fn inet_network

functions return numbers suitable for use

as Internet addresses and Internet network

numbers, respectively.

The routine

.Fn inet_ntoa

takes an Internet address and returns an

.Tn ASCII

string representing the address in

.Ql \&.

notation.  The routine

.Fn inet_makeaddr

takes an Internet network number and a local

network address and constructs an Internet address

from it.  The routines

.Fn inet_netof

and

.Fn inet_lnaof

break apart Internet host addresses, returning

the network number and local network address part,

respectively.

.Pp

All Internet addresses are returned in network

order (bytes ordered from left to right).

All network numbers and local address parts are

returned as machine format integer values.

.Sh INTERNET ADDRESSES

Values specified using the

.Ql \&.

notation take one

of the following forms:

.Bd -literal -offset indent

a.b.c.d

a.b.c

a.b

a

.Ed

.Pp

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

that when an Internet address is viewed as a 32-bit

integer quantity on the

.Tn VAX

the bytes referred to

above appear as

.Dq Li d.c.b.a .

That is,

.Tn VAX

bytes are

ordered from right to left.

.Pp

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

.Dq Li 128.net.host .

.Pp

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

.Dq Li net.host .

.Pp

When only one part is given, the value is stored

directly in the network address without any byte

rearrangement.

.Pp

All numbers supplied as

.Dq parts

in a

.Ql  \&.

notation

may be decimal, octal, or hexadecimal, as specified

in the C language (i.e., a leading 0x or 0X implies

hexadecimal; otherwise, a leading 0 implies octal;

otherwise, the number is interpreted as decimal).

.Pp

The

.Fn inet_aton

and

.Fn inet_ntoa

functions are semi-deprecated in favor of the

.Xr addr2ascii 3

family.  However, since those functions are not yet widely implemented,

portable programs cannot rely on their presence and will continue

to use the

.Xr inet 3

functions for some time.

.Sh DIAGNOSTICS

The constant

.Dv INADDR_NONE

is returned by

.Fn inet_addr

and

.Fn inet_network

for malformed requests.

.Sh SEE ALSO

.Xr addr2ascii 3 ,

.Xr gethostbyname 3 ,

.Xr getnetent 3 ,

.Xr hosts 5 ,

.Xr networks 5

.Sh HISTORY

These

functions appeared in

.Bx 4.2 .

.Sh BUGS

The value

.Dv INADDR_NONE

(0xffffffff) is a valid broadcast address, but

.Fn inet_addr

cannot return that value without indicating failure.

The newer

.Fn inet_aton

function does not share this problem.

The problem of host byte ordering versus network byte ordering is

confusing.

The string returned by

.Fn inet_ntoa

resides in a static memory area.

.Pp

Inet_addr should return a

.Fa struct in_addr .