.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "TOWCTRANS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" towctrans 
.SH NAME
towctrans \- wide-character transliteration
.SH SYNOPSIS
.LP
\fB#include <wctype.h>
.br
.sp
wint_t towctrans(wint_t\fP \fIwc\fP\fB, wctrans_t\fP \fIdesc\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fItowctrans\fP() function shall transliterate the wide-character
code \fIwc\fP using the mapping described by
\fIdesc\fP. The current setting of the \fILC_CTYPE\fP category should
be the same as during the call to \fIwctrans\fP() that returned the
value \fIdesc\fP.   \ If the value
of \fIdesc\fP is invalid (that is, not obtained by a call to \fIwctrans\fP()
or
\fIdesc\fP is invalidated by a subsequent call to \fIsetlocale\fP()
that has affected
category \fILC_CTYPE ),\fP the result is unspecified.
.LP
An application wishing to check for error situations should set \fIerrno\fP
to 0 before calling \fItowctrans\fP(). If
\fIerrno\fP is non-zero on return, an error has occurred. 
.SH RETURN VALUE
.LP
If successful, the \fItowctrans\fP() function shall return the mapped
value of \fIwc\fP using the mapping described by
\fIdesc\fP. Otherwise, it shall return \fIwc\fP unchanged.
.SH ERRORS
.LP
The \fItowctrans\fP() function may fail if:
.TP 7
.B EINVAL
\fIdesc\fP contains an invalid transliteration descriptor. 
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
The strings \fB"tolower"\fP and \fB"toupper"\fP are reserved for the
standard mapping names. In the table below, the
functions in the left column are equivalent to the functions in the
right column.
.sp
.RS
.nf

\fBtowlower(\fP\fIwc\fP\fB)    towctrans(\fP\fIwc\fP\fB, wctrans("tolower"))
towupper(\fP\fIwc\fP\fB)    towctrans(\fP\fIwc\fP\fB, wctrans("toupper"))
\fP
.fi
.RE
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fItowlower\fP() , \fItowupper\fP() , \fIwctrans\fP() , the Base Definitions
volume of IEEE\ Std\ 1003.1-2001, \fI<wctype.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .