Man Pages

iconv(1p) - phpMan iconv(1p) - phpMan

Command: man perldoc info search(apropos)  


ICONV(1P)                  POSIX Programmer's Manual                 ICONV(1P)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (consult the corresponding Linux manual page for details of Linux behavior), or the interface  may  not  be
       implemented on Linux.

NAME
       iconv - codeset conversion

SYNOPSIS
       iconv [-cs] -f frommap -t tomap [file ...]

       iconv -f fromcode [-cs] [-t tocode [file ...]

       iconv -t tocode [-cs] [-f fromcode] [file ...]

       iconv -l


DESCRIPTION
       The  iconv  utility  shall convert the encoding of characters in file from one codeset to another and write the
       results to standard output.

       When the options indicate that charmap files are used to specify the codesets (see OPTIONS), the  codeset  con-
       version 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.

OPTIONS
       The  iconv  utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2, Utility
       Syntax Guidelines.

       The following options shall be supported:

       -c     Omit any characters that are invalid in the codeset of the input file from the output. When  -c  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 -c shall not
              affect the exit status of iconv.

       -f  fromcodeset

              Identify the codeset of the input file. The implementation shall recognize the following  two  forms  of
              the fromcodeset option-argument:

       fromcode
              The 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
              fromcode are implementation-defined.

       frommap
              The  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 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.


       If this option is omitted, the codeset of the current locale shall be used.

       -l     Write all supported fromcode and tocode values to standard output in an unspecified format.

       -s     Suppress any messages written to standard error concerning invalid characters. When -s 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 -s shall not
              affect the exit status of iconv.

       -t  tocodeset
              Identify the codeset to be used for the output file. The implementation shall  recognize  the  following
              two forms of the tocodeset option-argument:

       tocode
              The semantics shall be equivalent to the -f fromcode option.

       tomap
              The semantics shall be equivalent to the tomap option.


       If this option is omitted, the codeset of the current locale shall be used.


       If  either  -f  or  -t represents a charmap file, but the other does not (or is omitted), or both -f and -t are
       omitted, the results are undefined.

OPERANDS
       The following operand shall be supported:

       file   A pathname of an input file. If no file operands are specified, or if a file operand is '-',  the  stan-
              dard input shall be used.


STDIN
       The standard input shall be used only if no file operands are specified, or if a file operand is '-' .

INPUT FILES
       The input file shall be a text file.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of iconv:

       LANG   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  prece-
              dence of internationalization variables used to determine the values of locale categories.)

       LC_ALL If set to a non-empty string value, override the values of all the other internationalization variables.

       LC_CTYPE
              Determine the locale for the interpretation of sequences of bytes of text data as characters (for  exam-
              ple, single-byte as opposed to multi-byte characters in arguments). During translation of the file, this
              variable is superseded by the use of the fromcode option-argument.

       LC_MESSAGES
              Determine the locale that should be used to affect the format and contents of diagnostic messages  writ-
              ten to standard error.

       NLSPATH
              Determine the location of message catalogs for the processing of LC_MESSAGES .


ASYNCHRONOUS EVENTS
       Default.

STDOUT
       When the -l option is used, the standard output shall contain all supported fromcode and tocode values, written
       in an unspecified format.

       When the -l 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.

STDERR
       The standard error shall be used only for diagnostic messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

        0     Successful completion.

       >0     An error occurred.


CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       The  user  must ensure that both charmap files use the same symbolic names for characters the two codesets have
       in common.

EXAMPLES
       The following example converts the contents of file mail.x400 from the ISO/IEC 6937:1994  standard  codeset  to
       the ISO/IEC 8859-1:1998 standard codeset, and stores the results in file mail.local:


              iconv -f IS6937 -t IS8859 mail.x400 > mail.local

RATIONALE
       The  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 fromcode and tocode are implementation-defined and do not have
       to have any relation to the charmap mechanisms. As an aid to interactive users, the -l 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 fromcode and tocode. The -l option is not intended for shell script usage; conforming applica-
       tions will have to use charmaps.

FUTURE DIRECTIONS
       None.

SEE ALSO
       gencat

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, 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 .



IEEE/The Open Group                  2003                            ICONV(1P)