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

strerror.3p (8491B)


  1. '\" et
  2. .TH STRERROR "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. strerror,
  12. strerror_l,
  13. strerror_r
  14. \(em get error message string
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <string.h>
  19. .P
  20. char *strerror(int \fIerrnum\fR);
  21. char *strerror_l(int \fIerrnum\fR, locale_t \fIlocale\fR);
  22. int strerror_r(int \fIerrnum\fR, char *\fIstrerrbuf\fR, size_t \fIbuflen\fR);
  23. .fi
  24. .SH DESCRIPTION
  25. For
  26. \fIstrerror\fR():
  27. The functionality described on this reference page is aligned with the
  28. ISO\ C standard. Any conflict between the requirements described here and the
  29. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  30. .P
  31. The
  32. \fIstrerror\fR()
  33. function shall map the error number in
  34. .IR errnum
  35. to a locale-dependent error message string and shall return a pointer
  36. to it. Typically, the values for
  37. .IR errnum
  38. come from
  39. .IR errno ,
  40. but
  41. \fIstrerror\fR()
  42. shall map any value of type
  43. .BR int
  44. to a message.
  45. .P
  46. The application shall not modify the string returned.
  47. The returned string pointer might be invalidated or
  48. the string content might be overwritten by a subsequent call to
  49. \fIstrerror\fR(),
  50. or by a subsequent call to
  51. \fIstrerror_l\fR()
  52. in the same thread. The returned pointer and the string content might
  53. also be invalidated if the calling thread is terminated.
  54. .P
  55. The string may be overwritten by a subsequent call to
  56. \fIstrerror_l\fR()
  57. in the same thread.
  58. .P
  59. The contents of the error message strings returned by
  60. \fIstrerror\fR()
  61. should be determined by the setting of the
  62. .IR LC_MESSAGES
  63. category in the current locale.
  64. .P
  65. The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017
  66. calls
  67. \fIstrerror\fR().
  68. .P
  69. The
  70. \fIstrerror\fR()
  71. and
  72. \fIstrerror_l\fR()
  73. functions shall not change the setting of
  74. .IR errno
  75. if successful.
  76. .P
  77. Since no return value is reserved to indicate an error of
  78. \fIstrerror\fR(),
  79. an application wishing to check for error situations should set
  80. .IR errno
  81. to 0, then call
  82. \fIstrerror\fR(),
  83. then check
  84. .IR errno .
  85. Similarly, since
  86. \fIstrerror_l\fR()
  87. is required to return a string for some errors, an application wishing
  88. to check for all error situations should set
  89. .IR errno
  90. to 0, then call
  91. \fIstrerror_l\fR(),
  92. then check
  93. .IR errno .
  94. .P
  95. The
  96. \fIstrerror\fR()
  97. function need not be thread-safe.
  98. .P
  99. The
  100. \fIstrerror_l\fR()
  101. function shall map the error number in
  102. .IR errnum
  103. to a locale-dependent error message string in the locale represented by
  104. .IR locale
  105. and shall return a pointer to it.
  106. .P
  107. The
  108. \fIstrerror_r\fR()
  109. function shall map the error number in
  110. .IR errnum
  111. to a locale-dependent error message string and shall return the string
  112. in the buffer pointed to by
  113. .IR strerrbuf ,
  114. with length
  115. .IR buflen .
  116. .P
  117. If the value of
  118. .IR errnum
  119. is a valid error number, the message string shall indicate what error
  120. occurred; if the value of
  121. .IR errnum
  122. is zero, the message string shall either be an empty string or
  123. indicate that no error occurred; otherwise, if these functions complete
  124. successfully, the message string shall indicate that an unknown error
  125. occurred.
  126. .P
  127. The behavior is undefined if the
  128. .IR locale
  129. argument to
  130. \fIstrerror_l\fR()
  131. is the special locale object LC_GLOBAL_LOCALE or is not a valid locale
  132. object handle.
  133. .SH "RETURN VALUE"
  134. Upon completion, whether successful or not,
  135. \fIstrerror\fR()
  136. shall return a pointer to the generated message string.
  137. On error
  138. .IR errno
  139. may be set, but no return value is reserved to indicate an error.
  140. .P
  141. Upon successful completion,
  142. \fIstrerror_l\fR()
  143. shall return a pointer to the generated message string. If
  144. .IR errnum
  145. is not a valid error number,
  146. .IR errno
  147. may be set to
  148. .BR [EINVAL] ,
  149. but a pointer to a message string shall still be returned. If any other
  150. error occurs,
  151. .IR errno
  152. shall be set to indicate the error and a null pointer shall be
  153. returned.
  154. .P
  155. Upon successful completion,
  156. \fIstrerror_r\fR()
  157. shall return 0. Otherwise, an error number shall be returned to
  158. indicate the error.
  159. .SH ERRORS
  160. These functions may fail if:
  161. .TP
  162. .BR EINVAL
  163. The value of
  164. .IR errnum
  165. is neither a valid error number nor zero.
  166. .P
  167. The
  168. \fIstrerror_r\fR()
  169. function may fail if:
  170. .TP
  171. .BR ERANGE
  172. Insufficient storage was supplied via
  173. .IR strerrbuf
  174. and
  175. .IR buflen
  176. to contain the generated message string.
  177. .LP
  178. .IR "The following sections are informative."
  179. .SH EXAMPLES
  180. None.
  181. .SH "APPLICATION USAGE"
  182. Historically in some implementations, calls to
  183. \fIperror\fR()
  184. would overwrite the string that the pointer returned by
  185. \fIstrerror\fR()
  186. points to. Such implementations did not conform to the ISO\ C standard; however,
  187. application developers should be aware of this behavior if they wish
  188. their applications to be portable to such implementations.
  189. .SH RATIONALE
  190. The
  191. \fIstrerror_l\fR()
  192. function is required to be thread-safe, thereby eliminating the
  193. need for an equivalent to the
  194. \fIstrerror_r\fR()
  195. function.
  196. .P
  197. Earlier versions of this standard did not explicitly require that the
  198. error message strings returned by
  199. \fIstrerror\fR()
  200. and
  201. \fIstrerror_r\fR()
  202. provide any information about the error. This version of the standard
  203. requires a meaningful message for any successful completion.
  204. .P
  205. Since no return value is reserved to indicate a
  206. \fIstrerror\fR()
  207. error, but all calls (whether successful or not) must return a pointer
  208. to a message string, on error
  209. \fIstrerror\fR()
  210. can return a pointer to an empty string or a pointer to a meaningful
  211. string that can be printed.
  212. .P
  213. Note that the
  214. .BR [EINVAL]
  215. error condition is a may fail error. If an invalid error number is
  216. supplied as the value of
  217. .IR errnum ,
  218. applications should be prepared to handle any of the following:
  219. .IP " 1." 4
  220. Error (with no meaningful message):
  221. .IR errno
  222. is set to
  223. .BR [EINVAL] ,
  224. the return value is a pointer to an empty string.
  225. .IP " 2." 4
  226. Successful completion:
  227. .IR errno
  228. is unchanged and the return value points to a string like
  229. .BR \(dqunknown error\(dq
  230. or
  231. .BR \(dqerror number xxx\(dq
  232. (where
  233. .IR xxx
  234. is the value of
  235. .IR errnum ).
  236. .IP " 3." 4
  237. Combination of #1 and #2:
  238. .IR errno
  239. is set to
  240. .BR [EINVAL]
  241. and the return value points to a string like
  242. .BR \(dqunknown error\(dq
  243. or
  244. .BR \(dqerror number xxx\(dq
  245. (where
  246. .IR xxx
  247. is the value of
  248. .IR errnum ).
  249. Since applications frequently use the return value of
  250. \fIstrerror\fR()
  251. as an argument to functions like
  252. \fIfprintf\fR()
  253. (without checking the return value) and since applications have no way
  254. to parse an error message string to determine whether
  255. .IR errnum
  256. represents a valid error number, implementations are encouraged to
  257. implement #3. Similarly, implementations are encouraged to have
  258. \fIstrerror_r\fR()
  259. return
  260. .BR [EINVAL]
  261. and put a string like
  262. .BR \(dqunknown error\(dq
  263. or
  264. .BR \(dqerror number xxx\(dq
  265. in the buffer pointed to by
  266. .IR strerrbuf
  267. when the value of
  268. .IR errnum
  269. is not a valid error number.
  270. .P
  271. Some applications rely on being able to set
  272. .IR errno
  273. to 0 before calling a function with no reserved value to indicate an
  274. error, then call
  275. .IR strerror ( errno )
  276. afterwards to detect whether an error occurred (because
  277. .IR errno
  278. changed) or to indicate success (because
  279. .IR errno
  280. remained zero). This usage pattern requires that
  281. .IR strerror (0)
  282. succeed with useful results. Previous versions of the standard did not
  283. specify the behavior when
  284. .IR errnum
  285. is zero.
  286. .SH "FUTURE DIRECTIONS"
  287. None.
  288. .SH "SEE ALSO"
  289. .IR "\fIperror\fR\^(\|)"
  290. .P
  291. The Base Definitions volume of POSIX.1\(hy2017,
  292. .IR "\fB<string.h>\fP"
  293. .\"
  294. .SH COPYRIGHT
  295. Portions of this text are reprinted and reproduced in electronic form
  296. from IEEE Std 1003.1-2017, Standard for Information Technology
  297. -- Portable Operating System Interface (POSIX), The Open Group Base
  298. Specifications Issue 7, 2018 Edition,
  299. Copyright (C) 2018 by the Institute of
  300. Electrical and Electronics Engineers, Inc and The Open Group.
  301. In the event of any discrepancy between this version and the original IEEE and
  302. The Open Group Standard, the original IEEE and The Open Group Standard
  303. is the referee document. The original Standard can be obtained online at
  304. http://www.opengroup.org/unix/online.html .
  305. .PP
  306. Any typographical or formatting errors that appear
  307. in this page are most likely
  308. to have been introduced during the conversion of the source files to
  309. man page format. To report such errors, see
  310. https://www.kernel.org/doc/man-pages/reporting_bugs.html .