| .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
| .\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
| .\" <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, |
| inet_netof \- Internet address manipulation routines |
| .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 "char *inet_ntoa(struct in_addr " in ); |
| .PP |
| .BI "struct in_addr inet_makeaddr(in_addr_t " net ", in_addr_t " host ); |
| .PP |
| .BI "in_addr_t inet_lnaof(struct in_addr " in ); |
| .BI "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 |
| .IR "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). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR inet_aton (), |
| .BR inet_addr (), |
| .BR inet_network (), |
| .BR inet_ntoa () |
| T} Thread safety MT-Safe locale |
| T{ |
| .BR inet_makeaddr (), |
| .BR inet_lnaof (), |
| .BR inet_netof () |
| T} Thread safety MT-Safe |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| .BR inet_addr (), |
| .BR inet_ntoa (): |
| POSIX.1-2001, POSIX.1-2008, 4.3BSD. |
| .PP |
| .BR inet_aton () |
| is not specified in POSIX.1, but is available on most systems. |
| .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). |
| .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 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 |
| \& |
| .EX |
| #define _BSD_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 |
| .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) |