iconv man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

iconv(3)							      iconv(3)

NAME
       iconv  -	 Convert  a  string  of characters from one codeset to another
       codeset

SYNOPSIS
       The following syntax is for pre-XSH5.0-compliant	 interfaces  on	 Tru64
       UNIX V4 and V5 systems: #include <iconv.h>

       size_t iconv(
	       iconv_t cd,
	       const char **inbuf,
	       size_t *inbytesleft,
	       char **outbuf,
	       size_t *outbytesleft );

       The  following  syntax is for pre-V4 Tru64 UNIX systems and XSH5.0-com‐
       pliant interfaces on V5 systems: #include <iconv.h>

       size_t iconv(
	       iconv_t cd,
	       char **inbuf,
	       size_t *inbytesleft,
	       char **outbuf,
	       size_t *outbytesleft );

LIBRARY
       The iconv library (libiconv)

STANDARDS
       Interfaces documented on this reference page conform to industry	 stan‐
       dards as follows:

       iconv(): XSH4.0, XSH4.2, XSH5.0

       Refer  to  the  standards(5)  reference page for more information about
       industry standards and associated tags.

PARAMETERS
       Specifies the conversion descriptor that points to the correct  codeset
       converter Points to a variable that points to the beginning of a buffer
       that contains the characters to be converted Points to an integer  that
       contains the number of bytes in inbuf still to be converted Points to a
       variable that points to the buffer that contains	 the  characters  that
       have  been  converted  Points to an integer that contains the number of
       free bytes in outbuf

DESCRIPTION
       The iconv() function converts a string of characters in	inbuf  into  a
       different  codeset and returns the results in outbuf. The required con‐
       verter is identified by cd, which must be a valid  descriptor  returned
       by a previous successful call to the iconv_open() function.

       On  calling, the inbytesleft parameter indicates the number of bytes in
       inbuf to be converted and outbytesleft indicates the number  of	avail‐
       able bytes in outbuf.

       For  codesets  that include shift-state sequences, a call to iconv() in
       which inbuf is or points to a null pointer  places  the	cd  conversion
       descriptor  into its initial shift state. In this case, as long as out‐
       buf is not (or does not point to) a null pointer, the  call  places  in
       outbuf  the byte sequence that changes the output buffer to its initial
       shift state.  If the output buffer is not  large	 enough	 to  hold  the
       entire  reset  sequence, the call fails and sets errno to [E2BIG].  Any
       subsequent calls in which inbuf is not (or does not point  to)  a  null
       pointer	cause  the  conversion to take place from the current state of
       the conversion descriptor. See the RESTRICTIONS section for information
       about support of shift-state encoding.

       If a sequence of input bytes does not form a character that is valid in
       the input codeset, conversion stops  after  the	previous  successfully
       converted  character. If the input buffer ends with an incomplete char‐
       acter or shift sequence, conversion stops after the last byte  sequence
       that  was  successfully	converted to a character. If the output is not
       large enough to hold the entire sequence of converted characters,  con‐
       version	stops  just  prior to the input byte sequence that would cause
       the output buffer to overflow.

       On return from the call: The inbuf value is updated  to	point  to  the
       byte  following	the  last  byte	 used  successfully  in conversion The
       inbytesleft value is decremented to reflect the number of  input	 bytes
       still  not  converted  The outbuf value is updated to point to the byte
       following the last output byte of successfully converted data The  out‐
       bytesleft  value	 is  decremented  to reflect the number of bytes still
       available in the output buffer.	For codesets that include  shift-state
       encoding,  the  conversion  descriptor  is updated to reflect the shift
       state in effect at the end of  the  last	 successfully  converted  byte
       sequence.

       It  is  possible for input data to include a character that is valid in
       the input codeset but for which an identical character does  not	 exist
       in  the output codeset.	The output character for such cases is defined
       by the converter that iconv() applies when converting from one particu‐
       lar  codeset  to another.  In other words, the output character in this
       case can vary from one codeset converter to another.

RESTRICTIONS
       Currently, the operating system does not include locales whose codesets
       use  shift-state	 encoding.  Some sections of this reference page refer
       to iconv() behavior with respect to conversion of shift sequences. This
       information  is included only for your convenience in developing porta‐
       ble applications that run on multiple platforms, some of which may sup‐
       ply locales whose codesets do use shift-state encoding.

RETURN VALUES
       The iconv() function updates the variables pointed to by the call argu‐
       ments to reflect the extent of the conversion and returns the number of
       non-identical  conversions performed. If the function is successful and
       converts the entire input string, the value pointed to  by  inbytesleft
       will be 0 (zero).

       If  an  error occurs, the function returns (size_t)-1 and sets errno to
       indicate the condition.

ERRORS
       If any of the following conditions occur,  the  iconv()	function  sets
       errno  to  the  corresponding  value: The outbuf buffer is too small to
       contain all the converted characters. The  character  that  causes  the
       overflow	 is  not converted and inbytesleft indicates the bytes left to
       be converted, including the character that  caused  the	overflow.  The
       inbuf parameter points to the first byte of the characters left to con‐
       vert.  The cd parameter does not specify a valid converter  descriptor.
       An  input character does not belong to the input codeset. No conversion
       is attempted on the invalid character  and  inbytesleft	indicates  the
       bytes  left  to	be  converted, including the first byte of the invalid
       character. The inbuf parameter points to the first byte of the  invalid
       character sequence.

	      The  values  of outbuf and outbytesleft are updated according to
	      the number of characters that were  previously  converted.   The
	      last  character or shift sequence in the inbuf parameter was not
	      complete. The inbytesleft	 parameter  indicates  the  number  of
	      input bytes still not converted.

SEE ALSO
       Functions: iconv_close(3), iconv_open(3)

       Commands: iconv(1), genxlt(1)

       Others: iconv_intro(5), standards(5)

								      iconv(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net