1c57c35c3Sbostic.\" Copyright (c) 1993 2c57c35c3Sbostic.\" The Regents of the University of California. All rights reserved. 3950a7bd2Sbostic.\" 4950a7bd2Sbostic.\" This code is derived from software contributed to Berkeley by 5950a7bd2Sbostic.\" Paul Borman at Krystal Technologies. 6950a7bd2Sbostic.\" 7950a7bd2Sbostic.\" %sccs.include.redist.roff% 8950a7bd2Sbostic.\" 9*0745259aSmckusick.\" @(#)rune.3 8.2 (Berkeley) 12/11/93 10950a7bd2Sbostic.\" 11950a7bd2Sbostic.Dd "" 12950a7bd2Sbostic.Dt RUNE 3 13950a7bd2Sbostic.Os 14950a7bd2Sbostic.Sh NAME 15950a7bd2Sbostic.Nm setrunelocale , 16950a7bd2Sbostic.Nm setinvalidrune , 17950a7bd2Sbostic.Nm sgetrune , 18950a7bd2Sbostic.Nm sputrune 19950a7bd2Sbostic.Nd rune support for C 20950a7bd2Sbostic.Sh SYNOPSIS 21950a7bd2Sbostic.Fd #include <rune.h> 22950a7bd2Sbostic.Fd #include <errno.h> 23950a7bd2Sbostic.Ft int 24950a7bd2Sbostic.Fn setrunelocale "char *locale" 25950a7bd2Sbostic.Ft void 26950a7bd2Sbostic.Fn setinvalidrune "rune_t rune" 27950a7bd2Sbostic.Ft rune_t 28950a7bd2Sbostic.Fn sgetrune "const char *string" "size_t n" "char const **result" 29950a7bd2Sbostic.Ft int 30950a7bd2Sbostic.Fn sputrune "rune_t rune" "char *string" "size_t n" "char **result" 31302f6d17Sbostic.sp 32302f6d17Sbostic.Fd #include <stdio.h> 33302f6d17Sbostic.Ft long 34302f6d17Sbostic.Fn fgetrune "FILE *stream" 35302f6d17Sbostic.Ft int 36302f6d17Sbostic.Fn fungetrune "rune_t rune" "FILE *stream" 37302f6d17Sbostic.Ft int 38302f6d17Sbostic.Fn fputrune "rune_t rune" "FILE *stream" 39950a7bd2Sbostic.Sh DESCRIPTION 40950a7bd2SbosticThe 41950a7bd2Sbostic.Fn setrunelocale 42950a7bd2Sbosticcontrols the type of encoding used to represent runes as multibyte strings 43950a7bd2Sbosticas well as the properties of the runes as defined in 44950a7bd2Sbostic\fB<ctype.h>\fP. 45950a7bd2SbosticThe 46950a7bd2Sbostic.Fa locale 47*0745259aSmckusickargument indicates which locale to load. 48950a7bd2SbosticIf the locale is successfully loaded, 49950a7bd2Sbostic.Dv 0 50950a7bd2Sbosticis returned, otherwise an errno value is returned to indicate the 51950a7bd2Sbostictype of error. 52950a7bd2Sbostic.Pp 53950a7bd2SbosticThe 54950a7bd2Sbostic.Fn setinvalidrune 55950a7bd2Sbosticfunction sets the value of the global value 56950a7bd2Sbostic.Ev _INVALID_RUNE 57950a7bd2Sbosticto be 58950a7bd2Sbostic.Fa rune. 59950a7bd2Sbostic.Pp 60950a7bd2SbosticThe 61950a7bd2Sbostic.Fn sgetrune 62950a7bd2Sbosticfunction tries to read a single multibyte character from 63950a7bd2Sbostic.Fa string , 64950a7bd2Sbosticwhich is at most 65950a7bd2Sbostic.Fa n 66950a7bd2Sbosticbytes long. 67950a7bd2SbosticIf 68950a7bd2Sbostic.Fn sgetrune 69950a7bd2Sbosticis successful, the rune is returned. 70950a7bd2SbosticIf 71950a7bd2Sbostic.Fa result 72950a7bd2Sbosticis not 73950a7bd2Sbostic.Dv NULL , 74950a7bd2Sbostic.Fa *result 75950a7bd2Sbosticwill point to the first byte which was not converted in 76950a7bd2Sbostic.Fa string. 77950a7bd2SbosticIf the first 78950a7bd2Sbostic.Fa n 79950a7bd2Sbosticbytes of 80950a7bd2Sbostic.Fa string 81950a7bd2Sbosticdo not describe a full multibyte character, 82950a7bd2Sbostic.Ev _INVALID_RUNE 83950a7bd2Sbosticis returned and 84950a7bd2Sbostic.Fa *result 85950a7bd2Sbosticwill point to 86950a7bd2Sbostic.Fa string. 87950a7bd2SbosticIf there is an encoding error at the start of 88950a7bd2Sbostic.Fa string , 89950a7bd2Sbostic.Ev _INVALID_RUNE 90950a7bd2Sbosticis returned and 91950a7bd2Sbostic.Fa *result 92950a7bd2Sbosticwill point to the second character of 93950a7bd2Sbostic.Fa string. 94950a7bd2Sbostic.Pp 95950a7bd2Sbosticthe 96950a7bd2Sbostic.Fn sputrune 97950a7bd2Sbosticfunction tries to encode 98950a7bd2Sbostic.Fa rune 99950a7bd2Sbosticas a multibyte string and store it at 100950a7bd2Sbostic.Fa string , 101950a7bd2Sbosticbut no more than 102950a7bd2Sbostic.Fa n 103950a7bd2Sbosticbytes will be stored. 104950a7bd2SbosticIf 105950a7bd2Sbostic.Fa result 106950a7bd2Sbosticis not 107950a7bd2Sbostic.Dv NULL , 108950a7bd2Sbostic.Fa *result 109950a7bd2Sbosticwill be set to point to the first byte in string following the new 110950a7bd2Sbosticmultibyte character. 111950a7bd2SbosticIf 112950a7bd2Sbostic.Fa string 113950a7bd2Sbosticis 114950a7bd2Sbostic.Dv NULL , 115950a7bd2Sbostic.Fa *result 116950a7bd2Sbosticwill point to 117950a7bd2Sbostic.Dv "(char *)0 +" 118950a7bd2Sbostic.Fa x , 119950a7bd2Sbosticwhere 120950a7bd2Sbostic.Fa x 121950a7bd2Sbosticis the number of bytes that would be needed to store the multibyte value. 122950a7bd2SbosticIf the multibyte character would consist of more than 123950a7bd2Sbostic.Fa n 124950a7bd2Sbosticbytes and 125950a7bd2Sbostic.Fa result 126950a7bd2Sbosticis not 127950a7bd2Sbostic.Dv NULL , 128950a7bd2Sbostic.Fa *result 129950a7bd2Sbosticwill be set to 130950a7bd2Sbostic.Dv NULL. 131950a7bd2SbosticIn all cases, 132950a7bd2Sbostic.Fn sputrune 133950a7bd2Sbosticwill return the number of bytes which would be needed to store 134950a7bd2Sbostic.Fa rune 135950a7bd2Sbosticas a multibyte character. 136302f6d17Sbostic.Pp 137302f6d17SbosticThe 138302f6d17Sbostic.Fn fgetrune 139302f6d17Sbosticfunction operates the same as 140302f6d17Sbostic.Fn sgetrune 141302f6d17Sbosticwith the exception that it attempts to read enough bytes from 142302f6d17Sbostic.Fa stream 143302f6d17Sbosticto decode a single rune. It returns either 144302f6d17Sbostic.Ev EOF 145302f6d17Sbosticon end of file, 146302f6d17Sbostic.Ev _INVALID_RUNE 147302f6d17Sbosticon an encoding error, or the rune decoded if all went well. 148302f6d17Sbostic.Pp 149302f6d17SbosticThe 150302f6d17Sbostic.Fn fungetrune 151*0745259aSmckusickfunction pushes the multibyte encoding, as provided by 152302f6d17Sbostic.Fn sputrune , 153302f6d17Sbosticof 154302f6d17Sbostic.Fa rune 155302f6d17Sbosticonto 156302f6d17Sbostic.Fa stream 157302f6d17Sbosticsuch that the next 158302f6d17Sbostic.Fn fgetrune 159302f6d17Sbosticcall will return 160302f6d17Sbostic.Fa rune . 161302f6d17SbosticIt returns 162302f6d17Sbostic.Ev EOF 163302f6d17Sbosticif it fails and 164302f6d17Sbostic.Dv 0 165302f6d17Sbosticon success. 166302f6d17Sbostic.Pp 167302f6d17SbosticThe 168302f6d17Sbostic.Fn fputrune 169302f6d17Sbosticfunction writes the multibyte encoding of 170302f6d17Sbostic.Fa rune , 171302f6d17Sbosticas provided by 172302f6d17Sbostic.Fn sputrune , 173302f6d17Sbosticonto 174302f6d17Sbostic.Fa stream . 175302f6d17SbosticIt returns 176302f6d17Sbostic.Ev EOF 177302f6d17Sbosticon failure and 178302f6d17Sbostic.Dv 0 179302f6d17Sbosticon success. 180950a7bd2Sbostic.Sh RETURN VALUES 181950a7bd2SbosticThe 182950a7bd2Sbostic.Fn setrunelocale 183950a7bd2Sbosticfunction returns one of the following values: 184950a7bd2Sbostic.Bl -tag -width WWWWWWWW 185950a7bd2Sbostic.It Dv 0 186950a7bd2Sbostic.Fa setrunelocale was successful. 187950a7bd2Sbostic.It Ev EFAULT 188950a7bd2Sbostic.Fa locale 189950a7bd2Sbosticwas 190950a7bd2Sbostic.Dv NULL . 191950a7bd2Sbostic.It Ev ENOENT 192950a7bd2SbosticThe locale could not be found. 193950a7bd2Sbostic.It Ev EFTYPE 194950a7bd2SbosticThe file found was not a valid file. 195950a7bd2Sbostic.It Ev EINVAL 196950a7bd2SbosticThe encoding indicated by the locale was unknown. 197950a7bd2Sbostic.El 198950a7bd2Sbostic.Pp 199950a7bd2SbosticThe 200950a7bd2Sbostic.Fn sgetrune 201950a7bd2Sbosticfunction either returns the rune read or 202950a7bd2Sbostic.Ev _INVALID_RUNE . 203950a7bd2SbosticThe 204950a7bd2Sbostic.Fn sputrune 205950a7bd2Sbosticfunction returns the number of bytes needed to store 206950a7bd2Sbostic.Fa rune 207950a7bd2Sbosticas a multibyte string. 208950a7bd2Sbostic.Sh FILES 209950a7bd2Sbostic.Bl -tag -width /usr/share/locale/locale/LC_CTYPE -compact 210950a7bd2Sbostic.It Pa $PATH_LOCALE/\fIlocale\fP/LC_CTYPE 211950a7bd2Sbostic.It Pa /usr/share/locale/\fIlocale\fP/LC_CTYPE 212950a7bd2Sbosticbinary LC_CTYPE file for the locale \fIlocale\fP. 213950a7bd2Sbostic.El 214950a7bd2Sbostic.Sh "SEE ALSO 215950a7bd2Sbostic.Xr euc 4 , 216950a7bd2Sbostic.Xr mbrune 3 , 217950a7bd2Sbostic.Xr setlocale 3 , 218950a7bd2Sbostic.Xr utf2 4 219950a7bd2Sbostic.Sh NOTE 220950a7bd2SbosticThe ANSI C type 221950a7bd2Sbostic.Ev wchar_t 222950a7bd2Sbosticis the same as 223950a7bd2Sbostic.Ev rune_t . 224950a7bd2Sbostic.Ev Rune_t 225950a7bd2Sbosticwas chosen to accent the purposeful choice of not basing the 226950a7bd2Sbosticsystem with the ANSI C 227950a7bd2Sbosticprimitives, which were, shall we say, less aesthetic. 228950a7bd2Sbostic.Sh HISTORY 229950a7bd2SbosticThese functions first appeared in 230950a7bd2Sbostic.Bx 4.4 . 231950a7bd2Sbostic.Pp 232950a7bd2SbosticThe 233950a7bd2Sbostic.Fn setrunelocale 234950a7bd2Sbosticfunction and the other non-ANSI rune functions were inspired by 235950a7bd2Sbostic.Nm Plan 9 from Bell Labs 236950a7bd2Sbosticas a much more sane alternative to the ANSI multibyte and 237950a7bd2Sbosticwide character support. 23812deb868Sbostic.\"They were conceived at the San Diego 1993 Summer USENIX conference by 23912deb868Sbostic.\"Paul Borman of Krystal Technologies, Keith Bostic of CSRG and Andrew Hume 24012deb868Sbostic.\"of Bell Labs. 241950a7bd2Sbostic.Pp 242950a7bd2SbosticAll of the ANSI multibyte and wide character 243950a7bd2Sbosticsupport functions are built using the rune functions. 244