NAME

putc, fputc, putc_unlocked, putchar, putchar_unlocked, putw −  Write a character or a word to a stream

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <stdio.h>

int putc(
        int c,
        FILE ∗stream);

int fputc(
        int c,
        FILE ∗stream);

int putc_unlocked(
        int c,
        FILE ∗ file);

int putchar(
        int c);

int putchar_unlocked(
        int c);

int putw(
        int w,
        FILE ∗stream);

PARAMETERS

cSpecifies the character to be written. 

streamPoints to the file structure of an open file. 

wSpecifies the word to be written. 

DESCRIPTION

The putc() function writes the character c to the output specified by the stream parameter.  The character is written at the position at which the file pointer is currently pointing, if defined. 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. 

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. 

With the exception of stderr, output streams are, by default, buffered if they refer to files, or line buffered if they refer to terminals. The standard error output stream, stderr, is unbuffered by default, but using the freopen() function causes stderr to become buffered or line buffered.  Use the setbuf() function to change the stream buffering strategy. 

When an output stream is unbuffered, information is queued for writing on the destination file or terminal as soon as the information is written.  When an output stream is buffered, many characters are saved and written as a block. When an output stream is line-buffered, each line of output is queued for writing on the destination terminal as soon as the line is completed (that is, as soon as a newline character is written or terminal input is requested). 

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. 

AES Support Level:
Full use (putc(), fputc(), putchar()). 

Trial use (putw()). 

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, if any of the following conditions occur, the putc(), putw(), putchar(), and fputc() functions set errno to the corresponding value. 

[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 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. 

[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. 

RELATED INFORMATION

Functions: ferror(3), fgetws(3), flockfile(3), fputws(3), funlockfile(3), getc(3), getwc(3), printf(3), puts(3), putwc(3).