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

Locale Sensitive

The behavior of this function might be affected by the LC_CTYPE category of the current locale. It 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.

Integrated File System Interface

This function is not available when SYSIFCOPT(*NOIFSIO) is specified on the compilation command.

Wide Character Function

See Wide Characters for more information.

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.

Note: If the current locale is changed between subsequent operations on the same stream, undefined results can occur.

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

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
   ************************************************************/
}