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

iconv.3p (7780B)


  1. '\" et
  2. .TH ICONV "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. iconv
  12. \(em codeset conversion function
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <iconv.h>
  17. .P
  18. size_t iconv(iconv_t \fIcd\fP, char **restrict \fIinbuf\fP,
  19. size_t *restrict \fIinbytesleft\fP, char **restrict \fIoutbuf\fP,
  20. size_t *restrict \fIoutbytesleft\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIiconv\fR()
  25. function shall convert the sequence of characters from one codeset,
  26. in the array specified by
  27. .IR inbuf ,
  28. into a sequence of corresponding characters in another codeset, in the
  29. array specified by
  30. .IR outbuf .
  31. The codesets are those specified in the
  32. \fIiconv_open\fR()
  33. call that returned the conversion descriptor,
  34. .IR cd .
  35. The
  36. .IR inbuf
  37. argument points to a variable that points to the first character in the
  38. input buffer and
  39. .IR inbytesleft
  40. indicates the number of bytes to the end of the buffer to be
  41. converted. The
  42. .IR outbuf
  43. argument points to a variable that points to the first available byte
  44. in the output buffer and
  45. .IR outbytesleft
  46. indicates the number of the available bytes to the end of the buffer.
  47. .P
  48. For state-dependent encodings, the conversion descriptor
  49. .IR cd
  50. is placed into its initial shift state by a call for which
  51. .IR inbuf
  52. is a null pointer, or for which
  53. .IR inbuf
  54. points to a null pointer. When
  55. \fIiconv\fR()
  56. is called in this way, and if
  57. .IR outbuf
  58. is not a null pointer or a pointer to a null pointer, and
  59. .IR outbytesleft
  60. points to a positive value,
  61. \fIiconv\fR()
  62. shall place, into the output buffer, the byte sequence to change the
  63. output buffer to its initial shift state. If the output buffer is not
  64. large enough to hold the entire reset sequence,
  65. \fIiconv\fR()
  66. shall fail and set
  67. .IR errno
  68. to
  69. .BR [E2BIG] .
  70. Subsequent calls with
  71. .IR inbuf
  72. as other than a null pointer or a pointer to a null pointer cause the
  73. conversion to take place from the current state of the conversion
  74. descriptor.
  75. .P
  76. If a sequence of input bytes does not form a valid character in the
  77. specified codeset, conversion shall stop after the previous
  78. successfully converted character. If the input buffer ends with an
  79. incomplete character or shift sequence, conversion shall stop after the
  80. previous successfully converted bytes. If the output buffer is not
  81. large enough to hold the entire converted input, conversion shall stop
  82. just prior to the input bytes that would cause the output buffer to
  83. overflow. The variable pointed to by
  84. .IR inbuf
  85. shall be updated to point to the byte following the last byte
  86. successfully used in the conversion. The value pointed to by
  87. .IR inbytesleft
  88. shall be decremented to reflect the number of bytes still not converted
  89. in the input buffer. The variable pointed to by
  90. .IR outbuf
  91. shall be updated to point to the byte following the last byte of
  92. converted output data. The value pointed to by
  93. .IR outbytesleft
  94. shall be decremented to reflect the number of bytes still available in
  95. the output buffer. For state-dependent encodings, the conversion
  96. descriptor shall be updated
  97. to reflect the shift state in effect at the end of the last
  98. successfully converted byte sequence.
  99. .P
  100. If
  101. \fIiconv\fR()
  102. encounters a character in the input buffer that is valid, but for which
  103. an identical character does not exist in the target codeset,
  104. \fIiconv\fR()
  105. shall perform an implementation-defined conversion on this character.
  106. .SH "RETURN VALUE"
  107. The
  108. \fIiconv\fR()
  109. function shall update the variables pointed to by the arguments to
  110. reflect the extent of the conversion and return the number of
  111. non-identical conversions performed. If the entire string in the input
  112. buffer is converted, the value pointed to by
  113. .IR inbytesleft
  114. shall be 0. If the input conversion is stopped due to any conditions
  115. mentioned above, the value pointed to by
  116. .IR inbytesleft
  117. shall be non-zero and
  118. .IR errno
  119. shall be set to indicate the condition. If an error occurs,
  120. \fIiconv\fR()
  121. shall return (\fBsize_t\fP)\-1 and set
  122. .IR errno
  123. to indicate the error.
  124. .SH ERRORS
  125. The
  126. \fIiconv\fR()
  127. function shall fail if:
  128. .TP
  129. .BR EILSEQ
  130. Input conversion stopped due to an input byte that does not belong to
  131. the input codeset.
  132. .TP
  133. .BR E2BIG
  134. Input conversion stopped due to lack of space in the output buffer.
  135. .TP
  136. .BR EINVAL
  137. Input conversion stopped due to an incomplete character or shift
  138. sequence at the end of the input buffer.
  139. .P
  140. The
  141. \fIiconv\fR()
  142. function may fail if:
  143. .TP
  144. .BR EBADF
  145. The
  146. .IR cd
  147. argument is not a valid open conversion descriptor.
  148. .LP
  149. .IR "The following sections are informative."
  150. .SH EXAMPLES
  151. None.
  152. .SH "APPLICATION USAGE"
  153. The
  154. .IR inbuf
  155. argument indirectly points to the memory area which contains the
  156. conversion input data. The
  157. .IR outbuf
  158. argument indirectly points to the memory area which is to contain the
  159. result of the conversion. The objects indirectly pointed to by
  160. .IR inbuf
  161. and
  162. .IR outbuf
  163. are not restricted to containing data that is directly representable in
  164. the ISO\ C standard language
  165. .BR char
  166. data type. The type of
  167. .IR inbuf
  168. and
  169. .IR outbuf ,
  170. .BR "char **" ,
  171. does not imply that the objects pointed to are interpreted as
  172. null-terminated C strings or arrays of characters. Any interpretation
  173. of a byte sequence that represents a character in a given character set
  174. encoding scheme is done internally within the codeset converters. For
  175. example, the area pointed to indirectly by
  176. .IR inbuf
  177. and/or
  178. .IR outbuf
  179. can contain all zero octets that are not interpreted as string
  180. terminators but as coded character data according to the respective
  181. codeset encoding scheme. The type of the data (\c
  182. .BR char ,
  183. .BR short ,
  184. .BR long ,
  185. and so on) read or stored in the objects is not specified, but may be
  186. inferred for both the input and output data by the converters
  187. determined by the
  188. .IR fromcode
  189. and
  190. .IR tocode
  191. arguments of
  192. \fIiconv_open\fR().
  193. .P
  194. Regardless of the data type inferred by the converter, the size of the
  195. remaining space in both input and output objects (the
  196. .IR intbytesleft
  197. and
  198. .IR outbytesleft
  199. arguments) is always measured in bytes.
  200. .P
  201. For implementations that support the conversion of state-dependent
  202. encodings, the conversion descriptor must be able to accurately reflect
  203. the shift-state in effect at the end of the last successful
  204. conversion. It is not required that the conversion descriptor itself
  205. be updated, which would require it to be a pointer type. Thus,
  206. implementations are free to implement the descriptor as a handle (other
  207. than a pointer type) by which the conversion information can be
  208. accessed and updated.
  209. .SH RATIONALE
  210. None.
  211. .SH "FUTURE DIRECTIONS"
  212. None.
  213. .SH "SEE ALSO"
  214. .IR "\fIiconv_open\fR\^(\|)",
  215. .IR "\fIiconv_close\fR\^(\|)",
  216. .IR "\fImbsrtowcs\fR\^(\|)"
  217. .P
  218. The Base Definitions volume of POSIX.1\(hy2017,
  219. .IR "\fB<iconv.h>\fP"
  220. .\"
  221. .SH COPYRIGHT
  222. Portions of this text are reprinted and reproduced in electronic form
  223. from IEEE Std 1003.1-2017, Standard for Information Technology
  224. -- Portable Operating System Interface (POSIX), The Open Group Base
  225. Specifications Issue 7, 2018 Edition,
  226. Copyright (C) 2018 by the Institute of
  227. Electrical and Electronics Engineers, Inc and The Open Group.
  228. In the event of any discrepancy between this version and the original IEEE and
  229. The Open Group Standard, the original IEEE and The Open Group Standard
  230. is the referee document. The original Standard can be obtained online at
  231. http://www.opengroup.org/unix/online.html .
  232. .PP
  233. Any typographical or formatting errors that appear
  234. in this page are most likely
  235. to have been introduced during the conversion of the source files to
  236. man page format. To report such errors, see
  237. https://www.kernel.org/doc/man-pages/reporting_bugs.html .