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  2014-03-18 "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 .sp
  24 .BI "wint_t towlower(wint_t " wc );
  25
  26 .BI "wint_t towlower_l(wint_t " wc ", locale_t " locale );
  27 .fi
  28 .sp
  29 .in -4n
  30 Feature Test Macro Requirements for glibc (see
  31 .BR feature_test_macros (7)):
  32 .in
  33 .sp
  34 .BR towlower_l ():
  35 .PD 0
  36 .RS 4
  37 .TP
  38 Since glibc 2.10:
  39 _XOPEN_SOURCE\ >=\ 700
  40 .TP
  41 Before glibc 2.10:
  42 _GNU_SOURCE
  43 .RE
  44 .PD
  45 .SH DESCRIPTION
  46 The
  47 .BR towlower ()
  48 function is the wide-character equivalent of the
  49 .BR tolower (3)
  50 function.
  51 If
  52 .I wc
  53 is an uppercase wide character,
  54 and there exists a lowercase equivalent in the current locale,
  55 it returns the lowercase equivalent of
  56 .IR wc .
  57 In all other cases,
  58 .I wc
  59 is returned unchanged.
  60
  61 The
  62 .BR towupper_l ()
  63 function performs the same task,
  64 but performs the conversion based on the character type information in
  65 the locale specified by
  66 .IR locale .
  67 The behavior of
  68 .BR towupper_l()
  69 is undefined if
  70 .I locale
  71 is the special locale object
  72 .BR LC_GLOBAL_LOCALE
  73 (see
  74 .BR duplocale (3))
  75 or is not a valid locale object handle.
  76
  77 The argument
  78 .I wc
  79 must be representable as a
  80 .IR wchar_t
  81 and be a valid character in the locale or be the value
  82 .BR WEOF .
  83 .SH RETURN VALUE
  84 If
  85 .I wc
  86 was convertible to lowercase,
  87 .BR towlower ()
  88 returns its lowercase equivalent;
  89 otherwise it returns
  90 .IR wc .
  91 .SH ATTRIBUTES
  92 .SS Multithreading (see pthreads(7))
  93 The
  94 .BR towlower ()
  95 function is thread-safe with exceptions.
  96 It can be safely used in multithreaded applications, as long as
  97 .BR setlocale (3)
  98 is not called to change the locale during its execution.
  99 .\" FIXME . need a thread-safety statement about towlower_l()
 100 .SH VERSIONS
 101 The
 102 .BR towlower_l ()
 103 function first appeared in glibc 2.3.
 104 .SH CONFORMING TO
 105 .BR towlower ():
 106 C99, POSIX.1-2001 (XSI);
 107 present as an XSI extension in POSIX.1-2008, but marked obsolete.
 108
 109 .BR towlower_l ():
 110 POSIX.1-2008.
 111 .SH NOTES
 112 The behavior of these functions depends on the
 113 .B LC_CTYPE
 114 category of the locale.
 115 .PP
 116 These functions are not very appropriate for dealing with Unicode characters,
 117 because Unicode knows about three cases: upper, lower and title case.
 118 .SH SEE ALSO
 119 .BR iswlower (3),
 120 .BR towctrans (3),
 121 .BR towupper (3),
 122 .BR locale (7)