putwchar() — Output a wide character to standard output

Standards

Standards / Extensions	C or C++	Dependencies
ISO C Amendment XPG4 XPG4.2 C99 Single UNIX Specification, Version 3 Language Environment	both

Format

Non-XPG4:

#include <stdio.h>
#include <wchar.h>

wint_t putwchar(wchar_t wc);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>

wint_t putwchar_unlocked(wchar_t wc);

XPG4:

#define _XOPEN_SOURCE
#include <stdio.h>
#include <wchar.h>

wint_t putwchar(wint_t wc);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>

wint_t putwchar_unlocked(wchar_t wc);

XPG4 and MSE:

#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <stdio.h>
#include <wchar.h>

wint_t putwchar(wchar_t wc);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>

wint_t putwchar_unlocked(wchar_t wc);

General description

The putwchar() function is equivalent to: putwc()(wc stdout).

The behavior of this wide-character function is affected by the LC_CTYPE category of the current locale. If you use a non-wide-oriented function with putwchar(), undefined results can occur.

putwchar() has the same restriction as any write operation for a read immediately following a write or a write immediately following a read. Between a write and a subsequent read, there must be an intervening flush or reposition. Between a read and a subsequent write, there must also be an intervening flush or reposition unless an EOF has been reached.

You may not use putwc() or putwchar() with files opened as type=record or type=blocked.

putwchar_unlocked() is functionally equivalent to putwchar() with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.

Special behavior for XPG4: If you define any feature test macro specifying XPG4 behavior before the statement in your program source file to include the wchar header, then the compiler assumes that your program is using the XPG4 variety of the putwchar() function, unless you also define the _MSE_PROTOS feature test macro. Please see Table 1 for a list of XPG4 and other feature test macros.

The prototype for the XPG4 variety of the putwchar() function is:

wint_t putwchar(wint_t wc);

The difference between this variety and the MSE variety of the putwchar() function is that its parameter has type wint_t rather than type wchar_t.

Returned value

If successful, putwchar() returns the wide character written.

If a write error occurs, the error indicator for the stream is set and WEOF is returned. If an encoding error occurs when converting from a wide character to a multibyte character, the value of the macro EILSEQ is stored in errno and WEOF is returned.

Example

CELEBP57

⁄* CELEBP57 *⁄                                   
#include <stdio.h>                                                              
#include <stdlib.h>                                                             
#include <wchar.h>                                                              
#include <errno.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
   wchar_t *wcs = L"This test string should not cause a WEOF condition";        
   int     i;                                                                   
   int     rc;                                                                  
                                                                                
   for (i=0; wcs[i] != L'\0'; i++) {                                            
      errno = 0;                                                                
      if ((rc = putwchar(wcs[i])) == WEOF) {                                    
         printf("Unable to putwchar() the wide character.\n");                  
         printf("wcs[%d] = 0x%X\n", i, wcs[i]);                                 
         if (errno == EILSEQ)                                                   
            printf("An invalid wide character was encountered.\n");             
         exit(1);                                                               
      }                                                                         
   }                                                                            
}