ILE C/C++ Run-Time Library Functions


putwc() -- Write Wide Character

Format

     #include <stdio.h>
     #include <wchar.h>
     wint_t putwc(wint_t wc, FILE *stream);

Language Level: ANSI

Threadsafe: Yes.

Description

The putwc() function writes the wide character wc to the stream at the current position. It also advances the file position indicator for the stream appropriately. The putwc() function is equivalent to the fputwc() function except that some platforms implement putwc() as a macro. Therefore, for portability, the stream argument to putwc() should not be an expression with side effects.

The behavior of the putwc() function is affected by the LC_CTYPE category of the current locale. Using a non-wide-character function with the putwc() function on the same stream results in undefined behavior. After calling the putwc() function, flush the buffer or reposition the stream pointer before calling a write function for the stream, unless EOF has been reached. After a write operation on the stream, flush the buffer or reposition the stream pointer before calling the putwc() function.

Note:
This function is not available when either LOCALETYPE(*CLD) or SYSIFCOPT(*NOIFSIO) is specified on the compilation command.

Return Value

The putwc() function returns the wide character written. If a write error occurs, it sets the error indicator for the stream and returns WEOF. If an encoding error occurs when a wide character is converted to a multibyte character, the putwc() function sets errno to EILSEQ and returns WEOF.

For information about errno values for putwc(), see "fputc() -- Write Character".

Example that uses putwc()

The following example uses the putwc() function to convert the wide characters in wcs to multibyte characters and write them to the file putwc.out.


#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <errno.h>
 
int main(void)
{
   FILE    *stream;
   wchar_t *wcs = L"A character string.";
   int     i;
 
   if (NULL == (stream = fopen("putwc.out", "w"))) {
      printf("Unable to open: \"putwc.out\".\n");
      exit(1);
   }
 
   for (i = 0; wcs[i] != L'\0'; i++) {
      errno = 0;
      if (WEOF == putwc(wcs[i], stream)) {
         printf("Unable to putwc() the wide character.\n"
                "wcs[%d] = 0x%lx\n", i, wcs[i]);
         if (EILSEQ == errno)
            printf("An invalid wide character was encountered.\n");
         exit(1);
      }
   }
   fclose(stream);
   return 0;
 
   /***************************************************************
      The output file putwc.out should contain :
 
      A character string.
   ***************************************************************/
}

Related Information


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]