diff options
Diffstat (limited to 'man3/iconv.3')
| -rw-r--r-- | man3/iconv.3 | 233 |
1 files changed, 0 insertions, 233 deletions
diff --git a/man3/iconv.3 b/man3/iconv.3 deleted file mode 100644 index 1f9f96f..0000000 --- a/man3/iconv.3 +++ /dev/null @@ -1,233 +0,0 @@ -'\" t -.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> -.\" -.\" SPDX-License-Identifier: GPL-2.0-or-later -.\" -.\" References consulted: -.\" GNU glibc-2 source code and manual -.\" OpenGroup's Single UNIX specification -.\" http://www.UNIX-systems.org/online.html -.\" -.\" 2000-06-30 correction by Yuichi SATO <sato@complex.eng.hokudai.ac.jp> -.\" 2000-11-15 aeb, fixed prototype -.\" -.TH iconv 3 2023-10-31 "Linux man-pages 6.7" -.SH NAME -iconv \- perform character set conversion -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <iconv.h> -.P -.BI "size_t iconv(iconv_t " cd , -.BI " char **restrict " inbuf ", size_t *restrict " inbytesleft , -.BI " char **restrict " outbuf ", size_t *restrict " outbytesleft ); -.fi -.SH DESCRIPTION -The -.BR iconv () -function converts a sequence of characters in one character encoding -to a sequence of characters in another character encoding. -The -.I cd -argument is a conversion descriptor, -previously created by a call to -.BR iconv_open (3); -the conversion descriptor defines the character encodings that -.BR iconv () -uses for the conversion. -The -.I inbuf -argument is the address of a variable that points to -the first character of the input sequence; -.I inbytesleft -indicates the number of bytes in that buffer. -The -.I outbuf -argument is the address of a variable that points to -the first byte available in the output buffer; -.I outbytesleft -indicates the number of bytes available in the output buffer. -.P -The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL. -In this case, the -.BR iconv () -function converts the multibyte sequence -starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP. -At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read. -At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. -.P -The -.BR iconv () -function converts one multibyte character at a time, and for -each character conversion it increments \fI*inbuf\fP and decrements -\fI*inbytesleft\fP by the number of converted input bytes, it increments -\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted -output bytes, and it updates the conversion state contained in \fIcd\fP. -If the character encoding of the input is stateful, the -.BR iconv () -function can also convert a sequence of input bytes -to an update to the conversion state without producing any output bytes; -such input is called a \fIshift sequence\fP. -The conversion can stop for five reasons: -.IP \[bu] 3 -An invalid multibyte sequence is encountered in the input. -In this case, -it sets \fIerrno\fP to \fBEILSEQ\fP and returns -.IR (size_t)\ \-1 . -\fI*inbuf\fP -is left pointing to the beginning of the invalid multibyte sequence. -.IP \[bu] -A multibyte sequence is encountered that is valid but that -cannot be translated to the character encoding of the output. -This condition depends on the implementation and on the conversion descriptor. -In the GNU C library and GNU libiconv, if -.I cd -was created without the suffix -.B //TRANSLIT -or -.BR //IGNORE , -the conversion is strict: -lossy conversions produce this condition. -If the suffix -.B //TRANSLIT -was specified, -transliteration can avoid this condition in some cases. -In the musl C library, -this condition cannot occur because a conversion to -.B \[aq]*\[aq] -is used as a fallback. -In the FreeBSD, NetBSD, and Solaris implementations of -.BR iconv (), -this condition cannot occur either, -because a conversion to -.B \[aq]?\[aq] -is used as a fallback. -When this condition is met, -.BR iconv () -sets -.I errno -to -.B EILSEQ -and returns -.IR (size_t)\ \-1 . -.I *inbuf -is left pointing to the beginning of the unconvertible multibyte sequence. -.IP \[bu] -The input byte sequence has been entirely converted, -that is, \fI*inbytesleft\fP has gone down to 0. -In this case, -.BR iconv () -returns the number of -nonreversible conversions performed during this call. -.IP \[bu] -An incomplete multibyte sequence is encountered in the input, and the -input byte sequence terminates after it. -In this case, it sets \fIerrno\fP to -\fBEINVAL\fP and returns -.IR (size_t)\ \-1 . -\fI*inbuf\fP is left pointing to the -beginning of the incomplete multibyte sequence. -.IP \[bu] -The output buffer has no more room for the next converted character. -In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns -.IR (size_t)\ \-1 . -.P -A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but -\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. -In this case, the -.BR iconv () -function attempts to set \fIcd\fP's conversion state to the -initial state and store a corresponding shift sequence at \fI*outbuf\fP. -At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. -If the output buffer has no more room for this reset sequence, it sets -\fIerrno\fP to \fBE2BIG\fP and returns -.IR (size_t)\ \-1 . -Otherwise, it increments -\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes -written. -.P -A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and -\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. -In this case, the -.BR iconv () -function sets \fIcd\fP's conversion state to the initial state. -.SH RETURN VALUE -The -.BR iconv () -function returns the number of characters converted in a -nonreversible way during this call; reversible conversions are not counted. -In case of error, -.BR iconv () -returns -.I (size_t)\ \-1 -and sets -.I errno -to indicate the error. -.SH ERRORS -The following errors can occur, among others: -.TP -.B E2BIG -There is not sufficient room at \fI*outbuf\fP. -.TP -.B EILSEQ -An invalid multibyte sequence has been encountered in the input. -.TP -.B EINVAL -An incomplete multibyte sequence has been encountered in the input. -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.na -.nh -.BR iconv () -T} Thread safety MT-Safe race:cd -.TE -.P -The -.BR iconv () -function is MT-Safe, as long as callers arrange for -mutual exclusion on the -.I cd -argument. -.SH STANDARDS -POSIX.1-2008. -.SH HISTORY -glibc 2.1. -POSIX.1-2001. -.SH NOTES -In each series of calls to -.BR iconv (), -the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL, -in order to flush out any partially converted input. -.P -Although -.I inbuf -and -.I outbuf -are typed as -.IR "char\ **" , -this does not mean that the objects they point can be interpreted -as C strings or as arrays of characters: -the interpretation of character byte sequences is -handled internally by the conversion functions. -In some encodings, a zero byte may be a valid part of a multibyte character. -.P -The caller of -.BR iconv () -must ensure that the pointers passed to the function are suitable -for accessing characters in the appropriate character set. -This includes ensuring correct alignment on platforms that have -tight restrictions on alignment. -.SH SEE ALSO -.BR iconv_close (3), -.BR iconv_open (3), -.BR iconvconfig (8) |