ICONV(1) BSD General Commands Manual ICONV(1)NAME
iconv -- codeset conversion utility
SYNOPSIS
iconv [-cs] -f from_name -t to_name [file ...]
iconv -f from_name [-cs] [-t to_name] [file ...]
iconv -t to_name [-cs] [-f from_name] [file ...]
iconv -l
DESCRIPTION
The iconv utility converts the codeset of file (or from standard input if no file is specified) from codeset from_name to codeset to_name and
outputs the converted text on standard output.
The following options are available:
-c Prevent output of any invalid characters. By default, iconv outputs an ``invalid character'' specified by the to_name codeset when it
encounts a character which is valid in the from_name codeset but does not have a corresponding character in the to_name codeset.
-f Specifies the source codeset name as from_name.
-l Lists available codeset names. Note that not all combinations of from_name and to_name are valid.
-s Silent. By default, iconv outputs the number of ``invalid characters'' to standard error if they exist. This option prevents this be-
haviour.
-t Specifies the destination codeset name as to_name.
EXIT STATUS
The iconv utility exits 0 on success, and >0 if an error occurs.
SEE ALSO mkcsmapper(1), mkesdb(1), iconv(3)STANDARDS
iconv conform to IEEE Std 1003.1-2008 (``POSIX.1'').
HISTORY
iconv first appeared in NetBSD 2.0, and made its appearance in FreeBSD 9.0.
BSD October 22, 2009 BSD
Check Out this Related Man Page
ICONV(3) BSD Library Functions Manual ICONV(3)NAME
iconv_open, iconv_close, iconv -- codeset conversion functions
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <iconv.h>
iconv_t
iconv_open(const char *dstname, const char *srcname);
int
iconv_close(iconv_t cd);
size_t
iconv(iconv_t cd, const char ** restrict src, size_t * restrict srcleft, char ** restrict dst, size_t * restrict dstleft);
DESCRIPTION
The iconv_open() function opens a converter from the codeset srcname to the codeset dstname and returns its descriptor.
The iconv_close() function closes the specified converter cd.
The iconv() function converts the string in the buffer *src of length *srcleft bytes and stores the converted string in the buffer *dst of
size *dstleft bytes. After calling iconv(), the values pointed to by src, srcleft, dst, and dstleft are updated as follows:
*src Pointer to the byte just after the last character fetched.
*srcleft Number of remaining bytes in the source buffer.
*dst Pointer to the byte just after the last character stored.
*dstleft Number of remainder bytes in the destination buffer.
If the string pointed to by *src contains a byte sequence which is not a valid character in the source codeset, the conversion stops just
after the last successful conversion. If the output buffer is too small to store the converted character, the conversion also stops in the
same way. In these cases, the values pointed to by src, srcleft, dst, and dstleft are updated to the state just after the last successful
conversion.
If the string pointed to by *src contains a character which is valid under the source codeset but can not be converted to the destination
codeset, the character is replaced by an ``invalid character'' which depends on the destination codeset, e.g., '?', and the conversion is
continued. iconv() returns the number of such ``invalid conversions''.
If the source and/or destination codesets are stateful, iconv() places these into their initial state. There are two special cases of
iconv():
1. If both dst and *dst are non-NULL, iconv() stores the shift sequence for the destination switching to the initial state in the
buffer pointed to by *dst. The buffer size is specified by the value pointed to by dstleft as above. iconv() will fail if the
buffer is too small to store the shift sequence.
2. On the other hand, dst or *dst may be NULL. In this case, the shift sequence for the destination switching to the initial state
is discarded.
RETURN VALUES
Upon successful completion of iconv_open(), it returns a conversion descriptor. Otherwise, iconv_open() returns (iconv_t)-1 and sets errno
to indicate the error.
Upon successful completion of iconv_close(), it returns 0. Otherwise, iconv_close() returns -1 and sets errno to indicate the error.
Upon successful completion of iconv(), it returns the number of ``invalid'' conversions. Otherwise, iconv() returns (size_t)-1 and sets
errno to indicate the error.
ERRORS
The iconv_open() function may cause an error in the following cases:
[EINVAL] There is no converter specified by srcname and dstname.
[ENOMEM] Memory is exhausted.
The iconv_close() function may cause an error in the following case:
[EBADF] The conversion descriptor specified by cd is invalid.
The iconv() function may cause an error in the following cases:
[E2BIG] The output buffer pointed to by *dst is too small to store the result string.
[EBADF] The conversion descriptor specified by cd is invalid.
[EILSEQ] The string pointed to by *src contains a byte sequence which does not describe a valid character of the source codeset.
[EINVAL] The string pointed to by *src terminates with an incomplete character or shift sequence.
SEE ALSO iconv(1)STANDARDS
iconv_open(), iconv_close(), and iconv() conform to IEEE Std 1003.1-2001 (``POSIX.1'').
BUGS
If iconv() is aborted due to the occurrence of some error, the ``invalid conversion'' count mentioned above is unfortunately lost.
BSD May 5, 2010 BSD