Unix/Linux Go Back    


NetBSD 6.1.5 - man page for iconv_close (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 code-
     set 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 conver-
     sion is continued.  iconv() returns the number of such ``invalid conversions''.

     If the source and/or destination codesets are stateful, iconv() places these into their ini-
     tial state.  There are two special cases of iconv():

	   1.	If both dst and *dst are non-NULL, iconv() stores the shift sequence for the des-
		tination 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
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:59 AM.