logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

inet_ntop.3p (5418B)


  1. '\" et
  2. .TH INET_NTOP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. inet_ntop,
  12. inet_pton
  13. \(em convert IPv4 and IPv6 addresses between binary and text form
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <arpa/inet.h>
  18. .P
  19. const char *inet_ntop(int \fIaf\fP, const void *restrict \fIsrc\fP,
  20. char *restrict \fIdst\fP, socklen_t \fIsize\fP);
  21. int inet_pton(int \fIaf\fP, const char *restrict \fIsrc\fP, void *restrict \fIdst\fP);
  22. .fi
  23. .SH DESCRIPTION
  24. The
  25. \fIinet_ntop\fR()
  26. function shall convert a numeric address into a text string suitable
  27. for presentation. The
  28. .IR af
  29. argument shall specify the family of the address. This can be AF_INET
  30. or AF_INET6.
  31. The
  32. .IR src
  33. argument points to a buffer holding an IPv4 address if the
  34. .IR af
  35. argument is AF_INET,
  36. or an IPv6 address if the
  37. .IR af
  38. argument is AF_INET6;
  39. the address must be in network byte order. The
  40. .IR dst
  41. argument points to a buffer where the function stores the resulting
  42. text string; it shall not be NULL. The
  43. .IR size
  44. argument specifies the size of this buffer, which shall be large enough
  45. to hold the text string (INET_ADDRSTRLEN characters for IPv4,
  46. INET6_ADDRSTRLEN characters for IPv6).
  47. .P
  48. The
  49. \fIinet_pton\fR()
  50. function shall convert an address in its standard text presentation
  51. form into its numeric binary form. The
  52. .IR af
  53. argument shall specify the family of the address. The AF_INET
  54. and AF_INET6
  55. address families shall be supported. The
  56. .IR src
  57. argument points to the string being passed in. The
  58. .IR dst
  59. argument points to a buffer into which the function stores the numeric
  60. address; this shall be large enough to hold the numeric address (32 bits
  61. for AF_INET,
  62. 128 bits for AF_INET6).
  63. .P
  64. If the
  65. .IR af
  66. argument of
  67. \fIinet_pton\fR()
  68. is AF_INET, the
  69. .IR src
  70. string shall be in the standard IPv4 dotted-decimal form:
  71. .sp
  72. .RS 4
  73. .nf
  74. ddd.ddd.ddd.ddd
  75. .fi
  76. .P
  77. .RE
  78. .P
  79. where
  80. .BR \(dqddd\(dq
  81. is a one to three digit decimal number between 0 and 255 (see
  82. .IR "\fIinet_addr\fR\^(\|)").
  83. The
  84. \fIinet_pton\fR()
  85. function does not accept other formats (such as the octal numbers,
  86. hexadecimal numbers, and fewer than four numbers that
  87. \fIinet_addr\fR()
  88. accepts).
  89. .P
  90. If the
  91. .IR af
  92. argument of
  93. \fIinet_pton\fR()
  94. is AF_INET6, the
  95. .IR src
  96. string shall be in one of the following standard IPv6 text forms:
  97. .IP " 1." 4
  98. The preferred form is
  99. .BR \(dqx:x:x:x:x:x:x:x\(dq ,
  100. where the
  101. .BR 'x' s
  102. are the hexadecimal values of the eight 16-bit pieces of the address.
  103. Leading zeros in individual fields can be omitted, but there shall be
  104. one to four hexadecimal digits in every field.
  105. .IP " 2." 4
  106. A string of contiguous zero fields in the preferred form can be shown
  107. as
  108. .BR \(dq::\(dq .
  109. The
  110. .BR \(dq::\(dq
  111. can only appear once in an address. Unspecified addresses (\c
  112. .BR \(dq0:0:0:0:0:0:0:0\(dq )
  113. may be represented simply as
  114. .BR \(dq::\(dq .
  115. .IP " 3." 4
  116. A third form that is sometimes more convenient when dealing with a
  117. mixed environment of IPv4 and IPv6 nodes is
  118. .BR \(dqx:x:x:x:x:x:d.d.d.d\(dq ,
  119. where the
  120. .BR 'x' s
  121. are the hexadecimal values of the six high-order 16-bit pieces of the
  122. address, and the
  123. .BR 'd' s
  124. are the decimal values of the four low-order 8-bit pieces of the
  125. address (standard IPv4 representation).
  126. .TP 10
  127. .BR Note:
  128. A more extensive description of the standard representations of IPv6
  129. addresses can be found in RFC\ 2373.
  130. .P
  131. .SH "RETURN VALUE"
  132. The
  133. \fIinet_ntop\fR()
  134. function shall return a pointer to the buffer containing the text
  135. string if the conversion succeeds, and NULL otherwise, and set
  136. .IR errno
  137. to indicate the error.
  138. .P
  139. The
  140. \fIinet_pton\fR()
  141. function shall return 1 if the conversion succeeds, with the address
  142. pointed to by
  143. .IR dst
  144. in network byte order. It shall return 0 if the input is not a valid
  145. IPv4 dotted-decimal string
  146. or a valid IPv6 address string,
  147. or \-1 with
  148. .IR errno
  149. set to
  150. .BR [EAFNOSUPPORT]
  151. if the
  152. .IR af
  153. argument is unknown.
  154. .SH ERRORS
  155. The
  156. \fIinet_ntop\fR()
  157. and
  158. \fIinet_pton\fR()
  159. functions shall fail if:
  160. .TP
  161. .BR EAFNOSUPPORT
  162. .br
  163. The
  164. .IR af
  165. argument is invalid.
  166. .TP
  167. .BR ENOSPC
  168. The size of the
  169. \fIinet_ntop\fR()
  170. result buffer is inadequate.
  171. .LP
  172. .IR "The following sections are informative."
  173. .SH "EXAMPLES"
  174. None.
  175. .SH "APPLICATION USAGE"
  176. None.
  177. .SH "RATIONALE"
  178. None.
  179. .SH "FUTURE DIRECTIONS"
  180. None.
  181. .SH "SEE ALSO"
  182. The Base Definitions volume of POSIX.1\(hy2017,
  183. .IR "\fB<arpa_inet.h>\fP"
  184. .\"
  185. .SH COPYRIGHT
  186. Portions of this text are reprinted and reproduced in electronic form
  187. from IEEE Std 1003.1-2017, Standard for Information Technology
  188. -- Portable Operating System Interface (POSIX), The Open Group Base
  189. Specifications Issue 7, 2018 Edition,
  190. Copyright (C) 2018 by the Institute of
  191. Electrical and Electronics Engineers, Inc and The Open Group.
  192. In the event of any discrepancy between this version and the original IEEE and
  193. The Open Group Standard, the original IEEE and The Open Group Standard
  194. is the referee document. The original Standard can be obtained online at
  195. http://www.opengroup.org/unix/online.html .
  196. .PP
  197. Any typographical or formatting errors that appear
  198. in this page are most likely
  199. to have been introduced during the conversion of the source files to
  200. man page format. To report such errors, see
  201. https://www.kernel.org/doc/man-pages/reporting_bugs.html .