ILE C/C++ Run-Time Library Functions


fputwc() -- Write Wide Character

Format

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

Language Level: ANSI

Threadsafe: Yes.

Description

The fputwc() function writes the wide character wc to the output stream pointed to by stream at the current position. It also advances the file position indicator appropriately. If the file cannot support positioning requests, or if the stream was opened with append mode, the character is appended to the stream.

Using non-wide-character functions with the fputwc() function on the same stream will result in undefined behavior. After calling the fputwc() function, delete the buffer or reposition the stream pointer before calling a read function for the stream. After reading from the stream, delete the buffer or reposition the stream pointer before calling the fputwc() function, unless EOF has been reached.

Notes:

  1. The behavior of the fputwc() function is affected by the LC_CTYPE category of the current locale. If you change the category between subsequent operations on the same stream, undefined results can occur.

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

Return Value

The fputwc() function returns the wide character that is written. If a write error occurs, the error indicator for the stream is set, and the fputwc() function returns WEOF. If an encoding error occurs during conversion from wide character to a multibyte character, fputwc() sets errno to EILSEQ and returns WEOF.

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

Example that uses fputwc()

This example opens a file and uses the fputwc() function to write wide characters to the file.


#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("fputwc.out", "w"))) 
   {
      printf("Unable to open: \"fputwc.out\".\n");
      exit(1);
   }
 
   for (i = 0; wcs[i] != L'\0'; i++) {
      errno = 0;
      if (WEOF == fputwc(wcs[i], stream)) {
         printf("Unable to fputwc() the wide character.\n"
                "wcs[%d] = 0x%.4lx\n", i, wcs[i]);
         if (EILSEQ == errno)
            printf("An invalid wide character was encountered.\n");
         exit(1);
      }
   }
   fclose(stream);
   return 0;
 
   /***************************************************************
      The output file fputwc.out should contain:
 
      A character string.
   ***************************************************************/
}

Related Information


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