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 .\" $FreeBSD: src/lib/libc/locale/rune.3,v 1.10.2.7 2002/08/07 06:24:14 ache Exp $
  37 .\"
  38 .Dd December 11, 1993
  39 .Dt RUNE 3
  40 .Os
  41 .Sh NAME
  42 .Nm setrunelocale ,
  43 .Nm setinvalidrune ,
  44 .Nm sgetrune ,
  45 .Nm sputrune ,
  46 .Nm fgetrune ,
  47 .Nm fungetrune ,
  48 .Nm fputrune
  49 .Nd rune support for C
  50 .Sh LIBRARY
  51 .Lb libc
  52 .Sh SYNOPSIS
  53 .In rune.h
  54 .In errno.h
  55 .Ft int
  56 .Fn setrunelocale "char *locale"
  57 .Ft void
  58 .Fn setinvalidrune "rune_t rune"
  59 .Ft rune_t
  60 .Fn sgetrune "const char *string" "size_t n" "char const **result"
  61 .Ft int
  62 .Fn sputrune "rune_t rune" "char *string" "size_t n" "char **result"
  63 .Pp
  64 .In stdio.h
  65 .Ft long
  66 .Fn fgetrune "FILE *stream"
  67 .Ft int
  68 .Fn fungetrune "rune_t rune" "FILE *stream"
  69 .Ft int
  70 .Fn fputrune "rune_t rune" "FILE *stream"
  71 .Sh DESCRIPTION
  72 The
  73 .Fn setrunelocale
  74 controls the type of encoding used to represent runes as multibyte strings
  75 as well as the properties of the runes as defined in
  76 .Aq Pa ctype.h .
  77 The
  78 .Fa locale
  79 argument indicates which locale to load.
  80 If the locale is successfully loaded,
  81 .Dv 0
  82 is returned, otherwise an errno value is returned to indicate the
  83 type of error.
  84 .Pp
  85 The
  86 .Fn setinvalidrune
  87 function sets the value of the global value
  88 .Dv _INVALID_RUNE
  89 to be
  90 .Fa rune .
  91 .Pp
  92 The
  93 .Fn sgetrune
  94 function tries to read a single multibyte character from
  95 .Fa string ,
  96 which is at most
  97 .Fa n
  98 bytes long.
  99 If
 100 .Fn sgetrune
 101 is successful, the rune is returned.
 102 If
 103 .Fa result
 104 is not
 105 .Dv NULL ,
 106 .Fa *result
 107 will point to the first byte which was not converted in
 108 .Fa string .
 109 If the first
 110 .Fa n
 111 bytes of
 112 .Fa string
 113 do not describe a full multibyte character,
 114 .Dv _INVALID_RUNE
 115 is returned and
 116 .Fa *result
 117 will point to
 118 .Fa string .
 119 If there is an encoding error at the start of
 120 .Fa string ,
 121 .Dv _INVALID_RUNE
 122 is returned and
 123 .Fa *result
 124 will point to the second character of
 125 .Fa string .
 126 .Pp
 127 the
 128 .Fn sputrune
 129 function tries to encode
 130 .Fa rune
 131 as a multibyte string and store it at
 132 .Fa string ,
 133 but no more than
 134 .Fa n
 135 bytes will be stored.
 136 If
 137 .Fa result
 138 is not
 139 .Dv NULL ,
 140 .Fa *result
 141 will be set to point to the first byte in string following the new
 142 multibyte character.
 143 If
 144 .Fa string
 145 is
 146 .Dv NULL ,
 147 .Fa *result
 148 will point to
 149 .Dv "(char *)0 +"
 150 .Fa x ,
 151 where
 152 .Fa x
 153 is the number of bytes that would be needed to store the multibyte value.
 154 If the multibyte character would consist of more than
 155 .Fa n
 156 bytes and
 157 .Fa result
 158 is not
 159 .Dv NULL ,
 160 .Fa *result
 161 will be set to
 162 .Dv NULL .
 163 In all cases,
 164 .Fn sputrune
 165 will return the number of bytes which would be needed to store
 166 .Fa rune
 167 as a multibyte character.
 168 .Pp
 169 The
 170 .Fn fgetrune
 171 function operates the same as
 172 .Fn sgetrune
 173 with the exception that it attempts to read enough bytes from
 174 .Fa stream
 175 to decode a single rune.  It returns either
 176 .Dv EOF
 177 on end of file,
 178 .Dv _INVALID_RUNE
 179 on an encoding error, or the rune decoded if all went well.
 180 .Pp
 181 The
 182 .Fn fungetrune
 183 function pushes the multibyte encoding, as provided by
 184 .Fn sputrune ,
 185 of
 186 .Fa rune
 187 onto
 188 .Fa stream
 189 such that the next
 190 .Fn fgetrune
 191 call will return
 192 .Fa rune .
 193 It returns
 194 .Dv EOF
 195 if it fails and
 196 .Dv 0
 197 on success.
 198 .Pp
 199 The
 200 .Fn fputrune
 201 function writes the multibyte encoding of
 202 .Fa rune ,
 203 as provided by
 204 .Fn sputrune ,
 205 onto
 206 .Fa stream .
 207 It returns
 208 .Dv EOF
 209 on failure and
 210 .Dv 0
 211 on success.
 212 .Sh RETURN VALUES
 213 The
 214 .Fn setrunelocale
 215 function returns one of the following values:
 216 .Bl -tag -width Er
 217 .It Er 0
 218 .Fn setrunelocale
 219 was successful.
 220 .It Bq Er EINVAL
 221 .Fa locale
 222 name was incorrect.
 223 .It Bq Er ENOENT
 224 The locale could not be found.
 225 .It Bq Er EFTYPE
 226 The file found was not a valid file.
 227 .El
 228 .Pp
 229 The
 230 .Fn sgetrune
 231 function either returns the rune read or
 232 .Dv _INVALID_RUNE .
 233 The
 234 .Fn sputrune
 235 function returns the number of bytes needed to store
 236 .Fa rune
 237 as a multibyte string.
 238 .Sh FILES
 239 .Bl -tag -width /usr/share/locale/locale/LC_CTYPE -compact
 240 .It Pa $PATH_LOCALE/ Ns Em locale Ns /LC_CTYPE
 241 .It Pa /usr/share/locale/ Ns Em locale Ns /LC_CTYPE
 242 binary LC_CTYPE file for the locale
 243 .Em locale .
 244 .El
 245 .Sh SEE ALSO
 246 .Xr mbrune 3 ,
 247 .Xr setlocale 3 ,
 248 .Xr euc 4 ,
 249 .Xr utf2 4
 250 .Sh NOTES
 251 The ANSI C type
 252 .Em wchar_t
 253 is the same as
 254 .Em rune_t .
 255 .Em Rune_t
 256 was chosen to accent the purposeful choice of not basing the
 257 system with the ANSI C
 258 primitives, which were, shall we say, less aesthetic.
 259 .Sh HISTORY
 260 These functions first appeared in
 261 .Bx 4.4 .
 262 .Pp
 263 The
 264 .Fn setrunelocale
 265 function and the other non-ANSI rune functions were inspired by
 266 .Sy "Plan 9 from Bell Labs"
 267 as a much more sane alternative to the ANSI multibyte and
 268 wide character support.
 269 .\"They were conceived at the San Diego 1993 Summer USENIX conference by
 270 .\"Paul Borman of Krystal Technologies, Keith Bostic of CSRG and Andrew Hume
 271 .\"of Bell Labs.
 272 .Pp
 273 All of the ANSI multibyte and wide character
 274 support functions are built using the rune functions.