lib/libc/locale/rune.3

   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 .\" 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.
  22 .\"
  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.
  34 .\"
  35 .\"     @(#)rune.3      8.2 (Berkeley) 12/11/93
  36 .\"
  37 .Dd December 11, 1993
  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"
  57 .Pp
  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"
  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 .Aq Pa ctype.h .
  71 The
  72 .Fa locale
  73 argument indicates which locale 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.
 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 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.
 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/ Ns Em locale Ns /LC_CTYPE
 237 .It Pa /usr/share/locale/ Ns Em locale Ns /LC_CTYPE
 238 binary LC_CTYPE file for the locale
 239 .Em locale .
 240 .El
 241 .Sh "SEE ALSO
 242 .Xr mbrune 3 ,
 243 .Xr setlocale 3 ,
 244 .Xr euc 4 ,
 245 .Xr utf2 4
 246 .Sh NOTE
 247 The ANSI C type
 248 .Ev wchar_t
 249 is the same as
 250 .Ev rune_t .
 251 .Ev Rune_t
 252 was chosen to accent the purposeful choice of not basing the
 253 system with the ANSI C
 254 primitives, which were, shall we say, less aesthetic.
 255 .Sh HISTORY
 256 These functions first appeared in
 257 .Bx 4.4 .
 258 .Pp
 259 The
 260 .Fn setrunelocale
 261 function and the other non-ANSI rune functions were inspired by
 262 .Nm Plan 9 from Bell Labs
 263 as a much more sane alternative to the ANSI multibyte and
 264 wide character support.
 265 .\"They were conceived at the San Diego 1993 Summer USENIX conference by
 266 .\"Paul Borman of Krystal Technologies, Keith Bostic of CSRG and Andrew Hume
 267 .\"of Bell Labs.
 268 .Pp
 269 All of the ANSI multibyte and wide character
 270 support functions are built using the rune functions.