PUTC(3s,L) AIX Technical Reference PUTC(3s,L)
-------------------------------------------------------------------------------
putc, putchar, fputc, putw, putwc, putwchar, fputwc
PURPOSE
Writes a character or a word to a stream.
LIBRARY
Standard C Library (libc.a)
SYNTAX
#include <stdio.h>
int putc(c, stream) int fputc(c, stream)
char c; char c;
FILE *stream; FILE *stream;
int putchar(c) int putw(w, stream)
char c; int w;
FILE *stream;
wchar_t putwc (c, stream)
wchar_t c; wchar_t fputwc (c, stream)
FILE *stream; wchar_t c;
FILE *stream;
wchar_t putwchar (c)
wchar_t c;
DESCRIPTION
The putc macro writes the character c to the output specified by the stream
parameter. The character is written at the position at which the file pointer
is currently pointing, if defined.
The putchar macro is the same as the putc macro except that putchar writes to
the standard output.
The fputc subroutine works the same as putc, but fputc is a true subroutine
rather than a macro. It runs more slowly than putc, but takes less space per
invocation.
Because putc is implemented as a macro, it treats incorrectly a stream
parameter with side effects, such as "putc(c, *f++)". For such cases, use
Processed November 7, 1990 PUTC(3s,L) 1
PUTC(3s,L) AIX Technical Reference PUTC(3s,L)
fputc instead. Also, use fputc whenever you need to pass a pointer to this
subroutine as a parameter to another subroutine.
The putw subroutine writes the word (int) specified by the w parameter to the
output specified by the stream parameter. The word is written at the position
at which the file pointer, if defined, is pointing. The size of a word is the
size of an integer and varies from machine to machine. The putw subroutine
does not assume or cause special alignment of the data in the file.
Because of possible differences in word length and byte ordering, files written
using the putw subroutine are machine-dependent, and may not be readable using
the getw subroutine on a different processor.
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
subroutine causes it to become buffered or line-buffered. Use the setbuf
subroutine to change the stream's buffering strategy.
When an output stream is unbuffered, information is queued for writing on the
destination file or terminal as soon as it is written. When an output stream
is buffered, many characters are saved and written as a block. When an output
stream is line-buffered, each line of output is queued for writing on the
destination terminal as soon as the line is completed (that is, as soon as a
new-line character is written or terminal input is requested).
The putwchar subroutine returns the character written. If a write error
occurs, the error indicator for the stream is set and putwchar returns WEOF.
The fputwc subroutine writes the character specified by c to the output stream
pointed to by stream, as a multibyte character at the position indicated by the
associated file position indicator for the stream (if defined), and it 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.
RETURN VALUE
Upon successful completion, each of these functions (with the exception of
putw) returns the value it has written. putw returns ferror (stream). If
these functions fail, they return the constant EOF. They fail if the stream is
not open for writing, or if the output file size cannot be increased. Because
EOF is a valid integer, you should use the ferror subroutine to detect putw
errors.
The putwc subroutine returns the argument path to it. If a write error occurs,
the error indicator for the stream is set and putwc returns WEOF.
The putwchar subroutine is equivalent to putwc with the second argument stdout.
The fputwc subroutine returns the wide character written. If a write error
occurs, the error indicator for the stream is set and fputwc returns WEOF.
Processed November 7, 1990 PUTC(3s,L) 2
PUTC(3s,L) AIX Technical Reference PUTC(3s,L)
ERROR CONDITIONS
The putc, putchar, fputc, and putw subroutines fail if one or more of the
following are true:
EAGAIN The O_NONBLOCK flag is set for the file descriptor underlying stream
and the process is delayed in the write operation.
EBADF The file descriptor underlying stream is not a valid file descriptor
open for writing.
Note: If a wide character routine fails and errno is not set, this
indicates that the translation from wide code to file code has
failed.
EFBIG An attempt was made to write to a file that exceeds the process's
file size limit or the maximum file size.
EINTR The write operation was terminated due to the receipt of a signal,
and either no data was transferred or the implementation does not
report partial transfers for this file.
EIO The implementation supports job control, 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. This error
may also be returned under implementation-defined conditions.
ENOSPC There was no free space remaining on the device containing the file.
ENXIO A request was made of a non-existent device, or the request was
outside the capabilities of the device.
RELATED INFORMATION
In this book: "fclose, fflush," "feof, ferror, clearerr, fileno," "fopen,
freopen, fdopen," "fread, fwrite," "getc, fgetc, getchar, getw, getwc, fgetwc,
getwchar," "printf, fprintf, sprintf, NLprintf, NLfprintf, NLsprintf,
wsprintf," "puts, fputs, putws, fputws," "setbuf, setvbuf," and "stdio."
AIX Guide to Multibyte Character Set (MBCS) Support.
Processed November 7, 1990 PUTC(3s,L) 3