Hallo, dies ist ein Test.

PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html

Running in File Mode
Relative path: ./../../../../../../usr/man/man3c/./cconv.3c
Real path: /usr/share/man/man3c/cconv.3c
Zurück

'\" te
.\" Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
.TH cconv 3C "3 Nov 2014" "Oracle Solaris 11.4" "Standard C Library Functions"
.SH NAME
cconv \- per character sequence based code conversion function
.SH SYNOPSIS

.LP
.nf
#include <iconv.h>
size_t cconv(cconv_t \fIcd\fR, char *\fIinbuf\fR, size_t *\fIinlen\fR, char *\fIoutbuf\fR,
        size_t *\fIoutlen\fR);
.fi
.SH DESCRIPTION
.sp
.LP
The \fBcconv()\fR function converts a character sequence from one codeset, in the array specified by \fIinbuf\fR, into a corresponding character sequence in another codeset, in the array specified by \fIoutbuf\fR. The codesets are those specified in the \fBcconv_open()\fR call (optionally modified with \fIvariants\fR and \fIflag\fR arguments) that returned the conversion descriptor, \fIcd\fR. The \fIinbuf\fR points to a character byte array to the first character in the input array and \fIinlen\fR indicates the number of bytes in the array to be converted. The \fIoutbuf\fR points to a character byte array to the first available byte in the output array and \fIoutlen\fR indicates the number of the available bytes in the array.
.sp
.LP
Unlike \fBiconv\fR(3C) that does buffer-based character code conversion, \fBcconv()\fR does per-character sequence-based code conversion which converts a single character sequence that is the first character sequence in the \fIinbuf\fR at a call indicating a character sequence boundary.
.sp
.LP
A character sequence is one or more character codes that comprises a character. In case of graphic characters, it may be a single character code or multiple character codes such as combining or conjoining character sequences defined in the current code conversion. It also includes designator character sequences for state-dependent encodings that may have one or more character codes in a designator. See the NOTES section below for the definitions of the terms mentioned.
.sp
.LP
For state-dependent encodings, the conversion descriptor (\fIcd\fR) is placed into its initial shift state by a call for which \fIinbuf\fR is a null pointer. When \fBcconv()\fR is called in this way, and if \fIoutbuf\fR is not a null pointer, and \fIoutlen\fR has a positive value, \fBcconv()\fR will place, into the \fIoutbuf\fR, the byte sequence to change the \fIoutbuf\fR to its initial shift state. If the \fIoutbuf\fR is not large enough to hold the entire reset sequence, \fBcconv()\fR will fail and set \fBerrno\fR to \fBE2BIG\fR. Subsequent calls with \fIinbuf\fR as other than a null pointer cause the conversion to take place from the current state of the conversion descriptor.
.sp
.LP
If a sequence of input bytes does not form a valid character sequence in the specified codeset, the conversion will fail and set \fBerrno\fR to \fBEILSEQ\fR. If the input array ends with an incomplete character or an incomplete shift sequence, conversion will fail and set \fBerrno\fR to \fBEINVAL\fR. If the output array is not large enough to hold the entire converted input character sequence, conversion will fail and set \fBerrno\fR to \fBE2BIG\fR. The value pointed to by \fIinlen\fR is decremented to reflect the number of bytes still not consumed by the code conversion in the \fIinbuf\fR. The value pointed to by \fIoutlen\fR is decremented to reflect the number of bytes still available in \fIoutbuf\fR. For state-dependent encodings, the conversion descriptor is updated to reflect the shift state in effect at the end of the successfully converted character sequence. For code conversions supporting combining or conjoining character sequences, the code conversion may consume and save some or all character codes of such a sequence into the conversion descriptor as a new conversion state if the sequence is the last character sequence in the input array and potentially an incomplete sequence.
.sp
.LP
If \fBcconv()\fR encounters a character sequence in the input array that is legal, but for which an identical character does not exist in the target codeset, \fBcconv()\fR performs an implementation-defined conversion, i.e., non-identical conversion, on this character sequence.
.sp
.LP
It is possible that \fBcconv()\fR consumes all the bytes from the input array without any failure return and yet produce no converted bytes or less number of characters at the output array if the current code conversion supports conversions of combining or conjoining character sequences and the input array has a potentially incomplete combining or conjoining character sequence. For instance, if the current code conversion supports conversions of two combining character sequences of a base character '\fBA\fR' followed by a combining mark character acute and the same base character '\fBA\fR' followed by two combining mark characters acute and dot below and the input array has the base character '\fBA\fR' and a combining mark character acute, the code conversion will consume the two characters but may not produce any converted bytes at the output array for a possible case that the next call will bring in dot below as the next first character in the input array which may result in a different code conversion bytes. Similar to the reset operation requirement for state-dependent encodings, in the end of the conversion, an additional call of reset operation is thus also required to force the conversion to store any saved bytes in the conversion descriptor into the output array. See the EXAMPLES section below for actual usage.
.sp
.LP
The default conversion behavior mentioned above can be modified if one or more of the conversion behavior modification flag values are specified and such conversion behavior modifications are supported by the implementation of the corresponding \fBcconv\fR code conversion. For more detail, see \fBcconv_open\fR(3C) and \fBcconvctl\fR(3C).
.SH RETURN VALUES
.sp
.LP
The \fBcconv()\fR function updates the values pointed to by \fIinlen\fR and \fIoutlen\fR arguments to reflect the extent of the conversion and returns the number of non-identical conversions performed. If the entire bytes in the input array is converted, the value pointed to by \fIinlen\fR will be \fB0\fR. If the input conversion is stopped due to any error conditions mentioned above, \fBcconv()\fR returns (\fBsize_t\fR)\fB-1\fR and sets \fBerrno\fR to indicate the error.
.SH ERRORS
.sp
.LP
The \fBcconv()\fR function will fail if:

.sp
.ne 2
.mk
.na
\fB\fBEILSEQ\fR\fR
.ad
.RS 10n
.rt
Input conversion stopped due to an input byte that does not belong to the input codeset.
.RE

.sp
.ne 2
.mk
.na
\fB\fBE2BIG\fR\fR
.ad
.RS 10n
.rt
Input conversion stopped due to lack of space in the output array.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt
Input conversion stopped due to an incomplete character or shift sequence at the end of the input array.
.RE

.sp
.LP
The \fBcconv()\fR function may fail if:

.sp
.ne 2
.mk
.na
\fB\fBEBADF\fR\fR
.ad
.RS 10n
.rt
The \fIcd\fR argument is not a valid open conversion descriptor.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
.rt
Insufficient storage space is available.
.RE

.SH EXAMPLES
.LP
\fBExample 1\fR 
Code Conversion from UTF-32 to ISO8859-1

.sp
.LP
The following example converts the first UTF-32 character sequence in \fIinbuf\fR into an ISO8859-1 character.

.sp
.in +2
.nf

#include <stdio.h>
    #include <string.h>
    #include <errno.h>
    #include <iconv.h>

#define MY_BUFFER_SIZE 24

uint32_t ib[MY_BUFFER_SIZE];
    char ob[MY_BUFFER_SIZE];
    size_t il;
    size_t ol;
    size_t i;
    size_t ret;
    cconv_t cd;

/*
     * As an example, initialize the input array, ib[],  with two
     * Unicode characters, 'a' U+0061 and COMBINING TILDE U+0303.
     */
    ib[0] = 0x61;
    ib[1] = 0x303;
    il = sizeof (uint32_t) * 2;
    ol = MY_BUFFER_SIZE;

cd = cconv_open("ISO8859-1", 0, "UTF-32", 0, 0);
    if (cd == (cconv_t)-1) {
        /* Code conversion not supported? */
        return (-1);
    }

/* Do the conversion. */
    ret = cconv(cd, ib, &il, ob, &ol);
    if (ret == (size_t)-1) {
        /* Illegal character or bad conversion descriptor? */
        if (errno == EILSEQ || errno == EBADF)
            return (-2);

/* Output array too small? */
        if (errno == E2BIG)
            return (-3);
    } else {
        for (i = 0; i < MY_BUFFER_SIZE - ol; i++)
            printf("Converted byte value = %d\en", ob[i]);
    }

/*
     * Make sure to flush any character bytes possibly stored in
     * the conversion descriptor by doing a reset operation.
     */
    ol = MY_BUFFER_SIZE;
    ret = cconv(cd, NULL, &il, ob, &ol);
    if (ret != (size_t)-1 && ob < MY_BUFFER_SIZE)
        for (i = 0; i < MY_BUFFER_SIZE - ol; i++)
            printf("Converted byte value = %d\en", ob[i]);

(void) cconv_close(cd);

.fi
.in -2
.sp

.SH FILES

.sp
.ne 2
.mk
.na
\fB\fB/usr/lib/iconv/*.bt\fR\fR
.ad
.RS 23n
.rt
\fBcconv\fR code conversion binary table files for \fBiconv\fR(1), \fBcconv\fR(3C), and \fBiconv\fR(3C).
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp
.TS
tab(
) box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPE
ATTRIBUTE VALUE
_
Interface Stability
Committed
_
MT-Level
MT-Safe
.TE
.sp
.SH SEE ALSO
.sp
.LP
\fBiconv\fR(1), \fBcconv_close\fR(3C), \fBcconv_open\fR(3C), \fBcconvctl\fR(3C), \fBiconv\fR(3C), \fBiconv_close\fR(3C), \fBiconv_open\fR(3C), \fBiconvctl\fR(3C), \fBiconvstr\fR(3C), \fBgeniconvtbl\fR(5), \fBattributes\fR(7)
.SH NOTES
.sp
.LP
A combining character sequence is a sequence of multiple characters starting with a base character followed by one or more of combining mark characters and optionally control characters governing combining behavior. For instance, a base character '\fBA\fR' followed by an acute combining mark followed by another combining mark, dot above.
.sp
.LP
A conjoining character sequence is a sequence of multiple characters starting with an initial character followed by one or more of conjoining characters, combining characters, and optionally control characters governing conjoining/combining behavior in some Asian scripts.
.sp
.LP
A designator sequence for state-dependent encodings is a sequence of one or more of characters that changes the state of the encoding. For instance, in ISO-2022-JP encoding, a designator (also known as an escape sequence) \fBESC $ B\fR (i.e., \fB0x1b 0x24 0x42\fR) indicates that the bytes following the designator are Japanese double byte characters in 7-bit encoding.