man3/inet_ntop.3

   1 '\" t
   2 .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References: RFC 2553
   7 .TH inet_ntop 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 inet_ntop \- convert IPv4 and IPv6 addresses from binary to text form
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <arpa/inet.h>
  16 .PP
  17 .BI "const char *inet_ntop(int " af ", const void *restrict " src ,
  18 .BI "                      char " dst "[restrict ." size "], socklen_t " size );
  19 .fi
  20 .SH DESCRIPTION
  21 This function converts the network address structure
  22 .I src
  23 in the
  24 .I af
  25 address family into a character string.
  26 The resulting string is copied to the buffer pointed to by
  27 .IR dst ,
  28 which must be a non-null pointer.
  29 The caller specifies the number of bytes available in this buffer in
  30 the argument
  31 .IR size .
  32 .PP
  33 .BR inet_ntop ()
  34 extends the
  35 .BR inet_ntoa (3)
  36 function to support multiple address families,
  37 .BR inet_ntoa (3)
  38 is now considered to be deprecated in favor of
  39 .BR inet_ntop ().
  40 The following address families are currently supported:
  41 .TP
  42 .B AF_INET
  43 .I src
  44 points to a
  45 .I struct in_addr
  46 (in network byte order)
  47 which is converted to an IPv4 network address in
  48 the dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP".
  49 The buffer
  50 .I dst
  51 must be at least
  52 .B INET_ADDRSTRLEN
  53 bytes long.
  54 .TP
  55 .B AF_INET6
  56 .I src
  57 points to a
  58 .I struct in6_addr
  59 (in network byte order)
  60 which is converted to a representation of this address in the
  61 most appropriate IPv6 network address format for this address.
  62 The buffer
  63 .I dst
  64 must be at least
  65 .B INET6_ADDRSTRLEN
  66 bytes long.
  67 .SH RETURN VALUE
  68 On success,
  69 .BR inet_ntop ()
  70 returns a non-null pointer to
  71 .IR dst .
  72 NULL is returned if there was an error, with
  73 .I errno
  74 set to indicate the error.
  75 .SH ERRORS
  76 .TP
  77 .B EAFNOSUPPORT
  78 .I af
  79 was not a valid address family.
  80 .TP
  81 .B ENOSPC
  82 The converted address string would exceed the size given by
  83 .IR size .
  84 .SH ATTRIBUTES
  85 For an explanation of the terms used in this section, see
  86 .BR attributes (7).
  87 .ad l
  88 .nh
  89 .TS
  90 allbox;
  91 lbx lb lb
  92 l l l.
  93 Interface       Attribute       Value
  94 T{
  95 .BR inet_ntop ()
  96 T}      Thread safety   MT-Safe locale
  97 .TE
  98 .hy
  99 .ad
 100 .sp 1
 101 .SH STANDARDS
 102 POSIX.1-2008.
 103 .SH HISTORY
 104 POSIX.1-2001.
 105 .PP
 106 Note that RFC\ 2553 defines a prototype where the last argument
 107 .I size
 108 is of type
 109 .IR size_t .
 110 Many systems follow RFC\ 2553.
 111 glibc 2.0 and 2.1 have
 112 .IR size_t ,
 113 but 2.2 and later have
 114 .IR socklen_t .
 115 .\" 2.1.3: size_t, 2.1.91: socklen_t
 116 .SH BUGS
 117 .B AF_INET6
 118 converts IPv4-mapped IPv6 addresses into an IPv6 format.
 119 .SH EXAMPLES
 120 See
 121 .BR inet_pton (3).
 122 .SH SEE ALSO
 123 .BR getnameinfo (3),
 124 .BR inet (3),
 125 .BR inet_pton (3)