locale/FreeBSD/wctrans.3

   1 .\" Copyright (c) 2002 Tim J. Robbins
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libc/locale/wctrans.3,v 1.3 2002/11/29 17:35:09 ru Exp $
  26 .\"
  27 .Dd October 3, 2002
  28 .Dt WCTRANS 3
  29 .Os
  30 .Sh NAME
  31 .Nm towctrans ,
  32 .Nm towctrans_l ,
  33 .Nm wctrans ,
  34 .Nm wctrans_l
  35 .Nd "wide character mapping functions"
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In wctype.h
  40 .Ft wint_t
  41 .Fo towctrans
  42 .Fa "wint_t wc"
  43 .Fa "wctrans_t desc"
  44 .Fc
  45 .Ft wctrans_t
  46 .Fo wctrans
  47 .Fa "const char *charclass"
  48 .Fc
  49 .In wctype.h
  50 .In xlocale.h
  51 .Ft wint_t
  52 .Fo towctrans_l
  53 .Fa "wint_t wc"
  54 .Fa "wctrans_t desc"
  55 .Fa "locale_t loc"
  56 .Fc
  57 .Ft wctrans_t
  58 .Fo wctrans_l
  59 .Fa "const char *charclass"
  60 .Fa "locale_t loc"
  61 .Fc
  62 .Sh DESCRIPTION
  63 The
  64 .Fn wctrans
  65 function returns a value of type
  66 .Vt wctrans_t ,
  67 which represents the requested wide character mapping operation and
  68 may be used as the second argument for calls to
  69 .Fn towctrans .
  70 .Pp
  71 The following character mapping names are recognised:
  72 .Bl -column -offset indent ".Li tolower" ".Li toupper"
  73 .It Li "tolower toupper"
  74 .El
  75 .Pp
  76 The
  77 .Fn towctrans
  78 function transliterates the wide character
  79 .Fa wc ,
  80 according to the mapping described by
  81 .Fa desc .
  82 .Pp
  83 While the
  84 .Fn towctrans
  85 and
  86 .Fn wctrans
  87 functions use the current locale, the
  88 .Fn towctrans_l
  89 and
  90 .Fn wctrans_l
  91 functions may be passed locales directly. See
  92 .Xr xlocale 3
  93 for more information.
  94 .Sh RETURN VALUES
  95 The
  96 .Fn towctrans
  97 function returns the transliterated character if successful, otherwise
  98 it returns the character unchanged and sets
  99 .Va errno .
 100 .Pp
 101 The
 102 .Fn wctrans
 103 function returns non-zero if successful, otherwise it returns zero
 104 and sets
 105 .Va errno .
 106 .Sh EXAMPLES
 107 Reimplement
 108 .Fn towupper
 109 in terms of
 110 .Fn towctrans
 111 and
 112 .Fn wctrans :
 113 .Bd -literal -offset indent
 114 wint_t
 115 mytowupper(wint_t wc)
 116 {
 117         return (towctrans(wc, wctrans("toupper")));
 118 }
 119 .Ed
 120 .Sh ERRORS
 121 The
 122 .Fn towctrans
 123 function will fail if:
 124 .Bl -tag -width Er
 125 .It Bq Er EINVAL
 126 The supplied
 127 .Fa desc
 128 argument is invalid.
 129 .El
 130 .Pp
 131 The
 132 .Fn wctrans
 133 function will fail if:
 134 .Bl -tag -width Er
 135 .It Bq Er EINVAL
 136 The requested mapping name is invalid.
 137 .El
 138 .Sh SEE ALSO
 139 .Xr tolower 3 ,
 140 .Xr toupper 3 ,
 141 .Xr wctype 3 ,
 142 .Xr xlocale 3
 143 .Sh STANDARDS
 144 The
 145 .Fn towctrans
 146 and
 147 .Fn wctrans
 148 functions conform to
 149 .St -p1003.1-2001 .
 150 .Sh HISTORY
 151 The
 152 .Fn towctrans
 153 and
 154 .Fn wctrans
 155 functions first appeared in
 156 .Fx 5.0 .