WebSVN – nexmon – Blame – Rev 1 – /utilities/libiconv/man/iconv.3.html

1

office

1

2

3

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"

4

"http://www.w3.org/TR/html4/loose.dtd">

5

<html>

6

<head>

7

<meta name="generator" content="groff -Thtml, see www.gnu.org">

8

<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">

9

<meta name="Content-Style" content="text/css">

10

<style type="text/css">

11

p { margin-top: 0; margin-bottom: 0; vertical-align: top }

12

pre { margin-top: 0; margin-bottom: 0; vertical-align: top }

13

table { margin-top: 0; margin-bottom: 0; vertical-align: top }

14

h1 { text-align: center }

15

</style>

16

<title>ICONV</title>

</head>

<body>

<h1 align="center">ICONV</h1>

22

23

<a href="#NAME">NAME</a> 

24

<a href="#SYNOPSIS">SYNOPSIS</a> 

25

<a href="#DESCRIPTION">DESCRIPTION</a> 

26

<a href="#RETURN VALUE">RETURN VALUE</a> 

27

<a href="#ERRORS">ERRORS</a> 

28

<a href="#CONFORMING TO">CONFORMING TO</a> 

29

<a href="#SEE ALSO">SEE ALSO</a> 

<hr>

<h2>NAME

<a name="NAME"></a>

</h2>

iconv −

perform character set conversion

41

42

<h2>SYNOPSIS

43

<a name="SYNOPSIS"></a>

</h2>

#include

<iconv.h>

size_t iconv

(iconv_t cd, 

const char* * inbuf, size_t *

53

inbytesleft, 

54

char* * outbuf, size_t *

outbytesleft);

<h2>DESCRIPTION

<a name="DESCRIPTION"></a>

</h2>

The argument

cd must be a conversion descriptor created using the

64

function iconv_open.

65

66

The main case

67

is when inbuf is not NULL and *inbuf is not

68

NULL. In this case, the iconv function converts the

69

multibyte sequence starting at *inbuf to a multibyte

70

sequence starting at *outbuf. At most

71

*inbytesleft bytes, starting at *inbuf, will

72

be read. At most *outbytesleft bytes, starting at

73

*outbuf, will be written.

74

75

The

76

iconv function converts one multibyte character at a

77

time, and for each character conversion it increments

78

*inbuf and decrements *inbytesleft by the

79

number of converted input bytes, it increments

80

*outbuf and decrements *outbytesleft by the

81

number of converted output bytes, and it updates the

82

conversion state contained in cd. If the character

83

encoding of the input is stateful, the iconv function

84

can also convert a sequence of input bytes to an update of

85

the conversion state without producing any output bytes;

86

such input is called a shift sequence. The conversion

87

can stop for four reasons:

88

89

1. An invalid

90

multibyte sequence is encountered in the input. In this case

91

it sets errno to EILSEQ and returns

92

(size_t)(−1). *inbuf is left pointing to the

93

beginning of the invalid multibyte sequence.

94

95

2. The input

96

byte sequence has been entirely converted, i.e.

97

*inbytesleft has gone down to 0. In this case

98

iconv returns the number of non-reversible

99

conversions performed during this call.

100

101

3. An

102

incomplete multibyte sequence is encountered in the input,

103

and the input byte sequence terminates after it. In this

104

case it sets errno to EINVAL and returns

105

(size_t)(−1). *inbuf is left pointing to the

106

beginning of the incomplete multibyte sequence.

107

108

4. The output

109

buffer has no more room for the next converted character. In

110

this case it sets errno to E2BIG and returns

(size_t)(−1).

A different

case is when inbuf is NULL or *inbuf is NULL,

115

but outbuf is not NULL and *outbuf is not

116

NULL. In this case, the iconv function attempts to

117

set cd’s conversion state to the initial state

118

and store a corresponding shift sequence at *outbuf.

119

At most *outbytesleft bytes, starting at

120

*outbuf, will be written. If the output buffer has no

121

more room for this reset sequence, it sets errno to

122

E2BIG and returns (size_t)(−1). Otherwise it

123

increments *outbuf and decrements

124

*outbytesleft by the number of bytes written.

125

126

A third case is

127

when inbuf is NULL or *inbuf is NULL, and

128

outbuf is NULL or *outbuf is NULL. In this

129

case, the iconv function sets cd’s

130

conversion state to the initial state.

131

132

<h2>RETURN VALUE

133

<a name="RETURN VALUE"></a>

</h2>

The

iconv function returns the number of characters

139

converted in a non-reversible way during this call;

140

reversible conversions are not counted. In case of error, it

141

sets errno and returns (size_t)(−1).

142

143

<h2>ERRORS

144

<a name="ERRORS"></a>

</h2>

The following

errors can occur, among others:

150

151

<table width="100%" border="0" rules="none" frame="void"

152

cellspacing="0" cellpadding="0">

153

<tr valign="top" align="left">

154

<td width="11%"></td>

<td width="9%">

E2BIG</td>

<td width="2%"></td>

<td width="78%">

There is not sufficient room at *outbuf.</td></tr>

164

<tr valign="top" align="left">

165

<td width="11%"></td>

<td width="9%">

EILSEQ</td>

<td width="2%"></td>

<td width="78%">

An invalid multibyte sequence has been encountered in

175

the input.</td></tr>

176

<tr valign="top" align="left">

177

<td width="11%"></td>

<td width="9%">

EINVAL</td>

<td width="2%"></td>

<td width="78%">

An incomplete multibyte sequence has been encountered in

187

the input.</td></tr>

</table>

<h2>CONFORMING TO

<a name="CONFORMING TO"></a>

</h2>

POSIX:2001

<h2>SEE ALSO

<a name="SEE ALSO"></a>

</h2>

iconv_open(3),

iconvctl(3) iconv_close(3)

205

<hr>

206

</body>

207

</html>

nexmon – Blame information for rev 1