[BACK]Return to inet_net.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / inet

Annotation of src/lib/libc/inet/inet_net.3, Revision 1.5

1.5     ! wiz         1: .\"    $NetBSD: inet_net.3,v 1.4 2012/07/20 19:44:39 ginsbach Exp $
1.1       christos    2: .\"
                      3: .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
                      4: .\" All rights reserved.
                      5: .\"
                      6: .\" This code is derived from software contributed to The NetBSD Foundation
                      7: .\" by Luke Mewburn.
                      8: .\"
                      9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\"    notice, this list of conditions and the following disclaimer in the
                     16: .\"    documentation and/or other materials provided with the distribution.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
                     19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
                     20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
                     21: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
                     22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
                     23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
                     24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                     25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                     26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
                     27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
                     28: .\" POSSIBILITY OF SUCH DAMAGE.
                     29: .\"
1.4       ginsbach   30: .Dd July 20, 2012
1.1       christos   31: .Dt INET_NET 3
                     32: .Os
                     33: .Sh NAME
                     34: .Nm inet_net_ntop ,
                     35: .Nm inet_net_pton
                     36: .Nd Internet network number manipulation routines
                     37: .Sh LIBRARY
                     38: .Lb libc
                     39: .Sh SYNOPSIS
                     40: .In sys/socket.h
                     41: .In netinet/in.h
                     42: .In arpa/inet.h
                     43: .Ft char *
                     44: .Fn inet_net_ntop "int af" "const void *src" "int bits" "char *dst" "size_t size"
                     45: .Ft int
                     46: .Fn inet_net_pton "int af" "const char *src" "void *dst" "size_t size"
                     47: .Sh DESCRIPTION
                     48: The
                     49: .Fn inet_net_ntop
                     50: function converts an Internet network number from network format (usually a
1.3       ginsbach   51: .Vt struct in_addr
1.1       christos   52: or some other binary form, in network byte order) to CIDR presentation format
                     53: (suitable for external display purposes).
1.3       ginsbach   54: The
1.1       christos   55: .Fa bits
1.3       ginsbach   56: argument is the number of bits in
1.1       christos   57: .Fa src
                     58: that are the network number.
1.3       ginsbach   59: It returns
                     60: .Dv NULL
1.4       ginsbach   61: if an error occurs (in which case
1.1       christos   62: .Va errno
                     63: will have been set), or it returns a pointer to the destination string.
                     64: .Pp
                     65: The
                     66: .Fn inet_net_pton
                     67: function converts a presentation format Internet network number (that is,
                     68: printable form as held in a character string) to network format (usually a
1.3       ginsbach   69: .Vt struct in_addr
1.1       christos   70: or some other internal binary representation, in network byte order).
                     71: It returns the number of bits (either computed based on the class, or
1.3       ginsbach   72: specified with /CIDR), or \-1 if a failure occurred
1.1       christos   73: (in which case
                     74: .Va errno
1.4       ginsbach   75: will have been set).
1.1       christos   76: .Pp
                     77: The currently supported values for
                     78: .Fa af
                     79: are
                     80: .Dv AF_INET
                     81: and
                     82: .Dv AF_INET6 .
1.3       ginsbach   83: The
1.1       christos   84: .Fa size
1.3       ginsbach   85: argument is the size of the result buffer
1.1       christos   86: .Fa dst .
                     87: .Sh NETWORK NUMBERS (IP VERSION 4)
                     88: Internet network numbers may be specified in one of the following forms:
                     89: .Bd -literal -offset indent
                     90: a.b.c.d/bits
                     91: a.b.c.d
                     92: a.b.c
                     93: a.b
                     94: a
                     95: .Ed
                     96: .Pp
                     97: When four parts are specified, each is interpreted
                     98: as a byte of data and assigned, from left to right,
1.3       ginsbach   99: to the four bytes of an Internet network number.
                    100: Note that when an Internet network number is viewed as a 32-bit
1.1       christos  101: integer quantity on a system that uses little-endian
                    102: byte order (such as the
1.3       ginsbach  103: .Tn Intel 386 , 486 ,
1.1       christos  104: and
                    105: .Tn Pentium
                    106: processors) the bytes referred to above appear as
                    107: .Dq Li d.c.b.a .
                    108: That is, little-endian bytes are ordered from right to left.
                    109: .Pp
                    110: When a three part number is specified, the last
                    111: part is interpreted as a 16-bit quantity and placed
1.3       ginsbach  112: in the rightmost two bytes of the Internet network number.
1.1       christos  113: This makes the three part number format convenient
                    114: for specifying Class B network numbers as
                    115: .Dq Li 128.net.host .
                    116: .Pp
                    117: When a two part number is supplied, the last part
                    118: is interpreted as a 24-bit quantity and placed in
1.3       ginsbach  119: the rightmost three bytes of the Internet network number.
1.1       christos  120: This makes the two part number format convenient
                    121: for specifying Class A network numbers as
                    122: .Dq Li net.host .
                    123: .Pp
                    124: When only one part is given, the value is stored
                    125: directly in the Internet network number without any byte
                    126: rearrangement.
                    127: .Pp
                    128: All numbers supplied as
                    129: .Dq parts
                    130: in a
1.3       ginsbach  131: .Ql \&.
1.1       christos  132: notation
                    133: may be decimal, octal, or hexadecimal, as specified
                    134: in the C language (i.e., a leading 0x or 0X implies
                    135: hexadecimal; otherwise, a leading 0 implies octal;
                    136: otherwise, the number is interpreted as decimal).
                    137: .\"
                    138: .\" .Sh NETWORK NUMBERS (IP VERSION 6)
                    139: .\" XXX - document this!
                    140: .\"
1.4       ginsbach  141: .Sh ERRORS
                    142: The
                    143: .Fn inet_net_ntop
                    144: and
                    145: .Fn inet_net_pton
                    146: functions may fail with
                    147: .Bl -tag -width Er
                    148: .It Bq Er EAFNOSUPPORT
                    149: The value of
                    150: .Fa af
                    151: was not
                    152: .Dv AF_INET
                    153: or
                    154: .Dv AF_INET6 .
                    155: .It Bq Er EMSGSIZE
                    156: The conversion of
                    157: .Fa src
                    158: overflows
                    159: .Fa size
1.5     ! wiz       160: of
        !           161: .Fa dst .
1.4       ginsbach  162: .El
                    163: .Pp
                    164: The
                    165: .Fn inet_net_ntop
                    166: function may fail with
                    167: .Bl -tag -width Er
                    168: .It Bq Er EINVAL
                    169: The
                    170: .Fa bits
                    171: argument contains an invalid number of bits
                    172: for the requested address family.
                    173: .El
                    174: .Pp
                    175: The
                    176: .Fn inet_net_pton
                    177: function may fail with
                    178: .Bl -tag -width Er
                    179: .It Bq Er ENOENT
                    180: The
                    181: .Fa src
                    182: was not a valid Internet network number.
                    183: .El
1.1       christos  184: .Sh SEE ALSO
                    185: .Xr byteorder 3 ,
                    186: .Xr inet 3 ,
                    187: .Xr networks 5
                    188: .Sh HISTORY
                    189: The
1.3       ginsbach  190: .Fn inet_net_ntop
1.1       christos  191: and
1.3       ginsbach  192: .Fn inet_net_pton
1.1       christos  193: functions appeared in BIND 4.9.4 and thence
                    194: .Nx 1.3 .
                    195: Support for
                    196: .Dv AF_INET6
                    197: appeared in
                    198: .Nx 1.6 .

CVSweb <webmaster@jp.NetBSD.org>