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

wcsrtombs.3p (5127B)


  1. '\" et
  2. .TH WCSRTOMBS "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. wcsnrtombs, wcsrtombs
  12. \(em convert a wide-character string to a character string (restartable)
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <wchar.h>
  17. .P
  18. size_t wcsnrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP,
  19. size_t \fInwc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP);
  20. size_t wcsrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP,
  21. size_t \fIlen\fP, mbstate_t *restrict \fIps\fP);
  22. .fi
  23. .SH DESCRIPTION
  24. For
  25. \fIwcsrtombs\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. \fIwcsrtombs\fR()
  32. function shall convert a sequence of wide characters from the array
  33. indirectly pointed to by
  34. .IR src
  35. into a sequence of corresponding characters, beginning in the
  36. conversion state described by the object pointed to by
  37. .IR ps .
  38. If
  39. .IR dst
  40. is not a null pointer, the converted characters shall then be
  41. stored into the array pointed to by
  42. .IR dst .
  43. Conversion continues up to and including a terminating null wide
  44. character, which shall also be stored. Conversion shall stop
  45. earlier in the following cases:
  46. .IP " *" 4
  47. When a code is reached that does not correspond to a valid character
  48. .IP " *" 4
  49. When the next character would exceed the limit of
  50. .IR len
  51. total bytes to be stored in the array pointed to by
  52. .IR dst
  53. (and
  54. .IR dst
  55. is not a null pointer)
  56. .P
  57. Each conversion shall take place as if by a call to the
  58. \fIwcrtomb\fR()
  59. function.
  60. .P
  61. If
  62. .IR dst
  63. is not a null pointer, the pointer object pointed to by
  64. .IR src
  65. shall be assigned either a null pointer (if conversion stopped due to
  66. reaching a terminating null wide character) or the address just past
  67. the last wide character converted (if any). If conversion stopped due
  68. to reaching a terminating null wide character, the resulting state
  69. described shall be the initial conversion state.
  70. .P
  71. If
  72. .IR ps
  73. is a null pointer, the
  74. \fIwcsrtombs\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. \fIwcsnrtombs\fR()
  87. and
  88. \fIwcsrtombs\fR()
  89. functions need not be thread-safe if called with a NULL
  90. .IR ps
  91. argument.
  92. .P
  93. The
  94. \fIwcsnrtombs\fR()
  95. function shall be equivalent to the
  96. \fIwcsrtombs\fR()
  97. function, except that the conversion is limited to the first
  98. .IR nwc
  99. wide characters.
  100. .P
  101. The
  102. \fIwcsrtombs\fR()
  103. function shall not change the setting of
  104. .IR errno
  105. if successful.
  106. .P
  107. The behavior of these functions shall be affected by the
  108. .IR LC_CTYPE
  109. category of the current locale.
  110. .P
  111. The implementation shall behave as if no function defined in System Interfaces volume of POSIX.1\(hy2017
  112. calls these functions.
  113. .SH "RETURN VALUE"
  114. If conversion stops because a code is reached that does not correspond
  115. to a valid character, an encoding error occurs. In this case, these
  116. functions shall store the value of the macro
  117. .BR [EILSEQ]
  118. in
  119. .IR errno
  120. and return (\fBsize_t\fP)\-1; the conversion state is undefined.
  121. Otherwise, these functions shall return the number of bytes in the
  122. resulting character sequence, not including the terminating null (if any).
  123. .SH ERRORS
  124. These functions shall fail if:
  125. .TP
  126. .BR EILSEQ
  127. A wide-character code does not correspond to a valid character.
  128. .P
  129. These functions may fail if:
  130. .TP
  131. .BR EINVAL
  132. .IR ps
  133. points to an object that contains an invalid conversion state.
  134. .LP
  135. .IR "The following sections are informative."
  136. .SH EXAMPLES
  137. None.
  138. .SH "APPLICATION USAGE"
  139. None.
  140. .SH RATIONALE
  141. None.
  142. .SH "FUTURE DIRECTIONS"
  143. None.
  144. .SH "SEE ALSO"
  145. .IR "\fImbsinit\fR\^(\|)",
  146. .IR "\fIwcrtomb\fR\^(\|)"
  147. .P
  148. The Base Definitions volume of POSIX.1\(hy2017,
  149. .IR "\fB<wchar.h>\fP"
  150. .\"
  151. .SH COPYRIGHT
  152. Portions of this text are reprinted and reproduced in electronic form
  153. from IEEE Std 1003.1-2017, Standard for Information Technology
  154. -- Portable Operating System Interface (POSIX), The Open Group Base
  155. Specifications Issue 7, 2018 Edition,
  156. Copyright (C) 2018 by the Institute of
  157. Electrical and Electronics Engineers, Inc and The Open Group.
  158. In the event of any discrepancy between this version and the original IEEE and
  159. The Open Group Standard, the original IEEE and The Open Group Standard
  160. is the referee document. The original Standard can be obtained online at
  161. http://www.opengroup.org/unix/online.html .
  162. .PP
  163. Any typographical or formatting errors that appear
  164. in this page are most likely
  165. to have been introduced during the conversion of the source files to
  166. man page format. To report such errors, see
  167. https://www.kernel.org/doc/man-pages/reporting_bugs.html .