btowc() — Convert Single Byte to Wide Character

Format

#include <stdio.h>
#include <wchar.h>
wint_t btowc(int c);

Language Level

ANSI

Threadsafe

Yes

Locale Sensitive

The behavior of this function might be affected by the LC_CTYPE category of the current locale. The behavior might also be affected by the LC_UNI_CTYPE category of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.

Wide Character Function

See Wide Characters for more information.

Description

The btowc() function converts the single byte value c to the wide-character representation of c. If c does not constitute a valid (1-byte) multibyte character in the initial shift state, the btowc() function returns WEOF.

Return Value

The btowc() function returns WEOF if c has the value EOF, or if (unsigned char) c does not constitute a valid (1-byte) multibyte character in the initial shift state. Otherwise, it returns the wide-character representation of that character.

Example

This example scans various types of data.

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <local.h>
 
#define UPPER_LIMIT   0xFF
 
int main(void)
{
   int wc;
   int ch;
   if (NULL == setlocale(LC_ALL, "/QSYS.LIB/EN_US.LOCALE")) {
      printf("Locale could not be loaded\n");
      exit(1);
   }
   for (ch = 0; ch <= UPPER_LIMIT; ++ch) {
      wc = btowc(ch);
      if (wc==WEOF) {
         printf("%#04x is not a one-byte multibyte character\n", ch);
      } else {
         printf("%#04x has wide character representation: %#06x\n", ch, wc);
      }
   }
  wc = btowc(EOF);
   if (wc==WEOF) {
      printf("The character is EOF.\n", ch);
   } else {
      printf("EOF has wide character representation: %#06x\n", wc);
   }
   return 0;
 }
  /***********************************************************************
      If the locale is bound to SBCS, the output should be similar to:
      0000 has wide character representation: 000000
      0x01 has wide character representation: 0x0001
      ...
      0xfe has wide character representation: 0x00fe
      0xff has wide character representation: 0x00ff
      The character is EOF.
 
  ************************************************************************/