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

mbsrtowcs.3p (6053B)


  1. '\" et
  2. .TH MBSRTOWCS "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. mbsnrtowcs, mbsrtowcs
  12. \(em convert a character string to a wide-character string (restartable)
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <wchar.h>
  17. .P
  18. size_t mbsnrtowcs(wchar_t *restrict \fIdst\fP, const char **restrict \fIsrc\fP,
  19. size_t \fInmc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP);
  20. size_t mbsrtowcs(wchar_t *restrict \fIdst\fP, const char **restrict \fIsrc\fP,
  21. size_t \fIlen\fP, mbstate_t *restrict \fIps\fP);
  22. .fi
  23. .SH DESCRIPTION
  24. For
  25. \fImbsrtowcs\fR():
  26. The functionality described on this reference page is aligned with the
  27. ISO\ C standard. Any conflict between the requirements described here and the
  28. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  29. .P
  30. The
  31. \fImbsrtowcs\fR()
  32. function shall convert a sequence of characters, beginning in the
  33. conversion state described by the object pointed to by
  34. .IR ps ,
  35. from the array indirectly pointed to by
  36. .IR src
  37. into a sequence of corresponding wide characters. If
  38. .IR dst
  39. is not a null pointer, the converted characters shall be stored into
  40. the array pointed to by
  41. .IR dst .
  42. Conversion continues up to and including a terminating null character,
  43. which shall also be stored. Conversion shall stop early in either of
  44. the following cases:
  45. .IP " *" 4
  46. A sequence of bytes is encountered that does not form a valid character.
  47. .IP " *" 4
  48. .IR len
  49. codes have been stored into the array pointed to by
  50. .IR dst
  51. (and
  52. .IR dst
  53. is not a null pointer).
  54. .P
  55. Each conversion shall take place as if by a call to the
  56. \fImbrtowc\fR()
  57. function.
  58. .P
  59. If
  60. .IR dst
  61. is not a null pointer, the pointer object pointed to by
  62. .IR src
  63. shall be assigned either a null pointer (if conversion stopped due to
  64. reaching a terminating null character) or the address just past the
  65. last character converted (if any). If conversion stopped due to
  66. reaching a terminating null character, and if
  67. .IR dst
  68. is not a null pointer, the resulting state described shall be the
  69. initial conversion state.
  70. .P
  71. If
  72. .IR ps
  73. is a null pointer, the
  74. \fImbsrtowcs\fR()
  75. function shall use its own internal
  76. .BR mbstate_t
  77. object, which is initialized at program start-up to the initial
  78. conversion state. Otherwise, the
  79. .BR mbstate_t
  80. object pointed to by
  81. .IR ps
  82. shall be used to completely describe the current conversion state of
  83. the associated character sequence.
  84. .P
  85. The
  86. \fImbsnrtowcs\fR()
  87. function shall be equivalent to the
  88. \fImbsrtowcs\fR()
  89. function, except that the conversion of characters indirectly
  90. pointed to by
  91. .IR src
  92. is limited to at most
  93. .IR nmc
  94. bytes (the size of the input buffer), and under conditions where
  95. \fImbsrtowcs\fR()
  96. would assign the address just past the last character converted (if any)
  97. to the pointer object pointed to by
  98. .IR src ,
  99. \fImbsnrtowcs\fR()
  100. shall instead assign the address just past the last byte processed
  101. (if any) to that pointer object. If the input buffer ends with an
  102. incomplete character, it is unspecified whether conversion stops at
  103. the end of the previous character (if any), or at the end of the input
  104. buffer. In the latter case, a subsequent call to
  105. \fImbsnrtowcs\fR()
  106. with an input buffer that starts with the remainder of the incomplete
  107. character shall correctly complete the conversion of that character.
  108. .P
  109. The behavior of these functions shall be affected by the
  110. .IR LC_CTYPE
  111. category of the current locale.
  112. .P
  113. The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017
  114. calls these functions.
  115. .P
  116. The
  117. \fImbsnrtowcs\fR()
  118. and
  119. \fImbsrtowcs\fR()
  120. functions need not be thread-safe if called with a NULL
  121. .IR ps
  122. argument.
  123. .P
  124. The
  125. \fImbsrtowcs\fR()
  126. function shall not change the setting of
  127. .IR errno
  128. if successful.
  129. .SH "RETURN VALUE"
  130. If the input conversion encounters a sequence of bytes that do not form
  131. a valid character, an encoding error occurs. In this case, these
  132. functions shall store the value of the macro
  133. .BR [EILSEQ]
  134. in
  135. .IR errno
  136. and shall return (\fBsize_t\fP)\-1; the conversion state is undefined.
  137. Otherwise, these functions shall return the number of characters
  138. successfully converted, not including the terminating null (if any).
  139. .SH ERRORS
  140. These functions shall fail if:
  141. .TP
  142. .BR EILSEQ
  143. An invalid character sequence is detected.
  144. In the POSIX locale an
  145. .BR [EILSEQ]
  146. error cannot occur since all byte values are valid characters.
  147. .P
  148. These functions may fail if:
  149. .TP
  150. .BR EINVAL
  151. .IR ps
  152. points to an object that contains an invalid conversion state.
  153. .LP
  154. .IR "The following sections are informative."
  155. .SH EXAMPLES
  156. None.
  157. .SH "APPLICATION USAGE"
  158. None.
  159. .SH RATIONALE
  160. None.
  161. .SH "FUTURE DIRECTIONS"
  162. A future version may require that when the input buffer ends with
  163. an incomplete character, conversion stops at the end of the input buffer.
  164. .SH "SEE ALSO"
  165. .IR "\fIiconv\fR\^(\|)",
  166. .IR "\fImbrtowc\fR\^(\|)",
  167. .IR "\fImbsinit\fR\^(\|)"
  168. .P
  169. The Base Definitions volume of POSIX.1\(hy2017,
  170. .IR "\fB<wchar.h>\fP"
  171. .\"
  172. .SH COPYRIGHT
  173. Portions of this text are reprinted and reproduced in electronic form
  174. from IEEE Std 1003.1-2017, Standard for Information Technology
  175. -- Portable Operating System Interface (POSIX), The Open Group Base
  176. Specifications Issue 7, 2018 Edition,
  177. Copyright (C) 2018 by the Institute of
  178. Electrical and Electronics Engineers, Inc and The Open Group.
  179. In the event of any discrepancy between this version and the original IEEE and
  180. The Open Group Standard, the original IEEE and The Open Group Standard
  181. is the referee document. The original Standard can be obtained online at
  182. http://www.opengroup.org/unix/online.html .
  183. .PP
  184. Any typographical or formatting errors that appear
  185. in this page are most likely
  186. to have been introduced during the conversion of the source files to
  187. man page format. To report such errors, see
  188. https://www.kernel.org/doc/man-pages/reporting_bugs.html .