diff options
Diffstat (limited to 'man-pages-posix-2013/man1p/iconv.1p')
| -rw-r--r-- | man-pages-posix-2013/man1p/iconv.1p | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man1p/iconv.1p b/man-pages-posix-2013/man1p/iconv.1p new file mode 100644 index 0000000..41b3b09 --- /dev/null +++ b/man-pages-posix-2013/man1p/iconv.1p @@ -0,0 +1,288 @@ +'\" et +.TH ICONV "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iconv +\(em codeset conversion +.SH SYNOPSIS +.LP +.nf +iconv \fB[\fR\(mics\fB]\fR \(mif \fIfrommap\fR \(mit \fItomap \fB[\fIfile\fR...\fB]\fR +.P +iconv \(mif \fIfromcode \fB[\fR\(mics\fB] [\fR\(mit \fItocode\fB] [\fIfile\fR...\fB]\fR +.P +iconv \(mit \fItocode \fB[\fR\(mics\fB] [\fR\(mif \fIfromcode\fB] [\fIfile\fR...\fB]\fR +.P +iconv \(mil +.fi +.SH DESCRIPTION +The +.IR iconv +utility shall convert the encoding of characters in +.IR file +from one codeset to another and write the results to standard output. +.P +When the options indicate that charmap files are used to specify the +codesets (see OPTIONS), the codeset conversion shall be accomplished by +performing a logical join on the symbolic character names in the two +charmaps. The implementation need not support the use of charmap files +for codeset conversion unless the POSIX2_LOCALEDEF symbol is defined on +the system. +.SH OPTIONS +The +.IR iconv +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fR" 10 +Omit any characters that are invalid in the codeset of the input file +from the output. When +.BR \(mic +is not used, the results of encountering invalid characters in the +input stream (either those that are not characters in the codeset of +the input file or that have no corresponding character in the codeset +of the output file) shall be specified in the system documentation. The +presence or absence of +.BR \(mic +shall not affect the exit status of +.IR iconv . +.IP "\fB\(mif\ \fIfromcodeset\fR" 10 +.br +Identify the codeset of the input file. The implementation shall +recognize the following two forms of the +.IR fromcodeset +option-argument: +.RS 10 +.IP "\fIfromcode\fR" 10 +The +.IR fromcode +option-argument must not contain a +<slash> +character. It shall be interpreted as the name of one of the codeset +descriptions provided by the implementation in an unspecified +format. Valid values of +.IR fromcode +are implementation-defined. +.IP "\fIfrommap\fR" 10 +The +.IR frommap +option-argument must contain a +<slash> +character. It shall be interpreted as the pathname of a charmap file as +defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File". +If the pathname does not represent a valid, readable charmap file, +the results are undefined. +.P +If this option is omitted, the codeset of the current locale shall +be used. +.RE +.IP "\fB\(mil\fR" 10 +Write all supported +.IR fromcode +and +.IR tocode +values to standard output in an unspecified format. +.IP "\fB\(mis\fR" 10 +Suppress any messages written to standard error concerning invalid +characters. When +.BR \(mis +is not used, the results of encountering invalid characters in the +input stream (either those that are not valid characters in the codeset +of the input file or that have no corresponding character in the +codeset of the output file) shall be specified in the system +documentation. The presence or absence of +.BR \(mis +shall not affect the exit status of +.IR iconv . +.IP "\fB\(mit\ \fItocodeset\fR" 10 +Identify the codeset to be used for the output file. The implementation +shall recognize the following two forms of the +.IR tocodeset +option-argument: +.RS 10 +.IP "\fItocode\fR" 10 +The semantics shall be equivalent to the +.BR \(mif +.IR fromcode +option. +.IP "\fItomap\fR" 10 +The semantics shall be equivalent to the +.BR \(mif +.IR frommap +option. +.P +If this option is omitted, the codeset of the current locale shall be +used. +.RE +.P +If either +.BR \(mif +or +.BR \(mit +represents a charmap file, but the other does not (or is omitted), or +both +.BR \(mif +and +.BR \(mit +are omitted, the results are undefined. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR iconv : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). During translation of the file, +this variable is superseded by the use of the +.IR fromcode +option-argument. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(mil +option is used, the standard output shall contain all supported +.IR fromcode +and +.IR tocode +values, written in an unspecified format. +.P +When the +.BR \(mil +option is not used, the standard output shall contain the sequence of +characters read from the input files, translated to the specified +codeset. Nothing else shall be written to the standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The user must ensure that both charmap files use the same symbolic +names for characters the two codesets have in common. +.SH EXAMPLES +The following example converts the contents of file +.BR mail.x400 +from the ISO/IEC\ 6937:\|2001 standard codeset to the ISO/IEC\ 8859\(hy1:\|1998 standard codeset, and stores the results in +file +.BR mail.local : +.sp +.RS 4 +.nf +\fB +iconv \(mif IS6937 \(mit IS8859 mail.x400 > mail.local +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR iconv +utility can be used portably only when the user provides two charmap +files as option-arguments. This is because a single charmap provided by +the user cannot reliably be joined with the names in a system-provided +character set description. The valid values for +.IR fromcode +and +.IR tocode +are implementation-defined and do not have to have any relation to +the charmap mechanisms. As an aid to interactive users, the +.BR \(mil +option was adopted from the Plan 9 operating system. It writes +information concerning these implementation-defined values. The +format is unspecified because there are many possible useful formats +that could be chosen, such as a matrix of valid combinations of +.IR fromcode +and +.IR tocode . +The +.BR \(mil +option is not intended for shell script usage; conforming applications +will have to use charmaps. +.P +The +.IR iconv +utility may support the conversion between ASCII and EBCDIC-based +encodings, but is not required to do so. In an XSI-compliant +implementation, the +.IR dd +utility is the only method guaranteed to support conversion between +these two character sets. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdd\fR\^", +.IR "\fIgencat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |