putwc(3)putwc(3)NAME
putwc, putwchar, fputwc - Write a wide character to a stream
SYNOPSIS
#include <stdio.h> #include <wchar.h>
wint_t putwc(
wint_t wc,
FILE *stream ); wint_t fputwc(
wint_t wc,
FILE *stream ); #include <wchar.h>
wint_t putwchar(
wchar_t wc );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
fputwc(), putwc(), putwchar(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the wide character to be converted and written. Points to
the output data.
DESCRIPTION
The fputwc() function converts the wchar_t specified by the wc parame‐
ter to its equivalent multibyte character and then writes the multibyte
character to the file or terminal associated with the stream parameter.
The function also advances the file position indicator for stream if
the associated file supports positioning requests. If the file does not
support positioning requests or was opened in append mode, the function
appends the character to the end of stream. The st_ctime and st_mtime
fields of the FILE structure are marked for update between a successful
execution of fputwc() and completion of one of the following: A suc‐
cessfully executed call to fflush() or fclose() on the same stream A
call to exit() or abort()
If an error occurs while the character is being written, the shift
state of the output file is undefined. See the RESTRICTIONS section for
information about support for shift-state encoding.
The putwc() function performs the same operation as fputwc(), but can
be implemented as a macro on some implementations that conform to
X/Open standards. If implemented as a macro, this function may evaluate
stream more than once; therefore, stream should never be implemented as
an expression with side effects (for example, as in putwc(wc,*f++)).
The putwchar() macro works like the putwc() function, except that
putwchar() writes the character to the standard output stream (stdout).
The call putwchar(wc) is equivalent to putwc(wc, stdout).
[Tru64 UNIX] With the exception of stderr, output streams are, by
default, buffered if they refer to files, or line buffered if they
refer to terminals. The standard error output stream, stderr, is
unbuffered by default, but using the freopen() function causes it to
become buffered or line buffered. Use the setbuf() function to change
the stream's buffering strategy.
RESTRICTIONS
Currently, the operating system does not include locales whose codesets
use shift-state encoding. Some sections of this reference page refer to
function behavior with respect to shift sequences. This information is
included only for your convenience in developing portable applications
that run on multiple platforms, some of which may supply locales whose
codesets do use shift-state encoding.
RETURN VALUES
On successful completion, these functions return the value written. If
these functions fail, they return the constant WEOF, set the error
indicator for the stream, and set errno to indicate the error.
ERRORS
If any of the following conditions occur, the putwc(), fputwc(), and
putwchar() functions set errno to the corresponding value: The O_NON‐
BLOCK option is set for the file descriptor underlying stream and the
process would be delayed in the write operation. The file descriptor
underlying stream is not a valid file descriptor open for writing. An
attempt was made to write to a file that exceeds the process's file
size limit or the maximum file size.
The file is a regular file and an attempt was made to write at
or beyond the offset maximum associated with the corresponding
stream. The write operation was interrupted by a signal that
was caught, and no data was transferred. The wide-character
code specified by the wc parameter does not correspond to a
valid character in the current locale. One of the following
errors occurred: 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. A physical I/O
error occurred. This condition is defined in Issue 4 Version 2
and later revisions of the XSH specification. There was no free
space remaining on the device containing the file. An attempt
was 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.
SEE ALSO
Functions: getc(3), getwc(3), printf(3), putc(3), puts(3), wctomb(3),
wprintf(3)
Others: i18n_intro(5), l10n_intro(5), standards(5)putwc(3)