The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### NAME

> towctrans, towctrans_l - wide-character transliteration

#### SYNOPSIS

> ``#include <wctype.h>
> wint_t towctrans(wint_t` wc`, wctrans_t` desc`);
> ``

> ``[CX] wint_t towctrans_l(wint_t` wc`, wctrans_t` desc`,
> locale_t` locale`);``
> `
> `

#### DESCRIPTION

> For towctrans(): [CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2008 defers to the ISO C standard.

> The towctrans() [CX] and towctrans_l() functions shall transliterate the wide-character code wc using the mapping described by desc.

> The current setting of the LC_CTYPE category in the current locale [CX] or in the locale represented by locale, respectively, should be the same as during the call to wctrans() [CX] or wctrans_l() that returned the value desc.

> If the value of desc is invalid (that is, not obtained by a call to wctrans() or desc is invalidated by a subsequent call to setlocale() that has affected category LC_CTYPE), the result is unspecified.

> [CX] If the value of desc is invalid (that is, not obtained by a call to wctrans_l() with the same locale object locale) the result is unspecified.

> [CX] An application wishing to check for error situations should set errno to 0 before calling towctrans() or towctrans_l().

> If errno is non-zero on return, an error has occurred.

> The behavior is undefined if the locale argument to towctrans_l() is the special locale object LC_GLOBAL_LOCALE or is not a valid locale object handle.

#### RETURN VALUE

> If successful, the towctrans() [CX] and towctrans_l() functions shall return the mapped value of wc using the mapping described by desc. Otherwise, they shall return wc unchanged.

#### ERRORS

> These functions may fail if:

> [EINVAL]
>   [CX] desc contains an invalid transliteration descriptor.

The following sections are informative.

#### EXAMPLES

> None.

#### APPLICATION USAGE

> The strings `"tolower"` and `"toupper"` 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.

>     towlower(wc)            towctrans(wc, wctrans("tolower"))
>     towlower_l(wc, locale)  towctrans_l(wc, wctrans("tolower"), locale)
>     towupper(wc)            towctrans(wc, wctrans("toupper"))
>     towupper_l(wc, locale)  towctrans_l(wc, wctrans("toupper"), locale)

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> towlower, towupper, wctrans

> XBD <wctype.h>

#### CHANGE HISTORY

> First released in Issue 5. Derived from ISO/IEC 9899:1990/Amendment 1:1995 (E).

#### Issue 6

> Extensions beyond the ISO C standard are marked.

#### Issue 7

> The towctrans_l() function is added from The Open Group Technical Standard, 2006, Extended API Set Part 4.

> POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0675 [302], XSH/TC1-2008/0676 [283], and XSH/TC1-2008/0677 [283] are applied.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]