usr/src/man/man3c/wctrans.3c

   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 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  15 .\"
  16 .TH WCTRANS 3C "Jun 25, 2014"
  17
  18 .SH NAME
  19 towctrans, towctrans_l, wctrans, wctrans_l \- define and perform transliteration mappings
  20 .SH SYNOPSIS
  21 .LP
  22 .nf
  23 #include <wctype.h>
  24
  25 \fBwint_t\fR \fBtowctrans\fR(\fBwint_t\fR \fIwc\fR, \fBwctrans_t\fR \fIdesc\fR);
  26 .fi
  27 .LP
  28 .nf
  29 \fBwint_t\fR \fBtowctrans_l\fR(\fBwint_t\fR \fIwc\fR, \fBwctrans_t\fR \fIdesc\fR, \fBlocale_t\fR \fIloc\fR);
  30 .fi
  31 .LP
  32 .nf
  33 \fBwctrans_t\fR \fBwctrans\fR(\fBconst char *\fR \fItranclass\fR);
  34 .fi
  35 .LP
  36 .nf
  37 \fBwctrans_t\fR \fBwctrans_l\fR(\fBconst char *\fR \fItranclass\fR, \fBlocale_t\fR \fIloc\fR);
  38 .fi
  39 .SH DESCRIPTION
  40 .LP
  41 The functions
  42 .B wctrans()
  43 and
  44 .B wctrans_l()
  45 are used to obtain a handle to a table that maps one set of wide
  46 characters to another. They return an object of type
  47 .I wctrans_t
  48 which can be used with the functions
  49 .B towctrans()
  50 and
  51 .BR towctrans_l() .
  52 The valid set of classes that are available depends on the locale.
  53 The following names are valid in all locales:
  54 .TP
  55 "tolower"
  56 Conversion from upper case to lower case characters.
  57 .TP
  58 "toupper"
  59 Conversion from lower case to upper case characters.
  60 .LP
  61 The
  62 .B towctrans()
  63 and
  64 .B towctrans_l()
  65 functions convert the wide character
  66 .IR wc
  67 based on the conversion table specified by
  68 .IR desc .
  69 .LP
  70 The functions
  71 .B towctrans_l()
  72 and
  73 .B wctrans_l()
  74 are equivalent to the functions
  75 .B towctrans()
  76 and
  77 .BR wctrans() ,
  78 but instead of operating in the current locale, they operate on the
  79 locale specified by
  80 .IR loc .
  81 .SH RETURN VALUES
  82 On successful completion,
  83 .B towctrans()
  84 and
  85 .B towctrans_l()
  86 functions return the character that corresponds to the argument passed
  87 through the mapping table described by
  88 .IR desc .
  89 Otherwise, they return the character unchanged and set
  90 .BR errno .
  91 On successful completion,
  92 .B wctrans()
  93 and
  94 .B wctrans_l()
  95 functions return a non-zero identifier for
  96 .IR tranclass .
  97 On failure, they return zero and set
  98 .BR errno .
  99 .SH ERRORS
 100 .LP
 101 The
 102 .B wctrans()
 103 and
 104 .B wctrans_l()
 105 functions will fail if:
 106 .TP
 107 .B EINVAL
 108 The mapping class specified by
 109 .I tranclass
 110 does not exist or is invalid.
 111 .LP
 112 The
 113 .B towctrans()
 114 and
 115 .B towctrans_l()
 116 functions will fail if:
 117 .TP
 118 .B EINVAL
 119 The mapping class specified by
 120 .I desc
 121 is invalid.
 122 .SH ATTRIBUTES
 123 .TS
 124 box;
 125 c | c
 126 l | l .
 127 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 128 _
 129 Interface Stability     Standard
 130 _
 131 MT-Level        MT-Safe
 132 .TE
 133
 134 .SH SEE ALSO
 135 .BR newlocale (3C),
 136 .BR setlocale (3C),
 137 .BR towlower (3C),
 138 .BR towupper (3C),
 139 .BR environ (5),
 140 .BR locale (5)