Commit | Line | Data |
---|---|---|
ad787160 C |
1 | .\" Copyright (c) 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
00e4457f KB |
3 | .\" |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" Paul Borman at Krystal Technologies. | |
6 | .\" | |
ad787160 C |
7 | .\" Redistribution and use in source and binary forms, with or without |
8 | .\" modification, are permitted provided that the following conditions | |
9 | .\" are met: | |
10 | .\" 1. Redistributions of source code must retain the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in the | |
14 | .\" documentation and/or other materials provided with the distribution. | |
15 | .\" 3. All advertising materials mentioning features or use of this software | |
16 | .\" must display the following acknowledgement: | |
17 | .\" This product includes software developed by the University of | |
18 | .\" California, Berkeley and its contributors. | |
19 | .\" 4. Neither the name of the University nor the names of its contributors | |
20 | .\" may be used to endorse or promote products derived from this software | |
21 | .\" without specific prior written permission. | |
00e4457f | 22 | .\" |
ad787160 C |
23 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
24 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
25 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
26 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
27 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
28 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
29 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
30 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
31 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
32 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
33 | .\" SUCH DAMAGE. | |
00e4457f | 34 | .\" |
ad787160 C |
35 | .\" @(#)rune.3 8.1 (Berkeley) 6/27/93 |
36 | .\" | |
37 | .Dd "June 27, 1993" | |
00e4457f KB |
38 | .Dt RUNE 3 |
39 | .Os | |
40 | .Sh NAME | |
41 | .Nm setrunelocale , | |
42 | .Nm setinvalidrune , | |
43 | .Nm sgetrune , | |
44 | .Nm sputrune | |
45 | .Nd rune support for C | |
46 | .Sh SYNOPSIS | |
47 | .Fd #include <rune.h> | |
48 | .Fd #include <errno.h> | |
49 | .Ft int | |
50 | .Fn setrunelocale "char *locale" | |
51 | .Ft void | |
52 | .Fn setinvalidrune "rune_t rune" | |
53 | .Ft rune_t | |
54 | .Fn sgetrune "const char *string" "size_t n" "char const **result" | |
55 | .Ft int | |
56 | .Fn sputrune "rune_t rune" "char *string" "size_t n" "char **result" | |
ad787160 C |
57 | .sp |
58 | .Fd #include <stdio.h> | |
59 | .Ft long | |
60 | .Fn fgetrune "FILE *stream" | |
61 | .Ft int | |
62 | .Fn fungetrune "rune_t rune" "FILE *stream" | |
63 | .Ft int | |
64 | .Fn fputrune "rune_t rune" "FILE *stream" | |
00e4457f KB |
65 | .Sh DESCRIPTION |
66 | The | |
67 | .Fn setrunelocale | |
68 | controls the type of encoding used to represent runes as multibyte strings | |
69 | as well as the properties of the runes as defined in | |
70 | \fB<ctype.h>\fP. | |
71 | The | |
72 | .Fa locale | |
73 | argument indicates the locale which to load. | |
74 | If the locale is successfully loaded, | |
75 | .Dv 0 | |
76 | is returned, otherwise an errno value is returned to indicate the | |
77 | type of error. | |
78 | .Pp | |
79 | The | |
80 | .Fn setinvalidrune | |
81 | function sets the value of the global value | |
82 | .Ev _INVALID_RUNE | |
83 | to be | |
84 | .Fa rune. | |
85 | .Pp | |
86 | The | |
87 | .Fn sgetrune | |
88 | function tries to read a single multibyte character from | |
89 | .Fa string , | |
90 | which is at most | |
91 | .Fa n | |
92 | bytes long. | |
93 | If | |
94 | .Fn sgetrune | |
95 | is successful, the rune is returned. | |
96 | If | |
97 | .Fa result | |
98 | is not | |
99 | .Dv NULL , | |
100 | .Fa *result | |
101 | will point to the first byte which was not converted in | |
102 | .Fa string. | |
103 | If the first | |
104 | .Fa n | |
105 | bytes of | |
106 | .Fa string | |
107 | do not describe a full multibyte character, | |
108 | .Ev _INVALID_RUNE | |
109 | is returned and | |
110 | .Fa *result | |
111 | will point to | |
112 | .Fa string. | |
113 | If there is an encoding error at the start of | |
114 | .Fa string , | |
115 | .Ev _INVALID_RUNE | |
116 | is returned and | |
117 | .Fa *result | |
118 | will point to the second character of | |
119 | .Fa string. | |
120 | .Pp | |
121 | the | |
122 | .Fn sputrune | |
123 | function tries to encode | |
124 | .Fa rune | |
125 | as a multibyte string and store it at | |
126 | .Fa string , | |
127 | but no more than | |
128 | .Fa n | |
129 | bytes will be stored. | |
130 | If | |
131 | .Fa result | |
132 | is not | |
133 | .Dv NULL , | |
134 | .Fa *result | |
135 | will be set to point to the first byte in string following the new | |
136 | multibyte character. | |
137 | If | |
138 | .Fa string | |
139 | is | |
140 | .Dv NULL , | |
141 | .Fa *result | |
142 | will point to | |
143 | .Dv "(char *)0 +" | |
144 | .Fa x , | |
145 | where | |
146 | .Fa x | |
147 | is the number of bytes that would be needed to store the multibyte value. | |
148 | If the multibyte character would consist of more than | |
149 | .Fa n | |
150 | bytes and | |
151 | .Fa result | |
152 | is not | |
153 | .Dv NULL , | |
154 | .Fa *result | |
155 | will be set to | |
156 | .Dv NULL. | |
157 | In all cases, | |
158 | .Fn sputrune | |
159 | will return the number of bytes which would be needed to store | |
160 | .Fa rune | |
161 | as a multibyte character. | |
ad787160 C |
162 | .Pp |
163 | The | |
164 | .Fn fgetrune | |
165 | function operates the same as | |
166 | .Fn sgetrune | |
167 | with the exception that it attempts to read enough bytes from | |
168 | .Fa stream | |
169 | to decode a single rune. It returns either | |
170 | .Ev EOF | |
171 | on end of file, | |
172 | .Ev _INVALID_RUNE | |
173 | on an encoding error, or the rune decoded if all went well. | |
174 | .Pp | |
175 | The | |
176 | .Fn fungetrune | |
177 | function function pushes the multibyte encoding, as provided by | |
178 | .Fn sputrune , | |
179 | of | |
180 | .Fa rune | |
181 | onto | |
182 | .Fa stream | |
183 | such that the next | |
184 | .Fn fgetrune | |
185 | call will return | |
186 | .Fa rune . | |
187 | It returns | |
188 | .Ev EOF | |
189 | if it fails and | |
190 | .Dv 0 | |
191 | on success. | |
192 | .Pp | |
193 | The | |
194 | .Fn fputrune | |
195 | function writes the multibyte encoding of | |
196 | .Fa rune , | |
197 | as provided by | |
198 | .Fn sputrune , | |
199 | onto | |
200 | .Fa stream . | |
201 | It returns | |
202 | .Ev EOF | |
203 | on failure and | |
204 | .Dv 0 | |
205 | on success. | |
00e4457f KB |
206 | .Sh RETURN VALUES |
207 | The | |
208 | .Fn setrunelocale | |
209 | function returns one of the following values: | |
210 | .Bl -tag -width WWWWWWWW | |
211 | .It Dv 0 | |
212 | .Fa setrunelocale was successful. | |
213 | .It Ev EFAULT | |
214 | .Fa locale | |
215 | was | |
216 | .Dv NULL . | |
217 | .It Ev ENOENT | |
218 | The locale could not be found. | |
219 | .It Ev EFTYPE | |
220 | The file found was not a valid file. | |
221 | .It Ev EINVAL | |
222 | The encoding indicated by the locale was unknown. | |
223 | .El | |
224 | .Pp | |
225 | The | |
226 | .Fn sgetrune | |
227 | function either returns the rune read or | |
228 | .Ev _INVALID_RUNE . | |
229 | The | |
230 | .Fn sputrune | |
231 | function returns the number of bytes needed to store | |
232 | .Fa rune | |
233 | as a multibyte string. | |
234 | .Sh FILES | |
235 | .Bl -tag -width /usr/share/locale/locale/LC_CTYPE -compact | |
236 | .It Pa $PATH_LOCALE/\fIlocale\fP/LC_CTYPE | |
237 | .It Pa /usr/share/locale/\fIlocale\fP/LC_CTYPE | |
238 | binary LC_CTYPE file for the locale \fIlocale\fP. | |
239 | .El | |
240 | .Sh "SEE ALSO | |
241 | .Xr euc 4 , | |
242 | .Xr mbrune 3 , | |
243 | .Xr setlocale 3 , | |
244 | .Xr utf2 4 | |
245 | .Sh NOTE | |
246 | The ANSI C type | |
247 | .Ev wchar_t | |
248 | is the same as | |
249 | .Ev rune_t . | |
250 | .Ev Rune_t | |
251 | was chosen to accent the purposeful choice of not basing the | |
252 | system with the ANSI C | |
253 | primitives, which were, shall we say, less aesthetic. | |
254 | .Sh HISTORY | |
255 | These functions first appeared in | |
256 | .Bx 4.4 . | |
257 | .Pp | |
258 | The | |
259 | .Fn setrunelocale | |
260 | function and the other non-ANSI rune functions were inspired by | |
261 | .Nm Plan 9 from Bell Labs | |
262 | as a much more sane alternative to the ANSI multibyte and | |
263 | wide character support. | |
9470f3f2 KB |
264 | .\"They were conceived at the San Diego 1993 Summer USENIX conference by |
265 | .\"Paul Borman of Krystal Technologies, Keith Bostic of CSRG and Andrew Hume | |
266 | .\"of Bell Labs. | |
00e4457f KB |
267 | .Pp |
268 | All of the ANSI multibyte and wide character | |
269 | support functions are built using the rune functions. |