putc(3)putc(3)NAME
putc, fputc, putc_unlocked, putchar, putchar_unlocked, putw - Write a
byte or a word to a stream
SYNOPSIS
#include <stdio.h>
int putc(
int c,
FILE *stream ); int fputc(
int c,
FILE *stream ); int putc_inlocked(
int c,
FILE *file ); int putchar(
int c ); int putchar_unlocked(
int c ); int putw(
int w,
FILE *stream );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
fputc(), putc(), putc_unlocked, putchar(), putchar_unlocked, putw():
XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the byte to be written. Points to the file structure of an
open file. Specifies the word to be written.
DESCRIPTION
The putc() function writes the byte c (converted to an unsigned char)
to the output specified by the stream parameter. The byte is written at
the position at which the file pointer is currently pointing (if
defined) and advances the indicator appropriately. If the file cannot
support positioning requests, or if the stream was opened with append
mode, the byte is appended to the output stream.
The putc() function may be a macro (depending on compile-time defini‐
tions). See the NOTES section for more information.
The fputc() function performs the same operation as putc(), but fputc()
is never a macro. The fputc() function runs more slowly than putc(),
but requires less space per invocation.
The putchar() function is the same as the putc() function except that
putchar() writes to the standard output. Note that putchar() can also
be a macro.
[Tru64 UNIX] The reentrant versions of these functions are locked
against simultaneous calls from multiple threads. This locking incurs
overhead to ensure integrity of the stream. To avoid locking overhead,
use the unlocked versions of these calls, the putc_unlocked() and
putchar_unlocked() functions. The putc_unlocked() and
putchar_unlocked() functions are functionally identical to the putc()
and putchar() functions, except that putc_unlocked() and
putchar_unlocked() may be safely used only within a scope that is pro‐
tected by the flockfile() and funlockfile() functions used as a pair.
The caller must ensure that the stream is locked before these functions
are used.
The putw() function 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 one processor
architecture to another. The putw() function 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() function are machine dependent, and may not be
readable using the getw() function on a different processor.
The st_ctime and st_mtime fields of the file are marked for update
between the successful execution of the putc(), putw(), putchar(), or
fputc() function and the next successful completion of a call to one of
the following: The fflush() or fclose() function on the same stream The
exit() or abort() function
NOTES
The putc() and putchar() functions may be macros (depending on the com‐
pile-time definitions used in the source). Consequently, you cannot
use these interfaces where a function is necessary; for example, a sub‐
routine pointer cannot point to one of these interfaces. In addition,
putc() does not work correctly with a stream parameter that has side
effects. In particular, the following does not work:
putc(*f++)
In cases like this one, use the fputc() function instead.
RETURN VALUES
The putc(), putc_unlocked(), putchar(), putchar_unlocked(), and fputc()
functions, upon successful completion, return the value written. If
these functions fail, they return the constant EOF. They fail if the
stream parameter is not open for writing, or if the size of the output
file cannot be increased. The putw() function, upon successful comple‐
tion, returns a value of 0 (zero). Otherwise, the function returns a
nonzero value.
ERRORS
The putc(), putc_unlocked(), putw(), putchar(), putchar_unlocked(), and
fputc() functions fail under either of the following conditions: The
stream is unbuffered. The stream's buffer needed to be flushed and the
function call caused an underlying write() or lseek() operation to be
invoked and this underlying operation fails.
In addition, the putc(), putw(), putchar(), and fputc() functions set
errno to the specified value for the following conditions: The O_NON‐
BLOCK option is set for the file descriptor underlying stream and the
process would be delayed in the write operation. The file descriptor
underlying stream is not a valid file descriptor open for writing. An
attempt was made to write to a file that exceeds the process's file
size limit or the maximum file size. The write operation was inter‐
rupted by a signal that was caught, and no data was transferred. The
implementation supports job control; the process is a member of a back‐
ground 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.
A physical I/O error has occurred. This condition is specified
for Issue 4 Version 2 and higher issues of the XSH specifica‐
tion. There was no free space remaining on the device contain‐
ing the file. An attempt was made to write to a pipe or FIFO
that is not open for reading by any process. A SIGPIPE signal
will also be sent to the process.
SEE ALSO
Functions: ferror(3), fgetws(3), flockfile(3), fputws(3), funlock‐
file(3), getc(3), getwc(3), printf(3), puts(3), putwc(3)
Standards: standards(5)putc(3)
