putwc, putwchar, or fputwc Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

putwc, putwchar, or fputwc Subroutine

Purpose

Writes a character or a word to a stream.

Library

Standard I/O Library (libc.a)

Syntax

#include <stdio.h>

wint_t putwc(Character, Stream)
wint_t Character;
FILE *Stream;

wint_t putwchar(Character)
wint_t Character;

wint_t fputwc(Character, Stream)
wint_t Character;
FILE Stream;

Description

The putwc subroutine writes the wide character specified by the Character parameter to the output stream pointed to by the Stream parameter. The wide character is written as a multibyte character at the associated file position indicator for the stream, if defined. The subroutine then advances the indicator. If the file cannot support positioning requests, or if the stream was opened with append mode, the character is appended to the output stream.

The putwchar subroutine works like the putwc subroutine, except that putwchar writes the specified wide character to the standard output.

The fputwc subroutine works the same as the putwc subroutine.

Output streams, with the exception of stderr, are buffered by default 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 subroutine causes it to become buffered or line-buffered. Use the setbuf subroutine to change the stream's buffering strategy.

After the fputwc, putwc, fputc. putc, fputs, puts, or putw subroutine runs successfully, and before the next successful completion of a call either to the fflush or fclose subroutine on the same stream or to the exit or abort subroutine, the st_ctime and st_mtime fields of the file are marked for update.

Parameters

Character	Specifies a wide character of type wint_t.
Stream	Specifies a stream of output data.

Return Values

Upon successful completion, the putwc, putwchar, and fputwc subroutines return the wide character that is written. Otherwise WEOF is returned, the error indicator for the stream is set, and the errno global variable is set to indicate the error.

Error Codes

If the putwc, putwchar, or fputwc subroutine fails because the stream is not buffered or data in the buffer needs to be written, it returns one or more of the following error codes:

EAGAIN	Indicates that the O_NONBLOCK flag is set for the file descriptor underlying the Stream parameter, delaying the process during the write operation.
EBADF	Indicates that the file descriptor underlying the Stream parameter is not valid and cannot be updated during the write operation.
EFBIG	Indicates that the process attempted to write to a file that already equals or exceeds the file-size limit for the process. The file is a regular file and an attempt was made to write at or beyond the offset maximum associated with the corresponding stream.
EILSEQ	Indicates that the wide-character code does not correspond to a valid character.
EINTR	Indicates that the process has received a signal that terminates the read operation.
EIO	Indicates that the process is in a background process group attempting to perform a write operation to its controlling terminal. The TOSTOP flag is set, the process is not ignoring or blocking the SIGTTOU flag, and the process group of the process is orphaned.
ENOMEM	Insufficient storage space is available.
ENOSPC	Indicates that no free space remains on the device containing the file.
ENXIO	Indicates a request was made of a non-existent device, or the request was outside the capabilities of the device.
EPIPE	Indicates that the process has attempted to write to a pipe or first-in-first-out (FIFO) that is not open for reading. The process will also receive a SIGPIPE signal.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

Other wide character I/O subroutines: fgetwc subroutine, fgetws subroutine, fputws subroutine, getwc subroutine, getwchar subroutine, getws subroutine, putws subroutine, ungetwc subroutine.

Related standard I/O subroutines: fdopen subroutine, fgets subroutine, fopen subroutine, fprintf subroutine, fputc subroutine, fputs subroutine, fread subroutine, freopen subroutine, fwrite subroutine, gets subroutine, printf subroutine, putc subroutine, putchar subroutine, puts subroutine, putw subroutine, sprintf subroutine.

National Language Support Overview for Programming, Subroutines Overview, Understanding Wide Character Input/Output Subroutines in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.