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

wcsxfrm.3p (4500B)

    

  1. '\" et
  2. .TH WCSXFRM "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. wcsxfrm,
  12. wcsxfrm_l
  13. \(em wide-character string transformation
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <wchar.h>
  18. .P
  19. size_t wcsxfrm(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP,
  20.     size_t \fIn\fP);
  21. size_t wcsxfrm_l(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP,
  22.     size_t \fIn\fP, locale_t \fIlocale\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. For
  26. \fIwcsxfrm\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. \fIwcsxfrm\fR()
  33. and
  34. \fIwcsxfrm_l\fR()
  35. functions shall transform the wide-character string pointed to by
  36. .IR ws2
  37. and place the resulting wide-character string into the array pointed to
  38. by
  39. .IR ws1 .
  40. The transformation shall be such that if
  41. \fIwcscmp\fR()
  42. is applied to two transformed wide strings, it shall return a value
  43. greater than, equal to, or less than 0, corresponding to the result of
  44. \fIwcscoll\fR()
  45. and
  46. \fIwcscoll_l\fR()
  47. applied to the same two original wide-character strings, and the same
  48. .IR LC_COLLATE
  49. category of the current locale
  50. or the locale object
  51. .IR locale ,
  52. respectively. No more than
  53. .IR n
  54. wide-character codes shall be placed into the resulting array pointed
  55. to by
  56. .IR ws1 ,
  57. including the terminating null wide-character code. If
  58. .IR n
  59. is 0,
  60. .IR ws1
  61. is permitted to be a null pointer. If copying takes place between
  62. objects that overlap, the behavior is undefined.
  63. .P
  64. The
  65. \fIwcsxfrm\fR()
  66. and
  67. \fIwcsxfrm_l\fR()
  68. functions shall not change the setting of
  69. .IR errno
  70. if successful.
  71. .P
  72. Since no return value is reserved to indicate an error, an
  73. application wishing to check for error situations should set
  74. .IR errno
  75. to 0, then call
  76. \fIwcsxfrm\fR()
  77. or
  78. \fIwcsxfrm_l\fR(),
  79. then check
  80. .IR errno .
  81. .P
  82. The behavior is undefined if the
  83. .IR locale
  84. argument to
  85. \fIwcsxfrm_l\fR()
  86. is the special locale object LC_GLOBAL_LOCALE or is not a valid locale
  87. object handle.
  88. .SH "RETURN VALUE"
  89. The
  90. \fIwcsxfrm\fR()
  91. and
  92. \fIwcsxfrm_l\fR()
  93. functions shall return the length of the transformed wide-character
  94. string (not including the terminating null wide-character code). If the
  95. value returned is
  96. .IR n
  97. or more, the contents of the array pointed to by
  98. .IR ws1
  99. are unspecified.
  100. .P
  101. On error, the
  102. \fIwcsxfrm\fR()
  103. and
  104. \fIwcsxfrm_l\fR()
  105. functions may set
  106. .IR errno ,
  107. but no return value is reserved to indicate an error.
  108. .SH ERRORS
  109. These functions may fail if:
  110. .TP
  111. .BR EINVAL
  112. The wide-character string pointed to by
  113. .IR ws2
  114. contains wide-character codes outside the domain of the collating
  115. sequence.
  116. .LP
  117. .IR "The following sections are informative."
  118. .SH EXAMPLES
  119. None.
  120. .SH "APPLICATION USAGE"
  121. The transformation function is such that two transformed wide-character
  122. strings can be ordered by
  123. \fIwcscmp\fR()
  124. as appropriate to collating sequence information in the current locale
  125. (category
  126. .IR LC_COLLATE ).
  127. .P
  128. The fact that when
  129. .IR n
  130. is 0
  131. .IR ws1
  132. is permitted to be a null pointer is useful to determine the size of
  133. the
  134. .IR ws1
  135. array prior to making the transformation.
  136. .SH RATIONALE
  137. None.
  138. .SH "FUTURE DIRECTIONS"
  139. None.
  140. .SH "SEE ALSO"
  141. .IR "\fIwcscmp\fR\^(\|)",
  142. .IR "\fIwcscoll\fR\^(\|)"
  143. .P
  144. The Base Definitions volume of POSIX.1\(hy2017,
  145. .IR "\fB<wchar.h>\fP"
  146. .\"
  147. .SH COPYRIGHT
  148. Portions of this text are reprinted and reproduced in electronic form
  149. from IEEE Std 1003.1-2017, Standard for Information Technology
  150. -- Portable Operating System Interface (POSIX), The Open Group Base
  151. Specifications Issue 7, 2018 Edition,
  152. Copyright (C) 2018 by the Institute of
  153. Electrical and Electronics Engineers, Inc and The Open Group.
  154. In the event of any discrepancy between this version and the original IEEE and
  155. The Open Group Standard, the original IEEE and The Open Group Standard
  156. is the referee document. The original Standard can be obtained online at
  157. http://www.opengroup.org/unix/online.html .
  158. .PP
  159. Any typographical or formatting errors that appear
  160. in this page are most likely
  161. to have been introduced during the conversion of the source files to
  162. man page format. To report such errors, see
  163. https://www.kernel.org/doc/man-pages/reporting_bugs.html .