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 ALSO
     fclose(3S), ferror(3S), fopen(3S), fread(3S), printf(3S), puts(3S),
     setbuf(3S), stdio(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