iconv 子例程

在线编辑

用途

将一个字符代码集中的字符串转换为另一个字符代码集。

库

iconv 库 (libiconv.a)

语法

#include <iconv.h>
size_t iconv (CD, InBuf, InBytesLeft, OutBuf, OutBytesLeft)
iconv_t CD;
char **OutBuf, **InBuf;
size_t *OutBytesLeft, *InBytesLeft;

描述

iconv 子例程将 InBuf 参数指定的字符串转换为不同的代码集，并在 OutBuf 参数中返回结果。 必需的转换方法由 CD 参数标识，该参数必须是先前成功调用 iconv_open 子例程所返回的有效转换描述符。

调用时， InBytesLeft参数表示 "InBuf缓冲区中需要转换的字节数，"OutBytesLeft参数表示 "OutBuf缓冲区中剩余的不包含转换数据的字节数。 返回时将更新这些值，以便它们指示其关联缓冲区的新状态。

对于依赖于状态的编码，在将 InBuf 缓冲区设置为空的情况下调用 iconv 子例程会将 CD 参数中的转换描述符重置为其初始状态。 使用 InBuf 缓冲区的后续调用 (指定非空指针) 可能会导致子例程的内部状态发生必要的改变。

参数

项 描述
CD 指定指向正确代码集转换器的转换描述符。
InBuf 指向一个缓冲区，其中包含InBytesLeft参数中需要转换的字节数。
InBytesLeft 指向包含 InBuf 参数中的字节数的整数。
OutBuf 指向一个缓冲区，其中包含OutBytesLeft参数中已转换的字节数。
OutBytesLeft 指向包含 OutBuf 参数中的字节数的整数。

返回值

成功转换InBuf缓冲区中的所有字符并将转换后的字符放入OutBuf缓冲区后，iconv子程序返回 0，更新InBytesLeft和OutBytesLeft参数，并递增 InBuf和OutBuf指针。 否则，它将更新参数指向的变量以指示转换范围，返回仍要在输入缓冲区中转换的字节数，并设置 errno 全局变量以指示错误。

错误代码

如果 iconv 子例程不成功，那么它会在停止之前更新变量以反映转换的程度，并将 errno 全局变量设置为下列其中一个值:

项 描述
EILSEQ 指示不可用的字符。 如果输入字符不属于输入代码集，那么不会尝试对该字符进行不可用的转换。 InBytesLeft参数表示待转换的剩余字节数，包括不可用字符的第一个字节。 InBuf 参数指向不可用字符序列的第一个字节。

OutBuf和OutBytesLeft的值会根据输出缓冲区中不包含转换数据的可用字节数进行更新。
E2BIG 指示输出缓冲区溢出。 如果 OutBuf 缓冲区太小，无法包含所有已转换的字符，那么不会转换导致溢出的字符。 InBytesLeft参数表示尚待转换的字节数（包括导致溢出的字符）。 InBuf 参数指向要转换的字符的第一个字节。
EINVAL 指示输入缓冲区已截断。 如果InBytesLeft的原始值在字符转换或移位/锁定块中间耗尽，则 InBytesLeft参数表示正在转换的字符中未定义的字节数。

如果移位序列的输入字符被InBuf缓冲区截断，则不会尝试对截断的数据进行转换，InBytesLeft参数将指示待转换的剩余字节数。 InBuf 参数指向第一个字节 (如果序列被截断)。 OutBuf和OutBytesLeft的值会根据之前转换的字符数进行更新。 由于某些编码可能具有模糊数据，因此 EINVAL 返回值在流转换结束时具有特殊含义。 因此，如果用户在正在转换的数据流中检测到一个 EOF 字符，而iconv子例程的上一次返回代码为EINVAL，则应再次调用iconv子例程，并使用与发生EINVAL返回时相同的InBytesLeft参数和InBuf参数指向的相同字符串。 因此，转换器将按现在的方式转换字符串，或者将其声明为不可用的序列 (EILSEQ)。

文件

项 描述
/ usr / lib / nls / loc / iconv /* 包含代码集转换器方法。