xref: /freebsd/lib/libc/locale/wctrans.3 (revision f4b37ed0f8b307b1f3f0f630ca725d68f1dff30d)
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$
26.\"
27.Dd October 3, 2002
28.Dt WCTRANS 3
29.Os
30.Sh NAME
31.Nm towctrans , wctrans
32.Nd "wide character mapping functions"
33.Sh LIBRARY
34.Lb libc
35.Sh SYNOPSIS
36.In wctype.h
37.Ft wint_t
38.Fn towctrans "wint_t wc" "wctrans_t desc"
39.Ft wctrans_t
40.Fn wctrans "const char *charclass"
41.Sh DESCRIPTION
42The
43.Fn wctrans
44function returns a value of type
45.Vt wctrans_t
46which represents the requested wide character mapping operation and
47may be used as the second argument for calls to
48.Fn towctrans .
49.Pp
50The following character mapping names are recognised:
51.Bl -column -offset indent ".Li tolower" ".Li toupper"
52.It Li "tolower	toupper"
53.El
54.Pp
55The
56.Fn towctrans
57function transliterates the wide character
58.Fa wc
59according to the mapping described by
60.Fa desc .
61.Sh RETURN VALUES
62The
63.Fn towctrans
64function returns the transliterated character if successful, otherwise
65it returns the character unchanged and sets
66.Va errno .
67.Pp
68The
69.Fn wctrans
70function returns non-zero if successful, otherwise it returns zero
71and sets
72.Va errno .
73.Sh EXAMPLES
74Reimplement
75.Fn towupper
76in terms of
77.Fn towctrans
78and
79.Fn wctrans :
80.Bd -literal -offset indent
81wint_t
82mytowupper(wint_t wc)
83{
84	return (towctrans(wc, wctrans("toupper")));
85}
86.Ed
87.Sh ERRORS
88The
89.Fn towctrans
90function will fail if:
91.Bl -tag -width Er
92.It Bq Er EINVAL
93The supplied
94.Fa desc
95argument is invalid.
96.El
97.Pp
98The
99.Fn wctrans
100function will fail if:
101.Bl -tag -width Er
102.It Bq Er EINVAL
103The requested mapping name is invalid.
104.El
105.Sh SEE ALSO
106.Xr tolower 3 ,
107.Xr toupper 3 ,
108.Xr wctype 3
109.Sh STANDARDS
110The
111.Fn towctrans
112and
113.Fn wctrans
114functions conform to
115.St -p1003.1-2001 .
116.Sh HISTORY
117The
118.Fn towctrans
119and
120.Fn wctrans
121functions first appeared in
122.Fx 5.0 .
123