diff options
Diffstat (limited to 'man3/inet.3')
| -rw-r--r-- | man3/inet.3 | 337 |
1 files changed, 337 insertions, 0 deletions
diff --git a/man3/inet.3 b/man3/inet.3 new file mode 100644 index 0000000..557bb2d --- /dev/null +++ b/man3/inet.3 @@ -0,0 +1,337 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" libc.info (from glibc distribution) +.\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith <faith@cs.unc.edu> +.\" Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" Changed network into host byte order (for inet_network), +.\" Andreas Jaeger <aj@arthur.rhein-neckar.de>, 980130. +.\" 2008-06-19, mtk +.\" Describe the various address forms supported by inet_aton(). +.\" Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr(). +.\" Add discussion of Classful Addressing, noting that it is obsolete. +.\" Added an EXAMPLE program. +.\" +.TH inet 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, +inet_netof \- Internet address manipulation routines +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.B #include <netinet/in.h> +.B #include <arpa/inet.h> +.PP +.BI "int inet_aton(const char *" cp ", struct in_addr *" inp ); +.PP +.BI "in_addr_t inet_addr(const char *" cp ); +.BI "in_addr_t inet_network(const char *" cp ); +.PP +.BI "[[deprecated]] char *inet_ntoa(struct in_addr " in ); +.PP +.BI "[[deprecated]] struct in_addr inet_makeaddr(in_addr_t " net , +.BI " in_addr_t " host ); +.PP +.BI "[[deprecated]] in_addr_t inet_lnaof(struct in_addr " in ); +.BI "[[deprecated]] in_addr_t inet_netof(struct in_addr " in ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR inet_aton (), +.BR inet_ntoa (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR inet_aton () +converts the Internet host address \fIcp\fP from the +IPv4 numbers-and-dots notation into binary form (in network byte order) +and stores it in the structure that \fIinp\fP points to. +.BR inet_aton () +returns nonzero if the address is valid, zero if not. +The address supplied in +.I cp +can have one of the following forms: +.TP 10 +.I a.b.c.d +Each of the four numeric parts specifies a byte of the address; +the bytes are assigned in left-to-right order to produce the binary address. +.TP +.I a.b.c +Parts +.I a +and +.I b +specify the first two bytes of the binary address. +Part +.I c +is interpreted as a 16-bit value that defines the rightmost two bytes +of the binary address. +This notation is suitable for specifying (outmoded) Class B +network addresses. +.TP +.I a.b +Part +.I a +specifies the first byte of the binary address. +Part +.I b +is interpreted as a 24-bit value that defines the rightmost three bytes +of the binary address. +This notation is suitable for specifying (outmoded) Class A +network addresses. +.TP +.I a +The value +.I a +is interpreted as a 32-bit value that is stored directly +into the binary address without any byte rearrangement. +.PP +In all of the above forms, +components of the dotted address can be specified in decimal, +octal (with a leading +.IR 0 ), +or hexadecimal, with a leading +.IR 0X ). +Addresses in any of these forms are collectively termed +.IR "IPV4 numbers-and-dots notation" . +The form that uses exactly four decimal numbers is referred to as +.I IPv4 dotted-decimal notation +(or sometimes: +.IR "IPv4 dotted-quad notation" ). +.PP +.BR inet_aton () +returns 1 if the supplied string was successfully interpreted, +or 0 if the string is invalid +.RB ( errno +is +.I not +set on error). +.PP +The +.BR inet_addr () +function converts the Internet host address +\fIcp\fP from IPv4 numbers-and-dots notation into binary data in network +byte order. +If the input is invalid, +.B INADDR_NONE +(usually \-1) is returned. +Use of this function is problematic because \-1 is a valid address +(255.255.255.255). +Avoid its use in favor of +.BR inet_aton (), +.BR inet_pton (3), +or +.BR getaddrinfo (3), +which provide a cleaner way to indicate error return. +.PP +The +.BR inet_network () +function converts +.IR cp , +a string in IPv4 numbers-and-dots notation, +into a number in host byte order suitable for use as an +Internet network address. +On success, the converted address is returned. +If the input is invalid, \-1 is returned. +.PP +The +.BR inet_ntoa () +function converts the Internet host address +\fIin\fP, given in network byte order, to a string in IPv4 +dotted-decimal notation. +The string is returned in a statically +allocated buffer, which subsequent calls will overwrite. +.PP +The +.BR inet_lnaof () +function returns the local network address part +of the Internet address \fIin\fP. +The returned value is in host byte order. +.PP +The +.BR inet_netof () +function returns the network number part of +the Internet address \fIin\fP. +The returned value is in host byte order. +.PP +The +.BR inet_makeaddr () +function is the converse of +.BR inet_netof () +and +.BR inet_lnaof (). +It returns an Internet host address in network byte order, +created by combining the network number \fInet\fP +with the local address \fIhost\fP, both in +host byte order. +.PP +The structure \fIin_addr\fP as used in +.BR inet_ntoa (), +.BR inet_makeaddr (), +.BR inet_lnaof (), +and +.BR inet_netof () +is defined in +.I <netinet/in.h> +as: +.PP +.in +4n +.EX +typedef uint32_t in_addr_t; +\& +struct in_addr { + in_addr_t s_addr; +}; +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR inet_aton (), +.BR inet_addr (), +.BR inet_network (), +.BR inet_ntoa () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR inet_makeaddr (), +.BR inet_lnaof (), +.BR inet_netof () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH STANDARDS +.TP +.BR inet_addr () +.TQ +.BR inet_ntoa () +POSIX.1-2008. +.TP +.BR inet_aton () +None. +.SH STANDARDS +.TP +.BR inet_addr () +.TQ +.BR inet_ntoa () +POSIX.1-2001, 4.3BSD. +.PP +.BR inet_lnaof (), +.BR inet_netof (), +and +.BR inet_makeaddr () +are legacy functions that assume they are dealing with +.IR "classful network addresses" . +Classful networking divides IPv4 network addresses into host and network +components at byte boundaries, as follows: +.TP 10 +Class A +This address type is indicated by the value 0 in the +most significant bit of the (network byte ordered) address. +The network address is contained in the most significant byte, +and the host address occupies the remaining three bytes. +.TP +Class B +This address type is indicated by the binary value 10 in the +most significant two bits of the address. +The network address is contained in the two most significant bytes, +and the host address occupies the remaining two bytes. +.TP +Class C +This address type is indicated by the binary value 110 in the +most significant three bits of the address. +The network address is contained in the three most significant bytes, +and the host address occupies the remaining byte. +.PP +Classful network addresses are now obsolete, +having been superseded by Classless Inter-Domain Routing (CIDR), +which divides addresses into network and host components at +arbitrary bit (rather than byte) boundaries. +.SH NOTES +On x86 architectures, the host byte order is Least Significant Byte +first (little endian), whereas the network byte order, as used on the +Internet, is Most Significant Byte first (big endian). +.SH EXAMPLES +An example of the use of +.BR inet_aton () +and +.BR inet_ntoa () +is shown below. +Here are some example runs: +.PP +.in +4n +.EX +.RB "$" " ./a.out 226.000.000.037" " # Last byte is in octal" +226.0.0.31 +.RB "$" " ./a.out 0x7f.1 " " # First byte is in hex" +127.0.0.1 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (inet.c) +.EX +#define _DEFAULT_SOURCE +#include <arpa/inet.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + struct in_addr addr; +\& + if (argc != 2) { + fprintf(stderr, "%s <dotted\-address>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (inet_aton(argv[1], &addr) == 0) { + fprintf(stderr, "Invalid address\en"); + exit(EXIT_FAILURE); + } +\& + printf("%s\en", inet_ntoa(addr)); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR byteorder (3), +.BR getaddrinfo (3), +.BR gethostbyname (3), +.BR getnameinfo (3), +.BR getnetent (3), +.BR inet_net_pton (3), +.BR inet_ntop (3), +.BR inet_pton (3), +.BR hosts (5), +.BR networks (5) |