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

strtoul.3p (6707B)


  1. '\" et
  2. .TH STRTOUL "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. strtoul,
  12. strtoull
  13. \(em convert a string to an unsigned long
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <stdlib.h>
  18. .P
  19. unsigned long strtoul(const char *restrict \fIstr\fP,
  20. char **restrict \fIendptr\fP, int \fIbase\fP);
  21. unsigned long long strtoull(const char *restrict \fIstr\fP,
  22. char **restrict \fIendptr\fP, int \fIbase\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The functionality described on this reference page is aligned with the
  26. ISO\ C standard. Any conflict between the requirements described here and the
  27. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  28. .P
  29. These functions shall convert the initial portion of the string pointed
  30. to by
  31. .IR str
  32. to a type
  33. .BR "unsigned long"
  34. and
  35. .BR "unsigned long long"
  36. representation, respectively. First, they decompose the input string
  37. into three parts:
  38. .IP " 1." 4
  39. An initial, possibly empty, sequence of white-space characters (as
  40. specified by
  41. \fIisspace\fR())
  42. .IP " 2." 4
  43. A subject sequence interpreted as an integer represented in some radix
  44. determined by the value of
  45. .IR base
  46. .IP " 3." 4
  47. A final string of one or more unrecognized characters, including
  48. the terminating NUL character of the input string
  49. .P
  50. Then they shall attempt to convert the subject sequence to an
  51. unsigned integer, and return the result.
  52. .P
  53. If the value of
  54. .IR base
  55. is 0, the expected form of the subject sequence is that of a decimal
  56. constant, octal constant, or hexadecimal constant, any of which may be
  57. preceded by a
  58. .BR '+'
  59. or
  60. .BR '\-'
  61. sign. A decimal constant begins with a non-zero digit, and consists of
  62. a sequence of decimal digits. An octal constant consists of the prefix
  63. .BR '0'
  64. optionally followed by a sequence of the digits
  65. .BR '0'
  66. to
  67. .BR '7'
  68. only. A hexadecimal constant consists of the prefix 0x or 0X followed
  69. by a sequence of the decimal digits and letters
  70. .BR 'a'
  71. (or
  72. .BR 'A' )
  73. to
  74. .BR 'f'
  75. (or
  76. .BR 'F' )
  77. with values 10 to 15 respectively.
  78. .P
  79. If the value of
  80. .IR base
  81. is between 2 and 36, the expected form of the subject sequence is a
  82. sequence of letters and digits representing an integer with the radix
  83. specified by
  84. .IR base ,
  85. optionally preceded by a
  86. .BR '+'
  87. or
  88. .BR '\-'
  89. sign. The letters from
  90. .BR 'a'
  91. (or
  92. .BR 'A' )
  93. to
  94. .BR 'z'
  95. (or
  96. .BR 'Z' )
  97. inclusive are ascribed the values 10 to 35; only letters whose ascribed
  98. values are less than that of
  99. .IR base
  100. are permitted. If the value of
  101. .IR base
  102. is 16, the characters 0x or 0X may optionally precede the sequence of
  103. letters and digits, following the sign if present.
  104. .P
  105. The subject sequence is defined as the longest initial subsequence of
  106. the input string, starting with the first non-white-space character
  107. that is of the expected form. The subject sequence shall contain no
  108. characters if the input string is empty or consists entirely of
  109. white-space characters, or if the first non-white-space character is
  110. other than a sign or a permissible letter or digit.
  111. .P
  112. If the subject sequence has the expected form and the value of
  113. .IR base
  114. is 0, the sequence of characters starting with the first digit shall be
  115. interpreted as an integer constant. If the subject sequence has the
  116. expected form and the value of
  117. .IR base
  118. is between 2 and 36, it shall be used as the base for conversion,
  119. ascribing to each letter its value as given above. If the subject
  120. sequence begins with a
  121. <hyphen-minus>,
  122. the value resulting from the
  123. conversion shall be negated. A pointer to the final string shall be
  124. stored in the object pointed to by
  125. .IR endptr ,
  126. provided that
  127. .IR endptr
  128. is not a null pointer.
  129. .P
  130. In other than the C
  131. or POSIX
  132. locale, additional locale-specific subject sequence forms may be
  133. accepted.
  134. .P
  135. If the subject sequence is empty or does not have the expected form, no
  136. conversion shall be performed; the value of
  137. .IR str
  138. shall be stored in the object pointed to by
  139. .IR endptr ,
  140. provided that
  141. .IR endptr
  142. is not a null pointer.
  143. .P
  144. These functions shall not change the setting of
  145. .IR errno
  146. if successful.
  147. .P
  148. Since 0,
  149. {ULONG_MAX},
  150. and
  151. {ULLONG_MAX}
  152. are returned on error and are also valid returns on success, an
  153. application wishing to check for error situations should set
  154. .IR errno
  155. to 0, then call
  156. \fIstrtoul\fR()
  157. or
  158. \fIstrtoull\fR(),
  159. then check
  160. .IR errno .
  161. .SH "RETURN VALUE"
  162. Upon successful completion, these functions shall return the converted
  163. value, if any. If no conversion could be performed, 0 shall be returned
  164. and
  165. .IR errno
  166. may be set to
  167. .BR [EINVAL] .
  168. .P
  169. If the value of
  170. .IR base
  171. is not supported, 0 shall be returned and
  172. .IR errno
  173. shall be set to
  174. .BR [EINVAL] .
  175. .P
  176. If the correct value is outside the range of representable values,
  177. {ULONG_MAX}
  178. or
  179. {ULLONG_MAX}
  180. shall be returned and
  181. .IR errno
  182. set to
  183. .BR [ERANGE] .
  184. .SH ERRORS
  185. These functions shall fail if:
  186. .TP
  187. .BR EINVAL
  188. The value of
  189. .IR base
  190. is not supported.
  191. .TP
  192. .BR ERANGE
  193. The value to be returned is not representable.
  194. .P
  195. These functions may fail if:
  196. .TP
  197. .BR EINVAL
  198. No conversion could be performed.
  199. .LP
  200. .IR "The following sections are informative."
  201. .SH EXAMPLES
  202. None.
  203. .SH "APPLICATION USAGE"
  204. Since the value of
  205. .IR *endptr
  206. is unspecified if the value of
  207. .IR base
  208. is not supported, applications should either ensure that
  209. .IR base
  210. has a supported value (0 or between 2 and 36) before the call, or check
  211. for an
  212. .BR [EINVAL]
  213. error before examining
  214. .IR *endptr .
  215. .SH RATIONALE
  216. None.
  217. .SH "FUTURE DIRECTIONS"
  218. None.
  219. .SH "SEE ALSO"
  220. .IR "\fIfscanf\fR\^(\|)",
  221. .IR "\fIisalpha\fR\^(\|)",
  222. .IR "\fIstrtod\fR\^(\|)",
  223. .IR "\fIstrtol\fR\^(\|)"
  224. .P
  225. The Base Definitions volume of POSIX.1\(hy2017,
  226. .IR "\fB<stdlib.h>\fP"
  227. .\"
  228. .SH COPYRIGHT
  229. Portions of this text are reprinted and reproduced in electronic form
  230. from IEEE Std 1003.1-2017, Standard for Information Technology
  231. -- Portable Operating System Interface (POSIX), The Open Group Base
  232. Specifications Issue 7, 2018 Edition,
  233. Copyright (C) 2018 by the Institute of
  234. Electrical and Electronics Engineers, Inc and The Open Group.
  235. In the event of any discrepancy between this version and the original IEEE and
  236. The Open Group Standard, the original IEEE and The Open Group Standard
  237. is the referee document. The original Standard can be obtained online at
  238. http://www.opengroup.org/unix/online.html .
  239. .PP
  240. Any typographical or formatting errors that appear
  241. in this page are most likely
  242. to have been introduced during the conversion of the source files to
  243. man page format. To report such errors, see
  244. https://www.kernel.org/doc/man-pages/reporting_bugs.html .