man3/towlower.3

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