git.saurik.com Git - apple/libc.git/blob - locale/FreeBSD/wcsrtombs.3

3 .\"

4 .\" Redistribution and use in source and binary forms, with or without

5 .\" modification, are permitted provided that the following conditions

6 .\" are met:

7 .\" 1. Redistributions of source code must retain the above copyright

8 .\" notice, this list of conditions and the following disclaimer.

9 .\" 2. Redistributions in binary form must reproduce the above copyright

10 .\" notice, this list of conditions and the following disclaimer in the

11 .\" documentation and/or other materials provided with the distribution.

12 .\"

13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND

14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE

17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

23 .\" SUCH DAMAGE.

24 .\"

25 .\" $FreeBSD: src/lib/libc/locale/wcsrtombs.3,v 1.5 2004/07/21 10:54:57 tjr Exp $

26 .\"

27 .Dd July 21, 2004

28 .Dt WCSRTOMBS 3

29 .Os

30 .Sh NAME

31 .Nm wcsnrtombs ,

32 .Nm wcsnrtombs_l ,

33 .Nm wcsrtombs ,

34 .Nm wcsrtombs_l

35 .Nd "convert a wide-character string to a character string (restartable)"

36 .Sh LIBRARY

37 .Lb libc

38 .Sh SYNOPSIS

39 .In wchar.h

40 .Ft size_t

41 .Fo wcsnrtombs

42 .Fa "char *restrict dst"

43 .Fa "const wchar_t **restrict src"

44 .Fa "size_t nwc"

45 .Fa "size_t len"

46 .Fa "mbstate_t *restrict ps"

47 .Fc

48 .Ft size_t

49 .Fo wcsrtombs

50 .Fa "char *restrict dst"

51 .Fa "const wchar_t **restrict src"

52 .Fa "size_t len"

53 .Fa "mbstate_t *restrict ps"

54 .Fc

55 .In wchar.h

56 .In xlocale.h

57 .Ft size_t

58 .Fo wcsnrtombs_l

59 .Fa "char *restrict dst"

60 .Fa "const wchar_t **restrict src"

61 .Fa "size_t nwc"

62 .Fa "size_t len"

63 .Fa "mbstate_t *restrict ps"

64 .Fa "locale_t loc"

65 .Fc

66 .Ft size_t

67 .Fo wcsrtombs_l

68 .Fa "char *restrict dst"

69 .Fa "const wchar_t **restrict src"

70 .Fa "size_t len"

71 .Fa "mbstate_t *restrict ps"

72 .Fa "locale_t loc"

73 .Fc

74 .Sh DESCRIPTION

75 The

76 .Fn wcsrtombs

77 function converts a string of wide characters,

78 indirectly pointed to by

79 .Fa src ,

80 to a corresponding multi-byte character string,

81 stored in the array pointed to by

82 .Fa dst .

83 No more than

84 .Fa len

85 bytes are written to

86 .Fa dst .

87 .Pp

88 If

89 .Fa dst

90 is

91 .Dv NULL ,

92 no characters are stored.

93 .Pp

94 If

95 .Fa dst

96 is not

97 .Dv NULL ,

98 the pointer pointed to by

99 .Fa src

100 is updated to point to the character after the one that conversion stopped at.

101 If conversion stops because a null character is encountered,

102 .Fa *src

103 is set to

104 .Dv NULL .

105 .Pp

106 The

107 .Vt mbstate_t

108 argument,

109 .Fa ps ,

110 is used to keep track of the shift state.

111 If it is

112 .Dv NULL ,

113 .Fn wcsrtombs

114 uses an internal, static

115 .Vt mbstate_t

116 object, which is initialized to the initial conversion state

117 at program startup.

118 .Pp

119 The

120 .Fn wcsnrtombs

121 function behaves identically to

122 .Fn wcsrtombs ,

123 except that conversion stops after reading at most

124 .Fa nwc

125 characters from the buffer pointed to by

126 .Fa src .

127 .Pp

128 Although the

129 .Fn wcsrtombs

130 and

131 .Fn wcsnrtombs

132 functions use the current locale, the

133 .Fn wcsrtombs_l

134 and

135 .Fn wcsnrtombs_l

136 functions may be passed locales directly. See

137 .Xr xlocale 3

138 for more information.

139 .Sh RETURN VALUES

140 If successful, the

141 .Fn wcsrtombs

142 and

143 .Fn wcsnrtombs

144 functions return the number of bytes stored in

145 the array pointed to by

146 .Fa dst

147 (not including any terminating null);

148 otherwise, they return

149 .Po Vt size_t Pc Ns \-1 .

150 .Sh ERRORS

151 The

152 .Fn wcsrtombs

153 and

154 .Fn wcsnrtombs

155 functions will fail if:

156 .Bl -tag -width Er

157 .It Bq Er EILSEQ

158 An invalid wide character was encountered.

159 .It Bq Er EINVAL

160 The conversion state is invalid.

161 .El

162 .Sh SEE ALSO

163 .Xr mbsrtowcs 3 ,

164 .Xr wcrtomb 3 ,

165 .Xr wcstombs 3 ,

166 .Xr xlocale 3

167 .Sh STANDARDS

168 The

169 .Fn wcsrtombs

170 function conforms to

171 .St -isoC-99 .

172 .Pp

173 The

174 .Fn wcsnrtombs

175 function is an extension to the standard.