iconv manpage

Search topic Section

ICONV(1)		       Linux User Manual		      ICONV(1)

       iconv - convert text from one character encoding to another

       iconv [options] [-f from-encoding] [-t to-encoding] [inputfile]...

       The iconv program reads in text in one encoding and outputs the text in
       another encoding.  If no input files are given, or if it is given as  a
       dash (-), iconv reads from standard input.  If no output file is given,
       iconv writes to standard output.

       If no from-encoding is given, the default is derived from  the  current
       locale's	 character  encoding.  If no to-encoding is given, the default
       is derived from the current locale's character encoding.

       -f from-encoding, --from-code=from-encoding
	      Use from-encoding for input characters.

       -t to-encoding, --to-code=to-encoding
	      Use to-encoding for output characters.

	      If the string //IGNORE is appended  to  to-encoding,  characters
	      that  cannot  be converted are discarded and an error is printed
	      after conversion.

	      If the string //TRANSLIT is appended to to-encoding,  characters
	      being  converted	are  transliterated  when needed and possible.
	      This means that when a character cannot be  represented  in  the
	      target character set, it can be approximated through one or sev-
	      eral similar looking characters.	Characters that are outside of
	      the  target  character  set  and	cannot	be  transliterated are
	      replaced with a question mark (?) in the output.

       -l, --list
	      List all known character set encodings.

       -c     Silently discard characters that cannot be converted instead  of
	      terminating when encountering such characters.

       -o outputfile, --output=outputfile
	      Use outputfile for output.

       -s, --silent
	      This option is ignored; it is provided only for compatibility.

	      Print  progress  information  on	standard error when processing
	      multiple files.

       -?, --help
	      Print a usage summary and exit.

	      Print a short usage summary and exit.

       -V, --version
	      Print the version number, license, and  disclaimer  of  warranty
	      for iconv.

       Zero on success, non-zero on errors.

       Internally,  the iconv program uses the iconv(3) function which in turn
       uses gconv modules (dynamically loaded shared libraries) to convert  to
       and  from  a character set.  Before calling iconv(3), the iconv program
       must first allocate a conversion descriptor using  iconv_open(3).   The
       operation  of  the  latter function is influenced by the setting of the
       GCONV_PATH environment variable:

       *  If GCONV_PATH is not set, iconv_open(3) loads the system gconv  mod-
	  ule  configuration  cache  file  created by iconvconfig(8) and then,
	  based on the configuration, loads the gconv modules needed  to  per-
	  form the conversion.	If the system gconv module configuration cache
	  file is not available then the  system  gconv	 module	 configuration
	  file is used.

       *  If  GCONV_PATH  is defined (as a colon-separated list of pathnames),
	  the system gconv module configuration cache is not  used.   Instead,
	  iconv_open(3) first tries to load the configuration files by search-
	  ing the directories in GCONV_PATH in order, followed by  the	system
	  default  gconv  module  configuration file.  If a directory does not
	  contain a gconv module configuration file, any gconv modules that it
	  may  contain	are  ignored.	If a directory contains a gconv module
	  configuration file and it is determined that	a  module  needed  for
	  this	conversion is available in the directory, then the needed mod-
	  ule is loaded from that directory, the order	being  such  that  the
	  first	 suitable  module  found  in  GCONV_PATH is used.  This allows
	  users to use custom modules and even replace system-provided modules
	  by providing such modules in GCONV_PATH directories.

	      Usual default gconv module path.

	      Usual system default gconv module configuration file.

	      Usual system gconv module configuration cache.


       Convert text from the ISO 8859-15 character encoding to UTF-8:

	   $ iconv -f ISO-8859-15 -t UTF-8 < input.txt > output.txt

       The  next  example  converts  from UTF-8 to ASCII, transliterating when

	   $ echo abc B a EUR ac | iconv -f UTF-8 -t ASCII//TRANSLIT
	   abc ss ? EUR abc

       locale(1), iconv(3), nl_langinfo(3), charsets(7), iconvconfig(8)

       This page is part of release 4.10 of the Linux  man-pages  project.   A
       description  of	the project, information about reporting bugs, and the
       latest	 version    of	  this	  page,	   can	   be	  found	    at

GNU				  2014-07-08			      ICONV(1)