PUTC(3S)PUTC(3S)NAME
putc, putchar, fputc, putw, putc_unlocked, putchar_unlocked - put
character or 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);
int putc_unlocked (int c, FILE *stream);
int putchar_unlocked (int c);
DESCRIPTION
Fputc and putc write the character c onto the output stream indicated
by stream at the position indicated by the associated file pointer (if
defined), advancing this pointer to the next character position. For
files which cannot be positioned, or which have been opened in append
mode (see fopen(3s)), the character is appended to the output stream.
putchar(c) is defined as putc(c, stdout). Each of these functions is
available in the C library. In addition, putc and putchar are macros
defined in <stdio.h>. (see below under CAVEATS for important details on
the implementation of these macros.)
The function versions of putc and putchar, as well as fputc runs more
slowly than the corresponding macros, but they take less space per
invocation and the function name can be passed as an argument to another
function.
putw writes the word (i.e. integer) w to the output stream (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.
putw neither assumes nor causes special alignment in the file.
The putc_unlocked and putchar_unlocked functions are equivalent to the
putc and putchar functions, respectively. However, these functions are
not thread-safe and thus must only be called under the protection of the
flockfile (or ftrylockfile) and funlockfile functions.
SEE ALSOfclose(3S), ferror(3S), fopen(3S), fread(3S), printf(3S), puts(3S),
setbuf(3S), stdio(3S).
Page 1
PUTC(3S)PUTC(3S)DIAGNOSTICS
On success, putc, putchar, and fputc each return the value they have
written. On failure, they return the constant EOF. This will occur if
the stream cannot be written for some reason, such as it is not open for
writing or if the output file cannot be extended.
Putw returns the value of ferror(stream), which is non-zero if an error
occurred on stream.
CAVEATS
When using the macro versions of putc and putchar, the stream argument
may be evaluated more than once. Thus, it must not be an expression with
side-effects. In particular, putc(c,*f++) does not work sensibly. In
these situations, the macro must either be #undef'd, or fputc 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.
BUGS
When using the macros for putc and putchar, hidden external names may be
referenced. Although these names are prefixed with an underscore, they
may conflict with names which the ANSI C Standard reserves for the user
when appearing in a local context. It is thus recommended that users of
these macros reserve all names which begin with an underscore for the
implementation, and avoid defining such names, even in a local context.
Page 2
