man3/towlower.3

   1 '\" t
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   3 .\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-2.0-or-later
   6 .\"
   7 .\" References consulted:
   8 .\"   GNU glibc-2 source code and manual
   9 .\"   Dinkumware C library reference http://www.dinkumware.com/
  10 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  11 .\"   ISO/IEC 9899:1999
  12 .\"
  13 .TH towlower 3 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 towlower, towlower_l \- convert a wide character to lowercase
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <wctype.h>
  22 .PP
  23 .BI "wint_t towlower(wint_t " wc );
  24 .BI "wint_t towlower_l(wint_t " wc ", locale_t " locale );
  25 .fi
  26 .PP
  27 .RS -4
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .RE
  31 .PP
  32 .BR towlower_l ():
  33 .nf
  34     Since glibc 2.10:
  35         _XOPEN_SOURCE >= 700
  36     Before glibc 2.10:
  37         _GNU_SOURCE
  38 .fi
  39 .SH DESCRIPTION
  40 The
  41 .BR towlower ()
  42 function is the wide-character equivalent of the
  43 .BR tolower (3)
  44 function.
  45 If
  46 .I wc
  47 is an uppercase wide character,
  48 and there exists a lowercase equivalent in the current locale,
  49 it returns the lowercase equivalent of
  50 .IR wc .
  51 In all other cases,
  52 .I wc
  53 is returned unchanged.
  54 .PP
  55 The
  56 .BR towlower_l ()
  57 function performs the same task,
  58 but performs the conversion based on the character type information in
  59 the locale specified by
  60 .IR locale .
  61 The behavior of
  62 .BR towlower_l ()
  63 is undefined if
  64 .I locale
  65 is the special locale object
  66 .B LC_GLOBAL_LOCALE
  67 (see
  68 .BR duplocale (3))
  69 or is not a valid locale object handle.
  70 .PP
  71 The argument
  72 .I wc
  73 must be representable as a
  74 .I wchar_t
  75 and be a valid character in the locale or be the value
  76 .BR WEOF .
  77 .SH RETURN VALUE
  78 If
  79 .I wc
  80 was convertible to lowercase,
  81 .BR towlower ()
  82 returns its lowercase equivalent;
  83 otherwise it returns
  84 .IR wc .
  85 .SH ATTRIBUTES
  86 For an explanation of the terms used in this section, see
  87 .BR attributes (7).
  88 .TS
  89 allbox;
  90 lbx lb lb
  91 l l l.
  92 Interface       Attribute       Value
  93 T{
  94 .na
  95 .nh
  96 .BR towlower ()
  97 T}      Thread safety   MT-Safe locale
  98 T{
  99 .na
 100 .nh
 101 .BR towlower_l ()
 102 T}      Thread safety   MT-Safe
 103 .TE
 104 .sp 1
 105 .SH STANDARDS
 106 .TP
 107 .BR towlower ()
 108 C11, POSIX.1-2008 (XSI).
 109 .TP
 110 .BR towlower_l ()
 111 POSIX.1-2008.
 112 .SH STANDARDS
 113 .TP
 114 .BR towlower ()
 115 C99, POSIX.1-2001 (XSI).
 116 Obsolete in POSIX.1-2008 (XSI).
 117 .TP
 118 .BR towlower_l ()
 119 glibc 2.3.
 120 POSIX.1-2008.
 121 .SH NOTES
 122 The behavior of these functions depends on the
 123 .B LC_CTYPE
 124 category of the locale.
 125 .PP
 126 These functions are not very appropriate for dealing with Unicode characters,
 127 because Unicode knows about three cases: upper, lower, and title case.
 128 .SH SEE ALSO
 129 .BR iswlower (3),
 130 .BR towctrans (3),
 131 .BR towupper (3),
 132 .BR locale (7)