1.\" Copyright (c) 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Paul Borman at Krystal Technologies. 6.\" 7.\" %sccs.include.redist.roff% 8.\" 9.\" @(#)rune.3 8.1 (Berkeley) 06/27/93 10.\" 11.Dd "" 12.Dt RUNE 3 13.Os 14.Sh NAME 15.Nm setrunelocale , 16.Nm setinvalidrune , 17.Nm sgetrune , 18.Nm sputrune 19.Nd rune support for C 20.Sh SYNOPSIS 21.Fd #include <rune.h> 22.Fd #include <errno.h> 23.Ft int 24.Fn setrunelocale "char *locale" 25.Ft void 26.Fn setinvalidrune "rune_t rune" 27.Ft rune_t 28.Fn sgetrune "const char *string" "size_t n" "char const **result" 29.Ft int 30.Fn sputrune "rune_t rune" "char *string" "size_t n" "char **result" 31.sp 32.Fd #include <stdio.h> 33.Ft long 34.Fn fgetrune "FILE *stream" 35.Ft int 36.Fn fungetrune "rune_t rune" "FILE *stream" 37.Ft int 38.Fn fputrune "rune_t rune" "FILE *stream" 39.Sh DESCRIPTION 40The 41.Fn setrunelocale 42controls the type of encoding used to represent runes as multibyte strings 43as well as the properties of the runes as defined in 44\fB<ctype.h>\fP. 45The 46.Fa locale 47argument indicates the locale which to load. 48If the locale is successfully loaded, 49.Dv 0 50is returned, otherwise an errno value is returned to indicate the 51type of error. 52.Pp 53The 54.Fn setinvalidrune 55function sets the value of the global value 56.Ev _INVALID_RUNE 57to be 58.Fa rune. 59.Pp 60The 61.Fn sgetrune 62function tries to read a single multibyte character from 63.Fa string , 64which is at most 65.Fa n 66bytes long. 67If 68.Fn sgetrune 69is successful, the rune is returned. 70If 71.Fa result 72is not 73.Dv NULL , 74.Fa *result 75will point to the first byte which was not converted in 76.Fa string. 77If the first 78.Fa n 79bytes of 80.Fa string 81do not describe a full multibyte character, 82.Ev _INVALID_RUNE 83is returned and 84.Fa *result 85will point to 86.Fa string. 87If there is an encoding error at the start of 88.Fa string , 89.Ev _INVALID_RUNE 90is returned and 91.Fa *result 92will point to the second character of 93.Fa string. 94.Pp 95the 96.Fn sputrune 97function tries to encode 98.Fa rune 99as a multibyte string and store it at 100.Fa string , 101but no more than 102.Fa n 103bytes will be stored. 104If 105.Fa result 106is not 107.Dv NULL , 108.Fa *result 109will be set to point to the first byte in string following the new 110multibyte character. 111If 112.Fa string 113is 114.Dv NULL , 115.Fa *result 116will point to 117.Dv "(char *)0 +" 118.Fa x , 119where 120.Fa x 121is the number of bytes that would be needed to store the multibyte value. 122If the multibyte character would consist of more than 123.Fa n 124bytes and 125.Fa result 126is not 127.Dv NULL , 128.Fa *result 129will be set to 130.Dv NULL. 131In all cases, 132.Fn sputrune 133will return the number of bytes which would be needed to store 134.Fa rune 135as a multibyte character. 136.Pp 137The 138.Fn fgetrune 139function operates the same as 140.Fn sgetrune 141with the exception that it attempts to read enough bytes from 142.Fa stream 143to decode a single rune. It returns either 144.Ev EOF 145on end of file, 146.Ev _INVALID_RUNE 147on an encoding error, or the rune decoded if all went well. 148.Pp 149The 150.Fn fungetrune 151function function pushes the multibyte encoding, as provided by 152.Fn sputrune , 153of 154.Fa rune 155onto 156.Fa stream 157such that the next 158.Fn fgetrune 159call will return 160.Fa rune . 161It returns 162.Ev EOF 163if it fails and 164.Dv 0 165on success. 166.Pp 167The 168.Fn fputrune 169function writes the multibyte encoding of 170.Fa rune , 171as provided by 172.Fn sputrune , 173onto 174.Fa stream . 175It returns 176.Ev EOF 177on failure and 178.Dv 0 179on success. 180.Sh RETURN VALUES 181The 182.Fn setrunelocale 183function returns one of the following values: 184.Bl -tag -width WWWWWWWW 185.It Dv 0 186.Fa setrunelocale was successful. 187.It Ev EFAULT 188.Fa locale 189was 190.Dv NULL . 191.It Ev ENOENT 192The locale could not be found. 193.It Ev EFTYPE 194The file found was not a valid file. 195.It Ev EINVAL 196The encoding indicated by the locale was unknown. 197.El 198.Pp 199The 200.Fn sgetrune 201function either returns the rune read or 202.Ev _INVALID_RUNE . 203The 204.Fn sputrune 205function returns the number of bytes needed to store 206.Fa rune 207as a multibyte string. 208.Sh FILES 209.Bl -tag -width /usr/share/locale/locale/LC_CTYPE -compact 210.It Pa $PATH_LOCALE/\fIlocale\fP/LC_CTYPE 211.It Pa /usr/share/locale/\fIlocale\fP/LC_CTYPE 212binary LC_CTYPE file for the locale \fIlocale\fP. 213.El 214.Sh "SEE ALSO 215.Xr euc 4 , 216.Xr mbrune 3 , 217.Xr setlocale 3 , 218.Xr utf2 4 219.Sh NOTE 220The ANSI C type 221.Ev wchar_t 222is the same as 223.Ev rune_t . 224.Ev Rune_t 225was chosen to accent the purposeful choice of not basing the 226system with the ANSI C 227primitives, which were, shall we say, less aesthetic. 228.Sh HISTORY 229These functions first appeared in 230.Bx 4.4 . 231.Pp 232The 233.Fn setrunelocale 234function and the other non-ANSI rune functions were inspired by 235.Nm Plan 9 from Bell Labs 236as a much more sane alternative to the ANSI multibyte and 237wide character support. 238.\"They were conceived at the San Diego 1993 Summer USENIX conference by 239.\"Paul Borman of Krystal Technologies, Keith Bostic of CSRG and Andrew Hume 240.\"of Bell Labs. 241.Pp 242All of the ANSI multibyte and wide character 243support functions are built using the rune functions. 244