diff options
Diffstat (limited to 'man-pages-posix-2003/man1p/iconv.1p')
| -rw-r--r-- | man-pages-posix-2003/man1p/iconv.1p | 263 |
1 files changed, 263 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/iconv.1p b/man-pages-posix-2003/man1p/iconv.1p new file mode 100644 index 0000000..23899d5 --- /dev/null +++ b/man-pages-posix-2003/man1p/iconv.1p @@ -0,0 +1,263 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ICONV" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iconv +.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 \- codeset conversion +.SH SYNOPSIS +.LP +\fBiconv\fP \fB[\fP\fB-cs\fP\fB]\fP \fB-f\fP \fIfrommap\fP \fB-t\fP +\fItomap\fP \fB[\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +iconv -f\fP \fIfromcode\fP \fB[\fP\fB-cs\fP\fB] [\fP\fB-t\fP \fItocode\fP +\fB[\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +iconv -t\fP \fItocode\fP \fB[\fP\fB-cs\fP\fB] [\fP\fB-f\fP \fIfromcode\fP\fB] +[\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +iconv -l +.br +\fP +.SH DESCRIPTION +.LP +The \fIiconv\fP utility shall convert the encoding of characters in +\fIfile\fP from one codeset to another and write the +results to standard output. +.LP +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 +.LP +The \fIiconv\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Omit any characters that are invalid in the codeset of the input file +from the output. When \fB-c\fP 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 \fB-c\fP shall not affect the exit status of +\fIiconv\fP. +.TP 7 +\fB-f\ \fP \fIfromcodeset\fP +.sp +Identify the codeset of the input file. The implementation shall recognize +the following two forms of the \fIfromcodeset\fP +option-argument: +.TP 7 +\fIfromcode\fP +.RS +The \fIfromcode\fP 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 \fIfromcode\fP are +implementation-defined. +.RE +.TP 7 +\fIfrommap\fP +.RS +The \fIfrommap\fP 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 IEEE\ Std\ 1003.1-2001, +Section +6.4, Character Set Description File. If the pathname does not represent +a valid, readable charmap file, the results are +undefined. +.RE +.sp +.LP +If this option is omitted, the codeset of the current locale shall +be used. +.TP 7 +\fB-l\fP +Write all supported \fIfromcode\fP and \fItocode\fP values to standard +output in an unspecified format. +.TP 7 +\fB-s\fP +Suppress any messages written to standard error concerning invalid +characters. When \fB-s\fP 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 \fB-s\fP shall not affect the exit status of +\fIiconv\fP. +.TP 7 +\fB-t\ \fP \fItocodeset\fP +Identify the codeset to be used for the output file. The implementation +shall recognize the following two forms of the +\fItocodeset\fP option-argument: +.TP 7 +\fItocode\fP +.RS +The semantics shall be equivalent to the \fB-f\fP \fIfromcode\fP option. +.RE +.TP 7 +\fItomap\fP +.RS +The semantics shall be equivalent to the \fItomap\fP option. +.RE +.sp +.LP +If this option is omitted, the codeset of the current locale shall +be used. +.sp +.LP +If either \fB-f\fP or \fB-t\fP represents a charmap file, but the +other does not (or is omitted), or both \fB-f\fP and +\fB-t\fP are omitted, the results are undefined. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If no \fIfile\fP operands are specified, +or if a \fIfile\fP operand is \fB'-'\fP, the +standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP +\&. +.SH INPUT FILES +.LP +The input file shall be a text file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIiconv\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +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 +\fIfromcode\fP option-argument. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When the \fB-l\fP option is used, the standard output shall contain +all supported \fIfromcode\fP and \fItocode\fP values, +written in an unspecified format. +.LP +When the \fB-l\fP 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 +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The user must ensure that both charmap files use the same symbolic +names for characters the two codesets have in common. +.SH EXAMPLES +.LP +The following example converts the contents of file \fBmail.x400\fP +from the ISO/IEC\ 6937:1994 standard codeset to the +ISO/IEC\ 8859-1:1998 standard codeset, and stores the results in file +\fBmail.local\fP: +.sp +.RS +.nf + +\fBiconv -f IS6937 -t IS8859 mail.x400 > mail.local +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fIiconv\fP 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 \fIfromcode\fP and \fItocode\fP are implementation-defined +and do not have to have any relation to the charmap +mechanisms. As an aid to interactive users, the \fB-l\fP 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 \fIfromcode\fP and \fItocode\fP. The \fB-l\fP option is +not intended for shell script usage; conforming applications will +have to use charmaps. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgencat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html . |