(openlog): Describe possible problems with string passed as first parameter.
[kopensolaris-gnu/glibc.git] / manual / ctype.texi
1 @node Character Handling, String and Array Utilities, Memory, Top
2 @c %MENU% Character testing and conversion functions
3 @chapter Character Handling
4
5 Programs that work with characters and strings often need to classify a
6 character---is it alphabetic, is it a digit, is it whitespace, and so
7 on---and perform case conversion operations on characters.  The
8 functions in the header file @file{ctype.h} are provided for this
9 purpose.
10 @pindex ctype.h
11
12 Since the choice of locale and character set can alter the
13 classifications of particular character codes, all of these functions
14 are affected by the current locale.  (More precisely, they are affected
15 by the locale currently selected for character classification---the
16 @code{LC_CTYPE} category; see @ref{Locale Categories}.)
17
18 The @w{ISO C} standard specifies two different sets of functions.  The
19 one set works on @code{char} type characters, the other one on
20 @code{wchar_t} wide characters (@pxref{Extended Char Intro}).
21
22 @menu
23 * Classification of Characters::       Testing whether characters are
24                                         letters, digits, punctuation, etc.
25
26 * Case Conversion::                    Case mapping, and the like.
27 * Classification of Wide Characters::  Character class determination for
28                                         wide characters.
29 * Using Wide Char Classes::            Notes on using the wide character
30                                         classes.
31 * Wide Character Case Conversion::     Mapping of wide characters.
32 @end menu
33
34 @node Classification of Characters, Case Conversion,  , Character Handling
35 @section Classification of Characters
36 @cindex character testing
37 @cindex classification of characters
38 @cindex predicates on characters
39 @cindex character predicates
40
41 This section explains the library functions for classifying characters.
42 For example, @code{isalpha} is the function to test for an alphabetic
43 character.  It takes one argument, the character to test, and returns a
44 nonzero integer if the character is alphabetic, and zero otherwise.  You
45 would use it like this:
46
47 @smallexample
48 if (isalpha (c))
49   printf ("The character `%c' is alphabetic.\n", c);
50 @end smallexample
51
52 Each of the functions in this section tests for membership in a
53 particular class of characters; each has a name starting with @samp{is}.
54 Each of them takes one argument, which is a character to test, and
55 returns an @code{int} which is treated as a boolean value.  The
56 character argument is passed as an @code{int}, and it may be the
57 constant value @code{EOF} instead of a real character.
58
59 The attributes of any given character can vary between locales.
60 @xref{Locales}, for more information on locales.@refill
61
62 These functions are declared in the header file @file{ctype.h}.
63 @pindex ctype.h
64
65 @cindex lower-case character
66 @comment ctype.h
67 @comment ISO
68 @deftypefun int islower (int @var{c})
69 Returns true if @var{c} is a lower-case letter.  The letter need not be
70 from the Latin alphabet, any alphabet representable is valid.
71 @end deftypefun
72
73 @cindex upper-case character
74 @comment ctype.h
75 @comment ISO
76 @deftypefun int isupper (int @var{c})
77 Returns true if @var{c} is an upper-case letter.  The letter need not be
78 from the Latin alphabet, any alphabet representable is valid.
79 @end deftypefun
80
81 @cindex alphabetic character
82 @comment ctype.h
83 @comment ISO
84 @deftypefun int isalpha (int @var{c})
85 Returns true if @var{c} is an alphabetic character (a letter).  If
86 @code{islower} or @code{isupper} is true of a character, then
87 @code{isalpha} is also true.
88
89 In some locales, there may be additional characters for which
90 @code{isalpha} is true---letters which are neither upper case nor lower
91 case.  But in the standard @code{"C"} locale, there are no such
92 additional characters.
93 @end deftypefun
94
95 @cindex digit character
96 @cindex decimal digit character
97 @comment ctype.h
98 @comment ISO
99 @deftypefun int isdigit (int @var{c})
100 Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}).
101 @end deftypefun
102
103 @cindex alphanumeric character
104 @comment ctype.h
105 @comment ISO
106 @deftypefun int isalnum (int @var{c})
107 Returns true if @var{c} is an alphanumeric character (a letter or
108 number); in other words, if either @code{isalpha} or @code{isdigit} is
109 true of a character, then @code{isalnum} is also true.
110 @end deftypefun
111
112 @cindex hexadecimal digit character
113 @comment ctype.h
114 @comment ISO
115 @deftypefun int isxdigit (int @var{c})
116 Returns true if @var{c} is a hexadecimal digit.
117 Hexadecimal digits include the normal decimal digits @samp{0} through
118 @samp{9} and the letters @samp{A} through @samp{F} and
119 @samp{a} through @samp{f}.
120 @end deftypefun
121
122 @cindex punctuation character
123 @comment ctype.h
124 @comment ISO
125 @deftypefun int ispunct (int @var{c})
126 Returns true if @var{c} is a punctuation character.
127 This means any printing character that is not alphanumeric or a space
128 character.
129 @end deftypefun
130
131 @cindex whitespace character
132 @comment ctype.h
133 @comment ISO
134 @deftypefun int isspace (int @var{c})
135 Returns true if @var{c} is a @dfn{whitespace} character.  In the standard
136 @code{"C"} locale, @code{isspace} returns true for only the standard
137 whitespace characters:
138
139 @table @code
140 @item ' '
141 space
142
143 @item '\f'
144 formfeed
145
146 @item '\n'
147 newline
148
149 @item '\r'
150 carriage return
151
152 @item '\t'
153 horizontal tab
154
155 @item '\v'
156 vertical tab
157 @end table
158 @end deftypefun
159
160 @cindex blank character
161 @comment ctype.h
162 @comment GNU
163 @deftypefun int isblank (int @var{c})
164 Returns true if @var{c} is a blank character; that is, a space or a tab.
165 This function is a GNU extension.
166 @end deftypefun
167
168 @cindex graphic character
169 @comment ctype.h
170 @comment ISO
171 @deftypefun int isgraph (int @var{c})
172 Returns true if @var{c} is a graphic character; that is, a character
173 that has a glyph associated with it.  The whitespace characters are not
174 considered graphic.
175 @end deftypefun
176
177 @cindex printing character
178 @comment ctype.h
179 @comment ISO
180 @deftypefun int isprint (int @var{c})
181 Returns true if @var{c} is a printing character.  Printing characters
182 include all the graphic characters, plus the space (@samp{ }) character.
183 @end deftypefun
184
185 @cindex control character
186 @comment ctype.h
187 @comment ISO
188 @deftypefun int iscntrl (int @var{c})
189 Returns true if @var{c} is a control character (that is, a character that
190 is not a printing character).
191 @end deftypefun
192
193 @cindex ASCII character
194 @comment ctype.h
195 @comment SVID, BSD
196 @deftypefun int isascii (int @var{c})
197 Returns true if @var{c} is a 7-bit @code{unsigned char} value that fits
198 into the US/UK ASCII character set.  This function is a BSD extension
199 and is also an SVID extension.
200 @end deftypefun
201
202 @node Case Conversion, Classification of Wide Characters, Classification of Characters, Character Handling
203 @section Case Conversion
204 @cindex character case conversion
205 @cindex case conversion of characters
206 @cindex converting case of characters
207
208 This section explains the library functions for performing conversions
209 such as case mappings on characters.  For example, @code{toupper}
210 converts any character to upper case if possible.  If the character
211 can't be converted, @code{toupper} returns it unchanged.
212
213 These functions take one argument of type @code{int}, which is the
214 character to convert, and return the converted character as an
215 @code{int}.  If the conversion is not applicable to the argument given,
216 the argument is returned unchanged.
217
218 @strong{Compatibility Note:} In pre-@w{ISO C} dialects, instead of
219 returning the argument unchanged, these functions may fail when the
220 argument is not suitable for the conversion.  Thus for portability, you
221 may need to write @code{islower(c) ? toupper(c) : c} rather than just
222 @code{toupper(c)}.
223
224 These functions are declared in the header file @file{ctype.h}.
225 @pindex ctype.h
226
227 @comment ctype.h
228 @comment ISO
229 @deftypefun int tolower (int @var{c})
230 If @var{c} is an upper-case letter, @code{tolower} returns the corresponding
231 lower-case letter.  If @var{c} is not an upper-case letter,
232 @var{c} is returned unchanged.
233 @end deftypefun
234
235 @comment ctype.h
236 @comment ISO
237 @deftypefun int toupper (int @var{c})
238 If @var{c} is a lower-case letter, @code{toupper} returns the corresponding
239 upper-case letter.  Otherwise @var{c} is returned unchanged.
240 @end deftypefun
241
242 @comment ctype.h
243 @comment SVID, BSD
244 @deftypefun int toascii (int @var{c})
245 This function converts @var{c} to a 7-bit @code{unsigned char} value
246 that fits into the US/UK ASCII character set, by clearing the high-order
247 bits.  This function is a BSD extension and is also an SVID extension.
248 @end deftypefun
249
250 @comment ctype.h
251 @comment SVID
252 @deftypefun int _tolower (int @var{c})
253 This is identical to @code{tolower}, and is provided for compatibility
254 with the SVID.  @xref{SVID}.@refill
255 @end deftypefun
256
257 @comment ctype.h
258 @comment SVID
259 @deftypefun int _toupper (int @var{c})
260 This is identical to @code{toupper}, and is provided for compatibility
261 with the SVID.
262 @end deftypefun
263
264
265 @node Classification of Wide Characters, Using Wide Char Classes, Case Conversion, Character Handling
266 @section Character class determination for wide characters
267
268 @w{Amendment 1} to @w{ISO C90} defines functions to classify wide
269 characters.  Although the original @w{ISO C90} standard already defined
270 the type @code{wchar_t}, no functions operating on them were defined.
271
272 The general design of the classification functions for wide characters
273 is more general.  It allows extensions to the set of available
274 classifications, beyond those which are always available.  The POSIX
275 standard specifies how extensions can be made, and this is already
276 implemented in the GNU C library implementation of the @code{localedef}
277 program.
278
279 The character class functions are normally implemented with bitsets,
280 with a bitset per character.  For a given character, the appropriate
281 bitset is read from a table and a test is performed as to whether a
282 certain bit is set.  Which bit is tested for is determined by the
283 class.
284
285 For the wide character classification functions this is made visible.
286 There is a type classification type defined, a function to retrieve this
287 value for a given class, and a function to test whether a given
288 character is in this class, using the classification value.  On top of
289 this the normal character classification functions as used for
290 @code{char} objects can be defined.
291
292 @comment wctype.h
293 @comment ISO
294 @deftp {Data type} wctype_t
295 The @code{wctype_t} can hold a value which represents a character class.
296 The only defined way to generate such a value is by using the
297 @code{wctype} function.
298
299 @pindex wctype.h
300 This type is defined in @file{wctype.h}.
301 @end deftp
302
303 @comment wctype.h
304 @comment ISO
305 @deftypefun wctype_t wctype (const char *@var{property})
306 The @code{wctype} returns a value representing a class of wide
307 characters which is identified by the string @var{property}.  Beside
308 some standard properties each locale can define its own ones.  In case
309 no property with the given name is known for the current locale
310 selected for the @code{LC_CTYPE} category, the function returns zero.
311
312 @noindent
313 The properties known in every locale are:
314
315 @multitable @columnfractions .25 .25 .25 .25
316 @item
317 @code{"alnum"} @tab @code{"alpha"} @tab @code{"cntrl"} @tab @code{"digit"}
318 @item
319 @code{"graph"} @tab @code{"lower"} @tab @code{"print"} @tab @code{"punct"}
320 @item
321 @code{"space"} @tab @code{"upper"} @tab @code{"xdigit"}
322 @end multitable
323
324 @pindex wctype.h
325 This function is declared in @file{wctype.h}.
326 @end deftypefun
327
328 To test the membership of a character to one of the non-standard classes
329 the @w{ISO C} standard defines a completely new function.
330
331 @comment wctype.h
332 @comment ISO
333 @deftypefun int iswctype (wint_t @var{wc}, wctype_t @var{desc})
334 This function returns a nonzero value if @var{wc} is in the character
335 class specified by @var{desc}.  @var{desc} must previously be returned
336 by a successful call to @code{wctype}.
337
338 @pindex wctype.h
339 This function is declared in @file{wctype.h}.
340 @end deftypefun
341
342 To make it easier to use the commonly-used classification functions,
343 they are defined in the C library.  There is no need to use
344 @code{wctype} if the property string is one of the known character
345 classes.  In some situations it is desirable to construct the property
346 strings, and then it is important that @code{wctype} can also handle the
347 standard classes.
348
349 @cindex alphanumeric character
350 @comment wctype.h
351 @comment ISO
352 @deftypefun int iswalnum (wint_t @var{wc})
353 This function returns a nonzero value if @var{wc} is an alphanumeric
354 character (a letter or number); in other words, if either @code{iswalpha}
355 or @code{iswdigit} is true of a character, then @code{iswalnum} is also
356 true.
357
358 @noindent
359 This function can be implemented using
360
361 @smallexample
362 iswctype (wc, wctype ("alnum"))
363 @end smallexample
364
365 @pindex wctype.h
366 It is declared in @file{wctype.h}.
367 @end deftypefun
368
369 @cindex alphabetic character
370 @comment wctype.h
371 @comment ISO
372 @deftypefun int iswalpha (wint_t @var{wc})
373 Returns true if @var{wc} is an alphabetic character (a letter).  If
374 @code{iswlower} or @code{iswupper} is true of a character, then
375 @code{iswalpha} is also true.
376
377 In some locales, there may be additional characters for which
378 @code{iswalpha} is true---letters which are neither upper case nor lower
379 case.  But in the standard @code{"C"} locale, there are no such
380 additional characters.
381
382 @noindent
383 This function can be implemented using
384
385 @smallexample
386 iswctype (wc, wctype ("alpha"))
387 @end smallexample
388
389 @pindex wctype.h
390 It is declared in @file{wctype.h}.
391 @end deftypefun
392
393 @cindex control character
394 @comment wctype.h
395 @comment ISO
396 @deftypefun int iswcntrl (wint_t @var{wc})
397 Returns true if @var{wc} is a control character (that is, a character that
398 is not a printing character).
399
400 @noindent
401 This function can be implemented using
402
403 @smallexample
404 iswctype (wc, wctype ("cntrl"))
405 @end smallexample
406
407 @pindex wctype.h
408 It is declared in @file{wctype.h}.
409 @end deftypefun
410
411 @cindex digit character
412 @comment wctype.h
413 @comment ISO
414 @deftypefun int iswdigit (wint_t @var{wc})
415 Returns true if @var{wc} is a digit (e.g., @samp{0} through @samp{9}).
416 Please note that this function does not only return a nonzero value for
417 @emph{decimal} digits, but for all kinds of digits.  A consequence is
418 that code like the following will @strong{not} work unconditionally for
419 wide characters:
420
421 @smallexample
422 n = 0;
423 while (iswdigit (*wc))
424   @{
425     n *= 10;
426     n += *wc++ - L'0';
427   @}
428 @end smallexample
429
430 @noindent
431 This function can be implemented using
432
433 @smallexample
434 iswctype (wc, wctype ("digit"))
435 @end smallexample
436
437 @pindex wctype.h
438 It is declared in @file{wctype.h}.
439 @end deftypefun
440
441 @cindex graphic character
442 @comment wctype.h
443 @comment ISO
444 @deftypefun int iswgraph (wint_t @var{wc})
445 Returns true if @var{wc} is a graphic character; that is, a character
446 that has a glyph associated with it.  The whitespace characters are not
447 considered graphic.
448
449 @noindent
450 This function can be implemented using
451
452 @smallexample
453 iswctype (wc, wctype ("graph"))
454 @end smallexample
455
456 @pindex wctype.h
457 It is declared in @file{wctype.h}.
458 @end deftypefun
459
460 @cindex lower-case character
461 @comment ctype.h
462 @comment ISO
463 @deftypefun int iswlower (wint_t @var{wc})
464 Returns true if @var{wc} is a lower-case letter.  The letter need not be
465 from the Latin alphabet, any alphabet representable is valid.
466
467 @noindent
468 This function can be implemented using
469
470 @smallexample
471 iswctype (wc, wctype ("lower"))
472 @end smallexample
473
474 @pindex wctype.h
475 It is declared in @file{wctype.h}.
476 @end deftypefun
477
478 @cindex printing character
479 @comment wctype.h
480 @comment ISO
481 @deftypefun int iswprint (wint_t @var{wc})
482 Returns true if @var{wc} is a printing character.  Printing characters
483 include all the graphic characters, plus the space (@samp{ }) character.
484
485 @noindent
486 This function can be implemented using
487
488 @smallexample
489 iswctype (wc, wctype ("print"))
490 @end smallexample
491
492 @pindex wctype.h
493 It is declared in @file{wctype.h}.
494 @end deftypefun
495
496 @cindex punctuation character
497 @comment wctype.h
498 @comment ISO
499 @deftypefun int iswpunct (wint_t @var{wc})
500 Returns true if @var{wc} is a punctuation character.
501 This means any printing character that is not alphanumeric or a space
502 character.
503
504 @noindent
505 This function can be implemented using
506
507 @smallexample
508 iswctype (wc, wctype ("punct"))
509 @end smallexample
510
511 @pindex wctype.h
512 It is declared in @file{wctype.h}.
513 @end deftypefun
514
515 @cindex whitespace character
516 @comment wctype.h
517 @comment ISO
518 @deftypefun int iswspace (wint_t @var{wc})
519 Returns true if @var{wc} is a @dfn{whitespace} character.  In the standard
520 @code{"C"} locale, @code{iswspace} returns true for only the standard
521 whitespace characters:
522
523 @table @code
524 @item L' '
525 space
526
527 @item L'\f'
528 formfeed
529
530 @item L'\n'
531 newline
532
533 @item L'\r'
534 carriage return
535
536 @item L'\t'
537 horizontal tab
538
539 @item L'\v'
540 vertical tab
541 @end table
542
543 @noindent
544 This function can be implemented using
545
546 @smallexample
547 iswctype (wc, wctype ("space"))
548 @end smallexample
549
550 @pindex wctype.h
551 It is declared in @file{wctype.h}.
552 @end deftypefun
553
554 @cindex upper-case character
555 @comment wctype.h
556 @comment ISO
557 @deftypefun int iswupper (wint_t @var{wc})
558 Returns true if @var{wc} is an upper-case letter.  The letter need not be
559 from the Latin alphabet, any alphabet representable is valid.
560
561 @noindent
562 This function can be implemented using
563
564 @smallexample
565 iswctype (wc, wctype ("upper"))
566 @end smallexample
567
568 @pindex wctype.h
569 It is declared in @file{wctype.h}.
570 @end deftypefun
571
572 @cindex hexadecimal digit character
573 @comment wctype.h
574 @comment ISO
575 @deftypefun int iswxdigit (wint_t @var{wc})
576 Returns true if @var{wc} is a hexadecimal digit.
577 Hexadecimal digits include the normal decimal digits @samp{0} through
578 @samp{9} and the letters @samp{A} through @samp{F} and
579 @samp{a} through @samp{f}.
580
581 @noindent
582 This function can be implemented using
583
584 @smallexample
585 iswctype (wc, wctype ("xdigit"))
586 @end smallexample
587
588 @pindex wctype.h
589 It is declared in @file{wctype.h}.
590 @end deftypefun
591
592 The GNU C library also provides a function which is not defined in the
593 @w{ISO C} standard but which is available as a version for single byte
594 characters as well.
595
596 @cindex blank character
597 @comment wctype.h
598 @comment GNU
599 @deftypefun int iswblank (wint_t @var{wc})
600 Returns true if @var{wc} is a blank character; that is, a space or a tab.
601 This function is a GNU extension.  It is declared in @file{wchar.h}.
602 @end deftypefun
603
604 @node Using Wide Char Classes, Wide Character Case Conversion, Classification of Wide Characters, Character Handling
605 @section Notes on using the wide character classes
606
607 The first note is probably not astonishing but still occasionally a
608 cause of problems.  The @code{isw@var{XXX}} functions can be implemented
609 using macros and in fact, the GNU C library does this.  They are still
610 available as real functions but when the @file{wctype.h} header is
611 included the macros will be used.  This is the same as the
612 @code{char} type versions of these functions.
613
614 The second note covers something new.  It can be best illustrated by a
615 (real-world) example.  The first piece of code is an excerpt from the
616 original code.  It is truncated a bit but the intention should be clear.
617
618 @smallexample
619 int
620 is_in_class (int c, const char *class)
621 @{
622   if (strcmp (class, "alnum") == 0)
623     return isalnum (c);
624   if (strcmp (class, "alpha") == 0)
625     return isalpha (c);
626   if (strcmp (class, "cntrl") == 0)
627     return iscntrl (c);
628   ...
629   return 0;
630 @}
631 @end smallexample
632
633 Now, with the @code{wctype} and @code{iswctype} you can avoid the
634 @code{if} cascades, but rewriting the code as follows is wrong:
635
636 @smallexample
637 int
638 is_in_class (int c, const char *class)
639 @{
640   wctype_t desc = wctype (class);
641   return desc ? iswctype ((wint_t) c, desc) : 0;
642 @}
643 @end smallexample
644
645 The problem is that it is not guaranteed that the wide character
646 representation of a single-byte character can be found using casting.
647 In fact, usually this fails miserably.  The correct solution to this
648 problem is to write the code as follows:
649
650 @smallexample
651 int
652 is_in_class (int c, const char *class)
653 @{
654   wctype_t desc = wctype (class);
655   return desc ? iswctype (btowc (c), desc) : 0;
656 @}
657 @end smallexample
658
659 @xref{Converting a Character}, for more information on @code{btowc}.
660 Note that this change probably does not improve the performance
661 of the program a lot since the @code{wctype} function still has to make
662 the string comparisons.  It gets really interesting if the
663 @code{is_in_class} function is called more than once for the
664 same class name.  In this case the variable @var{desc} could be computed
665 once and reused for all the calls.  Therefore the above form of the
666 function is probably not the final one.
667
668
669 @node Wide Character Case Conversion, , Using Wide Char Classes, Character Handling
670 @section Mapping of wide characters.
671
672 The classification functions are also generalized by the @w{ISO C}
673 standard.  Instead of just allowing the two standard mappings, a
674 locale can contain others.  Again, the @code{localedef} program
675 already supports generating such locale data files.
676
677 @comment wctype.h
678 @comment ISO
679 @deftp {Data Type} wctrans_t
680 This data type is defined as a scalar type which can hold a value
681 representing the locale-dependent character mapping.  There is no way to
682 construct such a value apart from using the return value of the
683 @code{wctrans} function.
684
685 @pindex wctype.h
686 @noindent
687 This type is defined in @file{wctype.h}.
688 @end deftp
689
690 @comment wctype.h
691 @comment ISO
692 @deftypefun wctrans_t wctrans (const char *@var{property})
693 The @code{wctrans} function has to be used to find out whether a named
694 mapping is defined in the current locale selected for the
695 @code{LC_CTYPE} category.  If the returned value is non-zero, you can use
696 it afterwards in calls to @code{towctrans}.  If the return value is
697 zero no such mapping is known in the current locale.
698
699 Beside locale-specific mappings there are two mappings which are
700 guaranteed to be available in every locale:
701
702 @multitable @columnfractions .5 .5
703 @item
704 @code{"tolower"} @tab @code{"toupper"}
705 @end multitable
706
707 @pindex wctype.h
708 @noindent
709 These functions are declared in @file{wctype.h}.
710 @end deftypefun
711
712 @comment wctype.h
713 @comment ISO
714 @deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc})
715 @code{towctrans} maps the input character @var{wc}
716 according to the rules of the mapping for which @var{desc} is a
717 descriptor, and returns the value it finds.  @var{desc} must be
718 obtained by a successful call to @code{wctrans}.
719
720 @pindex wctype.h
721 @noindent
722 This function is declared in @file{wctype.h}.
723 @end deftypefun
724
725 For the generally available mappings, the @w{ISO C} standard defines
726 convenient shortcuts so that it is not necessary to call @code{wctrans}
727 for them.
728
729 @comment wctype.h
730 @comment ISO
731 @deftypefun wint_t towlower (wint_t @var{wc})
732 If @var{wc} is an upper-case letter, @code{towlower} returns the corresponding
733 lower-case letter.  If @var{wc} is not an upper-case letter,
734 @var{wc} is returned unchanged.
735
736 @noindent
737 @code{towlower} can be implemented using
738
739 @smallexample
740 towctrans (wc, wctrans ("tolower"))
741 @end smallexample
742
743 @pindex wctype.h
744 @noindent
745 This function is declared in @file{wctype.h}.
746 @end deftypefun
747
748 @comment wctype.h
749 @comment ISO
750 @deftypefun wint_t towupper (wint_t @var{wc})
751 If @var{wc} is a lower-case letter, @code{towupper} returns the corresponding
752 upper-case letter.  Otherwise @var{wc} is returned unchanged.
753
754 @noindent
755 @code{towupper} can be implemented using
756
757 @smallexample
758 towctrans (wc, wctrans ("toupper"))
759 @end smallexample
760
761 @pindex wctype.h
762 @noindent
763 This function is declared in @file{wctype.h}.
764 @end deftypefun
765
766 The same warnings given in the last section for the use of the wide
767 character classification functions apply here.  It is not possible to
768 simply cast a @code{char} type value to a @code{wint_t} and use it as an
769 argument to @code{towctrans} calls.