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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
ICONV(3)	       FreeBSD Library Functions Manual		      ICONV(3)

NAME
     iconv_open, iconv_open_into, 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_open_into(const char	*dstname, const	char *srcname,
	 iconv_allocation_t *ptr);

     int
     iconv_close(iconv_t cd);

     size_t
     iconv(iconv_t cd, char ** restrict	src, size_t * restrict srcleft,
	 char ** restrict dst, size_t *	restrict dstleft);

     size_t
     __iconv(iconv_t cd, const char ** restrict	src,
	 size_t	* restrict srcleft, char ** restrict dst,
	 size_t	* restrict dstleft, uint32_t flags, size_t invalids);

DESCRIPTION
     The iconv_open() function opens a converter from the codeset srcname to
     the codeset dstname and returns its descriptor.  The arguments srcname
     and dstname accept	"" and "char", which refer to the current locale
     encoding.

     The iconv_open_into() creates a conversion	descriptor on a	preallocated
     space.  The iconv_allocation_t is used as a spaceholder type when allo-
     cating such space.	 The dstname and srcname arguments are the same	as in
     the case of iconv_open().	The ptr	argument is a pointer of
     iconv_allocation_t	to the preallocated space.

     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 con-
     tinued.  iconv() returns the number of such ``invalid conversions''.

     There are two special cases of iconv():

     src == NULL || *src == NULL
	   If the source and/or	destination codesets are stateful, iconv()
	   places these	into their initial state.

	   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.

	   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.

     The __iconv() function works just like iconv() but	if iconv() fails, the
     invalid character count is	lost there.  This is a not bug rather a	limi-
     tation of IEEE Std	1003.1-2008 (``POSIX.1''), so __iconv()	is provided as
     an	alternative but	non-standard interface.	 It also has a flags argument,
     where currently the following flags can be	passed:

     __ICONV_F_HIDE_INVALID
	   Skip	invalid	characters, instead of returning with an error.

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_open_into(), it returns 0.  Other-
     wise, iconv_open_into() returns -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:

     [ENOMEM]		Memory is exhausted.

     [EINVAL]		There is no converter specified	by srcname and
			dstname.
     The iconv_open_into() function may	cause an error in the following	cases:

     [EINVAL]		There is no converter specified	by srcname and
			dstname.

     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:

     [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.

     [E2BIG]		The output buffer pointed to by	*dst is	too small to
			store the result string.

     [EINVAL]		The string pointed to by *src terminates with an
			incomplete character or	shift sequence.

SEE ALSO
     iconv(1), mkcsmapper(1), mkesdb(1)

STANDARDS
     The iconv_open(), iconv_close(), and iconv() functions conform to IEEE
     Std 1003.1-2008 (``POSIX.1'').

     The iconv_open_into() function is a GNU-specific extension	and it is not
     part of any standard, thus	its use	may break portability.	The __iconv()
     function is an own	extension and it is not	part of	any standard, thus its
     use may break portability.

FreeBSD	10.1			 June 16, 2010			  FreeBSD 10.1

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=iconv&sektion=3&manpath=FreeBSD+10.0-RELEASE>

home | help