FPUTC(3C) Standard C Library Functions FPUTC(3C)
NAME
fputc, putc, putc_unlocked, putchar, putchar_unlocked, putw - put a byte
on a stream
SYNOPSIS
#include <stdio.h>
int fputc(
int c,
FILE *stream);
int putc(
int c,
FILE *stream);
int putc_unlocked(
int c,
FILE *stream);
int putchar(
int c);
int putchar_unlocked(
int c);
int putw(
int w,
FILE *stream);
DESCRIPTION
The
fputc() function writes the byte specified by
c (converted to an
unsigned char) to the output stream pointed to by
stream, at the position
indicated by the associated file-position indicator for the stream (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
st_ctime and
st_mtime fields of the file will be marked for update
between the successful execution of
fputc() and the next successful
completion of a call to
fflush(3C) or
fclose(3C) on the same stream or a
call to
exit(3C) or
abort(3C).
The
putc() routine behaves like
fputc(), except that it is implemented as
a macro. It runs faster than
fputc(), but it takes up more space per
invocation and its name cannot be passed as an argument to a function
call.
The call
putchar(c) is equivalent to
putc(c, stdout). The
putchar() routine is implemented as a macro.
The
putc_unlocked() and
putchar_unlocked() routines are variants of
putc() and
putchar(), respectively, that do not lock the stream. It is
the caller's responsibility to acquire the stream lock before calling
these routines and releasing the lock afterwards; see
flockfile(3C) and
stdio(3C). These routines are implemented as macros.
The
putw() function writes the word (that is, type
int)
w to the output
stream (at the position at which the file offset, if defined, is
pointing). The size of a word is the size of a type
int and varies from
machine to machine. The
putw() function neither assumes nor causes
special alignment in the file.
The
st_ctime and
st_mtime fields of the file will be marked for update
between the successful execution of
putw() and the next successful
completion of a call to
fflush(3C) or
fclose(3C) on the same stream or a
call to
exit(3C) or
abort(3C).
RETURN VALUES
Upon successful completion,
fputc(),
putc(),
putc_unlocked(),
putchar(),
and
putchar_unlocked() return the value that was written. Otherwise,
these functions return EOF, the error indicator for the stream is set,
and
errno is set to indicate the error.
Upon successful completion,
putw() returns
0. Otherwise, it returns a
non-zero value, sets the error indicator for the associated
stream, and
sets
errno to indicate the error.
An unsuccessful completion will occur, for example, if the file
associated with
stream is not open for writing or if the output file
cannot grow.
ERRORS
The
fputc(),
putc(),
putc_unlocked(),
putchar(),
putchar_unlocked(), and
putw() functions will fail if either the
stream is unbuffered or the
stream's buffer needs to be flushed, and:
EAGAIN The
O_NONBLOCK flag is set for the file descriptor underlying
stream and the process would be delayed in the write operation.
EBADF The file descriptor underlying
stream is not a valid file
descriptor open for writing.
EFBIG An attempt was made to write to a file that exceeds the maximum
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.
EIO A physical I/O error has occurred, or 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.
stream was created by
open_wmemstream(3C) and a wide-character or byte sequence buffered is invalid in
the current locale. This error may also be returned under
implementation-dependent conditions.
ENOSPC There was no free space remaining on the device containing the
file.
EPIPE An attempt is 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 calling thread.
The
fputc(),
putc(),
putc_unlocked(),
putchar(),
putchar_unlocked(), and
putw() functions 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.
USAGE
Functions exist for the
putc(),
putc_unlocked(),
putchar(), and
putchar_unlocked() macros. To get the function form, the macro name must
be undefined (for example,
#undef putc).
When the macro forms are used,
putc() and
putc_unlocked() evaluate the
stream argument more than once. In particular,
putc(c, *f++); does not
work sensibly. The
fputc() function should be used instead when
evaluating the
stream argument has side effects.
Because of possible differences in word length and byte ordering, files
written using
putw() are implementation-dependent, and possibly cannot be
read using
getw(3C) by a different application or by the same application
running in a different environment.
The
putw() function is inherently byte stream oriented and is not tenable
in the context of either multibyte character streams or wide-character
streams. Application programmers are encouraged to use one of the
character-based output functions instead.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------------------+
|Interface Stability |
fputc(),
putc(), |
| |
putc_unlocked(),
putchar(), |
| | and
putchar_unlocked() are |
| | Standard. |
+--------------------+-----------------------------+
|MT-Level | See
NOTES below. |
+--------------------+-----------------------------+
SEE ALSO
getrlimit(2),
ulimit(2) write(2),
Intro(3),
abort(3C),
exit(3C),
fclose(3C),
ferror(3C),
fflush(3C),
flockfile(3C),
printf(3C),
putc(3C),
puts(3C),
setbuf(3C),
stdio(3C),
attributes(7),
standards(7)NOTES
The
fputc(),
putc(),
putchar(), and
putw() routines are MT-Safe in
multithreaded applications. The
putc_unlocked() and
putchar_unlocked() routines are unsafe in multithreaded applications.
March 25, 2020
FPUTC(3C)