putc(3S) putc(3S)
NAME
putc, putchar, fputc, putw - output character/word on a stream
SYNOPSIS
#include <stdio.h>
int putc(int c, FILE *stream);
int putchar(int c);
int fputc(int c, FILE *stream);
int putw(int w, FILE *stream);
DESCRIPTION
putc() writes the byte c (converted to an unsigned char) onto the out-
put stream at the position where the file pointer (if defined) is
pointing, and advances the file pointer appropriately. If the file
cannot support positioning requests, or stream was opened with append
mode, the byte is written at the end of the output. putchar(c) is
defined as putc(c, stdout). puts() and putchar() are macros.
fputc() behaves like putc(), but is a function rather than a macro.
fputc() runs more slowly than putc(), but it takes less space per
invocation and its name can be passed as an argument to a function.
putw() writes the word (int) w to the output stream (where the file
pointer, if defined, is pointing). The size of a word is the size of
an int and varies from machine to machine. putw() neither assumes nor
causes special alignment in the file.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
These functions will fail if either the stream is unbuffered or the
stream's buffer needed to be flushed and:
EAGAIN The ONONBLOCK flag is set for the file descriptor and the
process would be delayed in the write operation.
EBADF The file descriptor underlying stream is not a valid
descriptor open for writing.
EFBIG An attempt was made to write to a file that exceeds the max-
imum file size or the process' file size limit.
EFBIG The file is a regular file and an attempt was made to write
at or beyond the offset maximum.
EINTR The write operation was terminated due to the receipt of a
signal, and no data was transferred.
Page 1 Reliant UNIX 5.44 Printed 11/98
putc(3S) putc(3S)
EIO A physical input/output error has occurred, the process is a
member of a background process group attempting to write to
its controlling terminal, TOSTOP is set, the process is nei-
ther ignoring nor blocking SIGTTOU and the process group of
the process is orphaned. This error may also be returned
under implementation-dependent conditions.
ENOSPC There was no free space remaining on the device.
EPIPE An attempt was made to write a pipe or FIFO that is not open
for reading by any process. A SIGPIPE signal will be sent to
the process.
The fputc() function 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.
RESULT
On success, these functions (with the exception of putw()) each return
the value they have written. putw() returns ferror(stream). On
failure, they return the constant EOF. This result will occur, for
example, if the file stream is not open for writing or if the output
file cannot grow.
NOTES
Because it is implemented as a macro, putc() can evaluate stream more
than once. If stream is an expression with side-effects, it is not
treated correctly by putc(). In particular, putc(c, *f++) does not
behave as expected. The fputc() function should be used instead.
Because of possible differences in word length and byte ordering,
files written using putw() are machine-dependent, and may not be read
using getw() on a different processor.
Functions exist for all the above defined macros. To get the function
form, the macro name must be undefined (e.g., #undef putc()).
SEE ALSO
exit(2), lseek(2), write(2), abort(3C), fclose(3S), ferror(3S),
fopen(3S), fread(3S), printf(3S), puts(3S), setbuf(3S), stdio(3S),
lfs(5), stdio(5).
Page 2 Reliant UNIX 5.44 Printed 11/98