1.\" Copyright (c) 1993 The Regents of the University of California. 2.\" 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 5.2 (Berkeley) 06/02/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.Sh DESCRIPTION 32The 33.Fn setrunelocale 34controls the type of encoding used to represent runes as multibyte strings 35as well as the properties of the runes as defined in 36\fB<ctype.h>\fP. 37The 38.Fa locale 39argument indicates the locale which to load. 40If the locale is successfully loaded, 41.Dv 0 42is returned, otherwise an errno value is returned to indicate the 43type of error. 44.Pp 45The 46.Fn setinvalidrune 47function sets the value of the global value 48.Ev _INVALID_RUNE 49to be 50.Fa rune. 51.Pp 52The 53.Fn sgetrune 54function tries to read a single multibyte character from 55.Fa string , 56which is at most 57.Fa n 58bytes long. 59If 60.Fn sgetrune 61is successful, the rune is returned. 62If 63.Fa result 64is not 65.Dv NULL , 66.Fa *result 67will point to the first byte which was not converted in 68.Fa string. 69If the first 70.Fa n 71bytes of 72.Fa string 73do not describe a full multibyte character, 74.Ev _INVALID_RUNE 75is returned and 76.Fa *result 77will point to 78.Fa string. 79If there is an encoding error at the start of 80.Fa string , 81.Ev _INVALID_RUNE 82is returned and 83.Fa *result 84will point to the second character of 85.Fa string. 86.Pp 87the 88.Fn sputrune 89function tries to encode 90.Fa rune 91as a multibyte string and store it at 92.Fa string , 93but no more than 94.Fa n 95bytes will be stored. 96If 97.Fa result 98is not 99.Dv NULL , 100.Fa *result 101will be set to point to the first byte in string following the new 102multibyte character. 103If 104.Fa string 105is 106.Dv NULL , 107.Fa *result 108will point to 109.Dv "(char *)0 +" 110.Fa x , 111where 112.Fa x 113is the number of bytes that would be needed to store the multibyte value. 114If the multibyte character would consist of more than 115.Fa n 116bytes and 117.Fa result 118is not 119.Dv NULL , 120.Fa *result 121will be set to 122.Dv NULL. 123In all cases, 124.Fn sputrune 125will return the number of bytes which would be needed to store 126.Fa rune 127as a multibyte character. 128.Sh RETURN VALUES 129The 130.Fn setrunelocale 131function returns one of the following values: 132.Bl -tag -width WWWWWWWW 133.It Dv 0 134.Fa setrunelocale was successful. 135.It Ev EFAULT 136.Fa locale 137was 138.Dv NULL . 139.It Ev ENOENT 140The locale could not be found. 141.It Ev EFTYPE 142The file found was not a valid file. 143.It Ev EINVAL 144The encoding indicated by the locale was unknown. 145.El 146.Pp 147The 148.Fn sgetrune 149function either returns the rune read or 150.Ev _INVALID_RUNE . 151The 152.Fn sputrune 153function returns the number of bytes needed to store 154.Fa rune 155as a multibyte string. 156.Sh FILES 157.Bl -tag -width /usr/share/locale/locale/LC_CTYPE -compact 158.It Pa $PATH_LOCALE/\fIlocale\fP/LC_CTYPE 159.It Pa /usr/share/locale/\fIlocale\fP/LC_CTYPE 160binary LC_CTYPE file for the locale \fIlocale\fP. 161.El 162.Sh "SEE ALSO 163.Xr euc 4 , 164.Xr mbrune 3 , 165.Xr setlocale 3 , 166.Xr utf2 4 167.Sh NOTE 168The ANSI C type 169.Ev wchar_t 170is the same as 171.Ev rune_t . 172.Ev Rune_t 173was chosen to accent the purposeful choice of not basing the 174system with the ANSI C 175primitives, which were, shall we say, less aesthetic. 176.Sh HISTORY 177These functions first appeared in 178.Bx 4.4 . 179.Pp 180The 181.Fn setrunelocale 182function and the other non-ANSI rune functions were inspired by 183.Nm Plan 9 from Bell Labs 184as a much more sane alternative to the ANSI multibyte and 185wide character support. 186.\"They were conceived at the San Diego 1993 Summer USENIX conference by 187.\"Paul Borman of Krystal Technologies, Keith Bostic of CSRG and Andrew Hume 188.\"of Bell Labs. 189.Pp 190All of the ANSI multibyte and wide character 191support functions are built using the rune functions. 192