toupper(3)

✨ toupper(3) ✨ the get-your-letters-swole (or smol) manual

okay bestie, so this is a page from the Library Functions Manual, and it's all about toupper(3) — her whole friend group is here: toupper, tolower, toupper_l, tolower_l. 💅 Let's get into it.

---

🌸 NAME 🌸

toupper, tolower, toupper_l, tolower_l — convert uppercase or lowercase

Bestie. The name literally tells you the whole vibe: these functions flip your letters between big and little. That's the job. That's the era. 👑

---

🎀 LIBRARY 🎀

Standard C library (libc, -lc)

---

✨ SYNOPSIS ✨

#include <ctype.h>

int toupper(int c);
int tolower(int c);

int toupper_l(int c, locale_t locale);
int tolower_l(int c, locale_t locale);

🦋 Feature Test Macro Requirements for glibc 🦋

(pssst — see feature_test_macros(7) if you wanna know the lore)

toupper_l(), tolower_l():

• Since glibc 2.10:
  • _XOPEN_SOURCE >= 700
• Before glibc 2.10:
  • _GNU_SOURCE

---

💖 DESCRIPTION 💖

So like, the whole point: these functions convert lowercase letters to uppercase, and vice versa. Both directions, one page, no cap. 🔥

If c is a lowercase letter, toupper() returns its uppercase equivalent — if an uppercase representation exists in the current locale. Otherwise it just hands you back c, unchanged, no drama. And toupper_l()? Same task, but it uses the locale referred to by the locale handle locale. So it's the "I brought my own locale" version. 💅

If c is an uppercase letter, tolower() returns its lowercase equivalent — if a lowercase representation exists in the current locale. Otherwise, again, it returns c. And tolower_l() does the same task but uses the locale referred to by the locale handle locale.

🚨 WARNING, and I mean it: if c is neither an unsigned char value nor EOF, the behavior of these functions is undefined. Not "a little weird". Undefined. Do not test her.

🚨 And another one: the behavior of toupper_l() and tolower_l() is undefined if locale is the special locale object LC_GLOBAL_LOCALE (see duplocale(3)) or is not a valid locale object handle. So pls, keep your locale handles valid, I'm begging. 🙈

---

⭐ RETURN VALUE ⭐

The value returned is that of the converted letter, or c if the conversion was not possible. Simple. She either glows you up or leaves you exactly as you were. Iconic behavior honestly. 💜

---

🌈 ATTRIBUTES 🌈

For the full explanation of the terms used in this section, go peek at attributes(7). Here's the tea:

• Interface: toupper(), tolower(), toupper_l(), tolower_l() — Attribute: Thread safety — Value: MT-Safe

That's it bestie, whole squad is MT-Safe, so they can hang out with all your threads at once. 🫶

---

🧚 STANDARDS 🧚

• toupper()
• tolower()
  • C11, POSIX.1-2008.
• toupper_l()
• tolower_l()
  • POSIX.1-2008.

---

💀 HISTORY 💀

• toupper()
• tolower()
  • C89, 4.3BSD, POSIX.1-2001.
• toupper_l()
• tolower_l()
  • POSIX.1-2008.

---

🌸 NOTES 🌸

The standards require that the argument c for these functions is either EOF or a value that is representable in the type unsigned char. So if your argument c is of type char, it must be cast to unsigned char, like this:

char c;
...
res = toupper((unsigned char) c);

Why though? Because char may be the equivalent of signed char, in which case a byte where the top bit is set would be sign extended when converting to int, yielding a value that is outside the range of unsigned char. So yeah — that cast is not optional, it's the moment. ✨

The details of what constitutes an uppercase or lowercase letter depend on the locale. For example, the default "C" locale does not know about umlauts, so no conversion is done for them. She simply doesn't know them. 😭

And in some non-English locales, there are lowercase letters with no corresponding uppercase equivalent — the German sharp s is one example. Some letters truly live alone. Respect it. 🍓

---

🦋 SEE ALSO 🦋

isalpha(3), newlocale(3), setlocale(3), towlower(3), towupper(3), uselocale(3), locale(7)

---

okay that's the whole page, you ate it, you understood it, I'm so proud of you 💖

this has been brought to you by Linux man-pages 6.20, dated 2026-02-08, and yes, toupper(3) said it herself. mwah. 💅✨