|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
|
ICONV(3P) POSIX Programmer's Manual ICONV(3P)
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.
iconv — codeset conversion function
#include <iconv.h>
size_t iconv(iconv_t cd, char **restrict inbuf,
size_t *restrict inbytesleft, char **restrict outbuf,
size_t *restrict outbytesleft);
The iconv() function shall convert the sequence of characters from
one codeset, in the array specified by inbuf, into a sequence of
corresponding characters in another codeset, in the array specified
by outbuf. The codesets are those specified in the iconv_open() call
that returned the conversion descriptor, cd. The inbuf argument
points to a variable that points to the first character in the input
buffer and inbytesleft indicates the number of bytes to the end of
the buffer to be converted. The outbuf argument points to a variable
that points to the first available byte in the output buffer and
outbytesleft indicates the number of the available bytes to the end
of the buffer.
For state-dependent encodings, the conversion descriptor cd is placed
into its initial shift state by a call for which inbuf is a null
pointer, or for which inbuf points to a null pointer. When iconv() is
called in this way, and if outbuf is not a null pointer or a pointer
to a null pointer, and outbytesleft points to a positive value,
iconv() shall place, into the output buffer, the byte sequence to
change the output buffer to its initial shift state. If the output
buffer is not large enough to hold the entire reset sequence, iconv()
shall fail and set errno to [E2BIG]. Subsequent calls with inbuf as
other than a null pointer or a pointer to a null pointer cause the
conversion to take place from the current state of the conversion
descriptor.
If a sequence of input bytes does not form a valid character in the
specified codeset, conversion shall stop after the previous
successfully converted character. If the input buffer ends with an
incomplete character or shift sequence, conversion shall stop after
the previous successfully converted bytes. If the output buffer is
not large enough to hold the entire converted input, conversion shall
stop just prior to the input bytes that would cause the output buffer
to overflow. The variable pointed to by inbuf shall be updated to
point to the byte following the last byte successfully used in the
conversion. The value pointed to by inbytesleft shall be decremented
to reflect the number of bytes still not converted in the input
buffer. The variable pointed to by outbuf shall be updated to point
to the byte following the last byte of converted output data. The
value pointed to by outbytesleft shall be decremented to reflect the
number of bytes still available in the output buffer. For state-
dependent encodings, the conversion descriptor shall be updated to
reflect the shift state in effect at the end of the last successfully
converted byte sequence.
If iconv() encounters a character in the input buffer that is valid,
but for which an identical character does not exist in the target
codeset, iconv() shall perform an implementation-defined conversion
on this character.
The iconv() function shall update the variables pointed to by the
arguments to reflect the extent of the conversion and return the
number of non-identical conversions performed. If the entire string
in the input buffer is converted, the value pointed to by inbytesleft
shall be 0. If the input conversion is stopped due to any conditions
mentioned above, the value pointed to by inbytesleft shall be non-
zero and errno shall be set to indicate the condition. If an error
occurs, iconv() shall return (size_t)−1 and set errno to indicate the
error.
The iconv() function shall fail if:
EILSEQ Input conversion stopped due to an input byte that does not
belong to the input codeset.
E2BIG Input conversion stopped due to lack of space in the output
buffer.
EINVAL Input conversion stopped due to an incomplete character or
shift sequence at the end of the input buffer.
The iconv() function may fail if:
EBADF The cd argument is not a valid open conversion descriptor.
The following sections are informative.
None.
The inbuf argument indirectly points to the memory area which
contains the conversion input data. The outbuf argument indirectly
points to the memory area which is to contain the result of the
conversion. The objects indirectly pointed to by inbuf and outbuf are
not restricted to containing data that is directly representable in
the ISO C standard language char data type. The type of inbuf and
outbuf, char **, does not imply that the objects pointed to are
interpreted as null-terminated C strings or arrays of characters. Any
interpretation of a byte sequence that represents a character in a
given character set encoding scheme is done internally within the
codeset converters. For example, the area pointed to indirectly by
inbuf and/or outbuf can contain all zero octets that are not
interpreted as string terminators but as coded character data
according to the respective codeset encoding scheme. The type of the
data (char, short, long, and so on) read or stored in the objects is
not specified, but may be inferred for both the input and output data
by the converters determined by the fromcode and tocode arguments of
iconv_open().
Regardless of the data type inferred by the converter, the size of
the remaining space in both input and output objects (the
intbytesleft and outbytesleft arguments) is always measured in bytes.
For implementations that support the conversion of state-dependent
encodings, the conversion descriptor must be able to accurately
reflect the shift-state in effect at the end of the last successful
conversion. It is not required that the conversion descriptor itself
be updated, which would require it to be a pointer type. Thus,
implementations are free to implement the descriptor as a handle
(other than a pointer type) by which the conversion information can
be accessed and updated.
None.
None.
iconv_open(3p), iconv_close(3p), mbsrtowcs(3p)
The Base Definitions volume of POSIX.1‐2008, iconv.h(0p)
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The Open
Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open
Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
applied.) 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.unix.org/online.html .
Any typographical or formatting errors that appear in this page are
most likely to have been introduced during the conversion of the
source files to man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 ICONV(3P)
Pages that refer to this page: iconv.h(0p), iconv_close(3p), iconv_open(3p), mbsrtowcs(3p)
|
HTML rendering created 2018-02-02 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH.
|
|