Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 differ (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 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.

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  en-
	      countering  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	 pres-
	      ence 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-ar-
	      gument:

       fromcode
	      The fromcode option-argument must	not contain a slash character.
	      It shall be interpreted as the name of one of  the  codeset  de-
	      scriptions provided by the implementation	in an unspecified for-
	      mat. 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 de-
	      fined 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  out-
	      put in an	unspecified format.

       -s     Suppress	any  messages written to standard error	concerning in-
	      valid characters.	When -s	is not used, the results of encounter-
	      ing  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 out-
	      put 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	imple-
	      mentation	shall recognize	the following two forms	of the tocode-
	      set 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	 unde-
       fined.

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 standard	input shall be used.

STDIN
       The standard input shall	be used	only if	no file	 operands  are	speci-
       fied, 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	 Vari-
	      ables  for the precedence	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  example,  single-byte  as
	      opposed  to multi-byte characters	in arguments). During transla-
	      tion 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 written 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 sup-
       ported 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  out-
       put.

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 sys-
       tem-provided  character	set description. The valid values for fromcode
       and tocode are implementation-defined and do not	have to	have any rela-
       tion  to	the charmap mechanisms.	As an aid to interactive users,	the -l
       option was adopted from the Plan	9 operating system. It writes informa-
       tion  concerning	these implementation-defined values. The format	is un-
       specified 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	appli-
       cations 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, 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 .

IEEE/The Open Group		     2003			     ICONV(1P)

PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=iconv&sektion=1&manpath=CentOS+7.1>

home | help