1 '\" te
   2 .\"
   3 .\" This file and its contents are supplied under the terms of the
   4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   5 .\" You may only use this file in accordance with the terms of version
   6 .\" 1.0 of the CDDL.
   7 .\"
   8 .\" A full copy of the text of the CDDL should have accompanied this
   9 .\" source.  A copy of the CDDL is also available via the Internet at
  10 .\" http://www.illumos.org/license/CDDL.
  11 .\"
  12 .\"
  13 .\" Copyright (c) 2014 Joyent, Inc.  All rights reserved.
  14 .\"
  15 .TH WCTRANS 3C "Jun 11, 2014"
  16 
  17 .SH NAME
  18 
  19 towctrans, towctrans_l, wctrans, wctrans_l \- define and perform transliteration mappings
  20 
  21 .SH SYNOPSIS
  22 
  23 .LP
  24 .nf
  25 #include <wctype.h>
  26 
  27 .BI "wint_t towctrans(wint_t " wc ", wctrans_t " desc );
  28 .BI "wint_t towctrans_l(wint_t " wc ", wctrans_t " desc ", locale_t " loc );
  29 
  30 .BI "wctrans_t wctrans(const char *" class );
  31 .BI "wctrans_t wctrans_l(const char *" class, " locale_t " loc );
  32 
  33 .SH DESCRIPTION
  34 
  35 The function
  36 .B wctrans
  37 is used to obtain a handle to a mapping table that maps one set of wide
  38 characters to another. It returns an object of type
  39 .I wctrans_t
  40 which can be used with the functions
  41 .B towctrans()
  42 and
  43 .BR towctrans_l() .
  44 The valid set of classes that are available depends on the locale.
  45 Regardless of what locale is being used, the following names are always
  46 valid:
  47 
  48 .na
  49 .in +2
  50 .I tolower
  51 .in -2
  52 .fi
  53 
  54 .na
  55 .in +2
  56 .I toupper
  57 .in -2
  58 .fi
  59 .sp
  60 .LP
  61 The
  62 .B towctrans()
  63 function converts the wide character
  64 .IR wc
  65  based on the conversion table
  66 specified by
  67 .IR desc .
  68 
  69 
  70 .LP
  71 The functions
  72 .B towctrans_l
  73 and
  74 .B wctrans_l
  75 are equivalent to the functions
  76 .B towctrans
  77 and
  78 .BR wctrans ,
  79 but instead of operating in the current environemnt, they operate on the
  80 environment specified by
  81 .IR loc .
  82 
  83 .SH RETURN VALUES
  84 
  85 On successful completion,
  86 .B towctrans()
  87 and
  88 .B towctrans_l()
  89 functions return the character that corresponds to the argument passed
  90 through the mapping table described by
  91 .IR desc .
  92 Otherwise, it returns the character unchanged and sets
  93 .BR errno .
  94 
  95 On successful completion,
  96 .B wctrans()
  97 and
  98 .B wctrans_l()
  99 functions return a non-zero identifier for
 100 .IR class .
 101 On failure, they return zero and set
 102 .BR errno .
 103 
 104 
 105 .SH ERRORS
 106 .LP
 107 The
 108 .B wctrans()
 109 and
 110 .B wctrans_l()
 111 functions will fail if:
 112 .sp
 113 .ne 2
 114 .na
 115 .B EINAVL
 116 .ad
 117 .RS 10n
 118 The mapping class specified by
 119 .I class
 120 does not exist or is invalid.
 121 .RE
 122 
 123 .LP
 124 The
 125 .B towctrans()
 126 and
 127 .B towctrans_l()
 128 functions will fail if:
 129 .sp
 130 .ne 2
 131 .na
 132 .B EINAVL
 133 .ad
 134 .RS 10n
 135 The mapping class specified by
 136 .I desc
 137 is invalid.
 138 .RE
 139 
 140 .SH ATTRIBUTES
 141 .sp
 142 .TS
 143 box;
 144 c | c
 145 l | l .
 146 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 147 _
 148 Interface Stability     Standard
 149 _
 150 MT-Level        Safe, with exceptions
 151 .TE
 152 
 153 .SH SEE ALSO
 154 .BR duplocale (3C),
 155 .BR newlocale (3C),
 156 .BR setlocale (3C),
 157 .BR towlower (3C),
 158 .BR towupper (3C),
 159 .BR environ (5),
 160 .BR locale (5)
 161 
 162 .SH NOTES
 163 
 164 The functions
 165 .B towctrans()
 166 and
 167 .B wctrans()
 168 are thread-safe as long as
 169 the thread is emplying a per-thread locale as set per
 170 .B uselocale(3C)
 171 or
 172 .B setlocale(3C)
 173 is not called by another thread while these functions are running.
 174 Both
 175 .B towctrans_l()
 176 and
 177 .B wctrans_l()
 178 are MT-safe.