Home Library Learn Downloads Support Community
Sign in | United States - English | |
This topic has not yet been rated - Rate this topic

tolower, _tolower, towlower, _tolower_l, _towlower_l

Visual Studio 2010

Converts a character to lowercase.

Copy 
int tolower(
   int c 
);
int _tolower(
   int c 
);
int towlower(
   wint_t c 
);
int _tolower_l(
   int c,
   _locale_t locale 
);
int _towlower_l(
   wint_t c,
   _locale_t locale 
);
[in] c

Character to convert.

[in] locale

Locale to use for locale-specific translation.

Each of these routines converts a copy of c to lower case if the conversion is possible, and returns the result. There is no return value reserved to indicate an error.

Each of these routines converts a given uppercase letter to a lowercase letter if it is possible and relevant. The case conversion of towlower is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the _l suffix use the currently set locale. The versions of these functions that have the _l suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see Locale.

In order for _tolower to give the expected results, __isascii and isupper must both return nonzero.

Generic-Text Routine Mappings

TCHAR.H routine

_UNICODE & _MBCS not defined

_MBCS defined

_UNICODE defined

_totlower

tolower

_mbctolower

towlower

_totlower_l

_tolower_l

_mbctolower_l

_towlower_l

Note Note

_tolower_l and _towlower_l have no locale dependence and are not meant to be called directly. They are provided for internal use by _totlower_l.

Routine

Required header

tolower

<ctype.h>

_tolower

<ctype.h>

towlower

<ctype.h> or <wchar.h>

For additional compatibility information, see Compatibility in the Introduction.

See the example in to Functions.

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
There is no return value reserved to indicate an error.
The statement above is wrong. The current implementation of tolower() does use '?' in some circumstances to indicate a conversion error, which is actually in direct violation of the POSIX specifications, where c is to be returned if the conversion is not possible.

For instance, the following code:
#include <windows.h>
#include <stdio.h>
#include <ctype.h>
#include <locale.h>

int main(int argc, char** argv)
{
  int c = 0xe9;
  setlocale (LC_ALL,"English_Ireland.850");
  printf("Locale is: %s\n", setlocale(LC_ALL,NULL) );
  printf("tolower(0x%02x) = 0x%02x ('%c' -> '%c')\n", c, tolower(c), (char)c, (char)tolower(c));
  setlocale(LC_ALL,"English_United States.437");
  printf("Locale is: %s\n", setlocale(LC_ALL,NULL) );
  printf("tolower(0x%02x) = 0x%02x ('%c' -> '%c')\n", c, tolower(c), (char)c, (char)tolower(c));
  return 0;
}
Produces the following output:
Locale is: English_Ireland.850
tolower(0xe9) = 0xa3 ('Ú' -> 'ú')
Locale is: English_United States.437
tolower(0xe9) = 0x3f ('Ø' -> '?')

This means that '?', which isn't the lowercase counterpart of a character in any standard codepage, is being used as a return value to indicate an error.
If you use tolower() to convert a filename, this can spell trouble, as '?' is invalid for a filename and a call to CreateFile() will fail as a result.

Unless Microsoft fixes tolower() to only return a lowercase character or the original character if the conversion was not possible, programmers may want to be careful that the returned value may use '?' to indicate an error.
History