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.1p (8990B)

    

  1. '\" et
  2. .TH ICONV "1P" 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
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. iconv \fB[\fR-cs\fB]\fR -f \fIfrommap\fR -t \fItomap \fB[\fIfile\fR...\fB]\fR
  17. .P
  18. iconv -f \fIfromcode \fB[\fR-cs\fB] [\fR-t \fItocode\fB] [\fIfile\fR...\fB]\fR
  19. .P
  20. iconv -t \fItocode \fB[\fR-cs\fB] [\fR-f \fIfromcode\fB] [\fIfile\fR...\fB]\fR
  21. .P
  22. iconv -l
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. .IR iconv
  27. utility shall convert the encoding of characters in
  28. .IR file
  29. from one codeset to another and write the results to standard output.
  30. .P
  31. When the options indicate that charmap files are used to specify the
  32. codesets (see OPTIONS), the codeset conversion shall be accomplished by
  33. performing a logical join on the symbolic character names in the two
  34. charmaps. The implementation need not support the use of charmap files
  35. for codeset conversion unless the POSIX2_LOCALEDEF symbol is defined on
  36. the system.
  37. .SH OPTIONS
  38. The
  39. .IR iconv
  40. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  41. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  42. .P
  43. The following options shall be supported:
  44. .IP "\fB\-c\fR" 10
  45. Omit any characters that are invalid in the codeset of the input file
  46. from the output. When
  47. .BR \-c
  48. is not used, the results of encountering invalid characters in the
  49. input stream (either those that are not characters in the codeset of
  50. the input file or that have no corresponding character in the codeset
  51. of the output file) shall be specified in the system documentation. The
  52. presence or absence of
  53. .BR \-c
  54. shall not affect the exit status of
  55. .IR iconv .
  56. .IP "\fB\-f\ \fIfromcodeset\fR" 10
  57. .br
  58. Identify the codeset of the input file. The implementation shall
  59. recognize the following two forms of the
  60. .IR fromcodeset
  61. option-argument:
  62. .RS 10 
  63. .IP "\fIfromcode\fR" 10
  64. The
  65. .IR fromcode
  66. option-argument must not contain a
  67. <slash>
  68. character. It shall be interpreted as the name of one of the codeset
  69. descriptions provided by the implementation in an unspecified
  70. format. Valid values of
  71. .IR fromcode
  72. are implementation-defined.
  73. .IP "\fIfrommap\fR" 10
  74. The
  75. .IR frommap
  76. option-argument must contain a
  77. <slash>
  78. character. It shall be interpreted as the pathname of a charmap file as
  79. defined in the Base Definitions volume of POSIX.1\(hy2017,
  80. .IR "Section 6.4" ", " "Character Set Description File".
  81. If the pathname does not represent a valid, readable charmap file,
  82. the results are undefined.
  83. .P
  84. If this option is omitted, the codeset of the current locale shall
  85. be used.
  86. .RE
  87. .IP "\fB\-l\fR" 10
  88. Write all supported
  89. .IR fromcode
  90. and
  91. .IR tocode
  92. values to standard output in an unspecified format.
  93. .IP "\fB\-s\fR" 10
  94. Suppress any messages written to standard error concerning invalid
  95. characters. When
  96. .BR \-s
  97. is not used, the results of encountering invalid characters in the
  98. input stream (either those that are not valid characters in the codeset
  99. of the input file or that have no corresponding character in the
  100. codeset of the output file) shall be specified in the system
  101. documentation. The presence or absence of
  102. .BR \-s
  103. shall not affect the exit status of
  104. .IR iconv .
  105. .IP "\fB\-t\ \fItocodeset\fR" 10
  106. Identify the codeset to be used for the output file. The implementation
  107. shall recognize the following two forms of the
  108. .IR tocodeset
  109. option-argument:
  110. .RS 10 
  111. .IP "\fItocode\fR" 10
  112. The semantics shall be equivalent to the
  113. .BR \-f
  114. .IR fromcode
  115. option.
  116. .IP "\fItomap\fR" 10
  117. The semantics shall be equivalent to the
  118. .BR \-f
  119. .IR frommap
  120. option.
  121. .P
  122. If this option is omitted, the codeset of the current locale shall be
  123. used.
  124. .RE
  125. .P
  126. If either
  127. .BR \-f
  128. or
  129. .BR \-t
  130. represents a charmap file, but the other does not (or is omitted), or
  131. both
  132. .BR \-f
  133. and
  134. .BR \-t
  135. are omitted, the results are undefined.
  136. .SH OPERANDS
  137. The following operand shall be supported:
  138. .IP "\fIfile\fR" 10
  139. A pathname of an input file. If no
  140. .IR file
  141. operands are specified, or if a
  142. .IR file
  143. operand is
  144. .BR '\-' ,
  145. the standard input shall be used.
  146. .SH STDIN
  147. The standard input shall be used only if no
  148. .IR file
  149. operands are specified, or if a
  150. .IR file
  151. operand is
  152. .BR '\-' .
  153. .SH "INPUT FILES"
  154. The input file shall be a text file.
  155. .SH "ENVIRONMENT VARIABLES"
  156. The following environment variables shall affect the execution of
  157. .IR iconv :
  158. .IP "\fILANG\fP" 10
  159. Provide a default value for the internationalization variables that are
  160. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  161. .IR "Section 8.2" ", " "Internationalization Variables"
  162. for the precedence of internationalization variables used to determine
  163. the values of locale categories.)
  164. .IP "\fILC_ALL\fP" 10
  165. If set to a non-empty string value, override the values of all the
  166. other internationalization variables.
  167. .IP "\fILC_CTYPE\fP" 10
  168. Determine the locale for the interpretation of sequences of bytes of
  169. text data as characters (for example, single-byte as opposed to
  170. multi-byte characters in arguments). During translation of the file,
  171. this variable is superseded by the use of the
  172. .IR fromcode
  173. option-argument.
  174. .IP "\fILC_MESSAGES\fP" 10
  175. .br
  176. Determine the locale that should be used to affect the format and
  177. contents of diagnostic messages written to standard error.
  178. .IP "\fINLSPATH\fP" 10
  179. Determine the location of message catalogs for the processing of
  180. .IR LC_MESSAGES .
  181. .SH "ASYNCHRONOUS EVENTS"
  182. Default.
  183. .SH STDOUT
  184. When the
  185. .BR \-l
  186. option is used, the standard output shall contain all supported
  187. .IR fromcode
  188. and
  189. .IR tocode
  190. values, written in an unspecified format.
  191. .P
  192. When the
  193. .BR \-l
  194. option is not used, the standard output shall contain the sequence of
  195. characters read from the input files, translated to the specified
  196. codeset. Nothing else shall be written to the standard output.
  197. .SH STDERR
  198. The standard error shall be used only for diagnostic messages.
  199. .SH "OUTPUT FILES"
  200. None.
  201. .SH "EXTENDED DESCRIPTION"
  202. None.
  203. .SH "EXIT STATUS"
  204. The following exit values shall be returned:
  205. .IP "\00" 6
  206. Successful completion.
  207. .IP >0 6
  208. An error occurred.
  209. .SH "CONSEQUENCES OF ERRORS"
  210. Default.
  211. .LP
  212. .IR "The following sections are informative."
  213. .SH "APPLICATION USAGE"
  214. The user must ensure that both charmap files use the same symbolic
  215. names for characters the two codesets have in common.
  216. .SH EXAMPLES
  217. The following example converts the contents of file
  218. .BR mail.x400
  219. from the ISO/IEC\ 6937:\|2001 standard codeset to the ISO/IEC\ 8859\(hy1:\|1998 standard codeset, and stores the results in
  220. file
  221. .BR mail.local :
  222. .sp
  223. .RS 4
  224. .nf
  226. iconv -f IS6937 -t IS8859 mail.x400 > mail.local
  227. .fi
  228. .P
  229. .RE
  230. .SH RATIONALE
  231. The
  232. .IR iconv
  233. utility can be used portably only when the user provides two charmap
  234. files as option-arguments. This is because a single charmap provided by
  235. the user cannot reliably be joined with the names in a system-provided
  236. character set description. The valid values for
  237. .IR fromcode
  238. and
  239. .IR tocode
  240. are implementation-defined and do not have to have any relation to
  241. the charmap mechanisms. As an aid to interactive users, the
  242. .BR \-l
  243. option was adopted from the Plan 9 operating system. It writes
  244. information concerning these implementation-defined values. The
  245. format is unspecified because there are many possible useful formats
  246. that could be chosen, such as a matrix of valid combinations of
  247. .IR fromcode
  248. and
  249. .IR tocode .
  250. The
  251. .BR \-l
  252. option is not intended for shell script usage; conforming applications
  253. will have to use charmaps.
  254. .P
  255. The
  256. .IR iconv
  257. utility may support the conversion between ASCII and EBCDIC-based
  258. encodings, but is not required to do so. In an XSI-compliant
  259. implementation, the
  260. .IR dd
  261. utility is the only method guaranteed to support conversion between
  262. these two character sets.
  263. .SH "FUTURE DIRECTIONS"
  264. None.
  265. .SH "SEE ALSO"
  266. .IR "\fIdd\fR\^",
  267. .IR "\fIgencat\fR\^"
  268. .P
  269. The Base Definitions volume of POSIX.1\(hy2017,
  270. .IR "Section 6.4" ", " "Character Set Description File",
  271. .IR "Chapter 8" ", " "Environment Variables",
  272. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  273. .\"
  274. .SH COPYRIGHT
  275. Portions of this text are reprinted and reproduced in electronic form
  276. from IEEE Std 1003.1-2017, Standard for Information Technology
  277. -- Portable Operating System Interface (POSIX), The Open Group Base
  278. Specifications Issue 7, 2018 Edition,
  279. Copyright (C) 2018 by the Institute of
  280. Electrical and Electronics Engineers, Inc and The Open Group.
  281. In the event of any discrepancy between this version and the original IEEE and
  282. The Open Group Standard, the original IEEE and The Open Group Standard
  283. is the referee document. The original Standard can be obtained online at
  284. http://www.opengroup.org/unix/online.html .
  285. .PP
  286. Any typographical or formatting errors that appear
  287. in this page are most likely
  288. to have been introduced during the conversion of the source files to
  289. man page format. To report such errors, see
  290. https://www.kernel.org/doc/man-pages/reporting_bugs.html .