ILE C/C++ Run-Time Library Functions


fputws() -- Write Wide-Character String

Format

#include <wchar.h>
#include <stdio.h>
int fputws(const wchar_t *wcs, FILE *stream);

Language Level: XPG4

Threadsafe: Yes.

Description

The fputws() function writes the wide-character string wcs to a stream. It does not write the ending null wide characters.

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

Notes:

  1. The behavior of the fputws() 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 fputws() function returns a non-negative value if successful. If a write error occurs, the error indicator for the stream is set, and the fputws() function returns -1. If an encoding error occurs in converting the wide characters to multibyte characters, the fputws() function sets errno to EILSEQ and returns -1.

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

Example that uses fputws()

This example opens a file and writes a wide-character string to the file using the fgetws() function.


#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <errno.h>
 
int main(void)
{
   FILE    *stream;
   wchar_t *wcs = L"This test string should not return -1";
 
   if (NULL == (stream = fopen("fputws.out", "w"))) {
      printf("Unable to open: \"fputws.out\".\n");
      exit(1);
   }
 
   errno = 0;
   if (EOF == fputws(wcs, stream)) {
      printf("Unable to complete fputws() function.\n");
      if (EILSEQ == errno)
         printf("An invalid wide character was encountered.\n");
      exit(1);
   }
   fclose(stream);
   return 0;
 
   /************************************************************
      The output file fputws.out should contain:
 
      This test string should not return -1
   ************************************************************/
}

Related Information


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