putwc(3C)

NAME

     fputwc, putwc, putwchar  -  put  wide-character  code  on  a
     stream

SYNOPSIS

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

     wint_t fputwc(wchar_t wc, FILE*stream);

     wint_t putwc(wchar_t wc, FILE*stream);

     #include <wchar.h>

     wint_t putwchar(wchar_t wc);

DESCRIPTION

     The fputwc() function writes the character corresponding  to
     the  wide-character  code wc to the output stream pointed to
     by stream, at  the  position  indicated  by  the  associated
     file-position  indicator  for  the  stream (if defined), and
     advances the indicator appropriately.  If  the  file  cannot
     support  positioning  requests,  or if the stream was opened
     with append mode, the character is appended  to  the  output
     stream.  If an error occurs while writing the character, the
     shift state of the output  file  is  left  in  an  undefined
     state.

     The st_ctime and st_mtime fields of the file will be  marked
     for  update between the successful execution of fputwc() and
     the next successful completion of a call  to  fflush(3C)  or
     fclose(3C)  on  the  same  stream  or  a  call to exit(2) or
     abort(3C).

     The putwc() function is equivalent to fputwc(), except  that
     it is implemented as a macro.

     The call putwchar(wc) is equivalent  to  putwc(wc,  stdout).
     The putwchar() routine is implemented as a macro.

RETURN VALUES

     Upon   successful   completion,   fputwc(),   putwc(),   and
     putwchar() return wc. Otherwise, they return WEOF, the error
     indicator for the stream is set, and errno is set  to  indi-
     cate the error.

ERRORS

     The fputwc(), putwc(), and putwchar() functions will fail if
     either  the  stream  is  unbuffered  or data in the stream's
     buffer needs to be written, and:

     EAGAIN
           The O_NONBLOCK flag is set  for  the  file  descriptor
           underlying  stream and the process would be delayed in
           the write operation.

     EBADF The file descriptor underlying stream is not  a  valid
           file descriptor open for writing.

     EFBIG An attempt was made to write to a  file  that  exceeds
           the  maximum  file  size  or  the  process's file size
           limit; or the file is a regular file  and  an  attempt
           was  made  to  write  at  or beyond the offset maximum
           associated with the corresponding stream.

     EINTR The write operation was terminated due to the  receipt
           of a signal, and no data was transferred.

     EIO   A physical I/O error has occurred, or the process is a
           member  of  a  background  process group attempting to
           write to its controlling terminal, TOSTOP is set,  the
           process  is neither ignoring nor blocking SIGTTOU, and
           the process group of the process is orphaned.

     ENOSPC
           There was no free space remaining on the  device  con-
           taining the file.

     EPIPE An attempt is made to write to a pipe or FIFO that  is
           not  open for reading by any process. A SIGPIPE signal
           will also be sent to the process.

     The fputwc(), putwc(), and putwchar() functions may fail if:

     ENOMEM
           Insufficient storage space is available.

     ENXIO A request was made of a non-existent  device,  or  the
           request was outside the capabilities of the device.

     EILSEQ
           The wide-character code wc does not  correspond  to  a
           valid character.

USAGE

     Functions exist for the putwc() and  putwchar()  macros.  To
     get the function form, the macro name must be undefined (for
     example, #undef putc).

     When the macro form is used, putwc()  evaluates  the  stream
     argument more than once. In particular, putwc(wc, *f++) does
     not work sensibly.  The fputwc()  function  should  be  used
     instead   when  evaluating  the  stream  argument  has  side
     effects.
     When a UFS file system is mounted with logging enabled, file
     system  transactions  that  free blocks from files might not
     actually add those freed blocks to the  file  system's  free
     list  until  some  unspecified  time  in  the  future.  This
     behavior improves file system performance but does not  con-
     form  to the POSIX, Single UNIX Specification, SPARC Confor-
     mance Definition, System  V  Application  Binary  Interface,
     System  V Interface Definition, and X/Open Portability Guide
     Standards, which  require  that  freed  space  be  available
     immediately.  To enable standards conformance regarding file
     deletions or to address the problem of  not  being  able  to
     grow  files  on a relatively full UFS file system even after
     files  have  been  deleted,   disable   UFS   logging   (see
     mount_ufs(1M).

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     mount_ufs(1M), exit(2),  ulimit(2),  abort(3C),  fclose(3C),
     ferror(3C), fflush(3C), fopen(3C), setbuf(3C), attributes(5)