 |
Index for
Section 3 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
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 standards
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
c Specifies the byte to be written.
stream
Points to the file structure of an open file.
w 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 definitions).
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 protected 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
compile-time definitions used in the source). Consequently, you cannot use
these interfaces where a function is necessary; for example, a subroutine
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 completion, 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:
[EAGAIN]
The O_NONBLOCK option 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 process's file
size limit or the maximum file size.
[EINTR]
The write operation was interrupted by a signal that was caught, and no
data was transferred.
[EIO]
The implementation supports job control; 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. 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 specification.
[ENOSPC]
There was no free space remaining on the device containing the file.
[EPIPE]
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), funlockfile(3),
getc(3), getwc(3), printf(3), puts(3), putwc(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|