Writes a character or a word to a stream.
Standard I/O Package (libc.a)
The putc and putchar macros write a character or word to a stream. The fputc and putw subroutines serve similar purposes but are true subroutines.
The putc macro writes the character Character (converted to an unsigned char data type) 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 putchar macro is the same as the putc macro except that putchar writes to the standard output.
The fputc subroutine works the same as the putc macro, but fputc is a true subroutine rather than a macro. It runs more slowly than putc, but takes less space per invocation.
Because putc is implemented as a macro, it incorrectly treats a Stream parameter with side effects, such as putc(C, *f++). For such cases, use the fputc subroutine instead. Also, use fputc whenever you need to pass a pointer to this subroutine as a parameter to another subroutine.
The putc and putchar macros have also been implemented as subroutines for ANSI compatibility. To access the subroutines instead of the macros, insert #undef putc or #undef putchar at the beginning of the source file.
The putw subroutine writes the word (int data type) specified by the Word 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 machine to machine. The putw subroutine does not assume or cause special alignment of the data in the file.
After the fputcw, putwc, fputc, putc, fputs, puts, or putw subroutine runs successfully, and before the next successful completion of a call either to the fflush or fclose subroutine on the same stream or to the exit or abort subroutine, the st_ctime and st_mtime fields of the file are marked for update.
Because of possible differences in word length and byte ordering, files written using the putw subroutine are machine-dependent, and may not be readable using the getw subroutine 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 subroutine causes it to become buffered or line-buffered. Use the setbuf subroutine 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 it 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 new-line character is written or terminal input is requested).
| Item | Description |
|---|---|
| Stream | Points to the file structure of an open file. |
| Character | Specifies a character to be written. |
| Word | Specifies a word to be written (not portable because word length and byte-ordering are machine-dependent). |
Upon successful completion, these functions each 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 output file size cannot be increased. Because the EOF value is a valid integer, you should use the ferror subroutine to detect putw errors.
The fputc subroutine will fail if either the Stream is unbuffered or the Stream buffer needs to be flushed, and:
| Item | Description |
|---|---|
| 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 a file that exceeds the file size of the process limit or the maximum file size. |
| 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 either no data was transferred or the implementation
does not report partial transfers for this file. Note: Depending
upon which library routine the application binds to, this subroutine
may return EINTR. Refer to the signal Subroutine regarding sa_restart.
|
| EIO | A physical I/O error has occurred, or the process is a member of a background process group attempting to perform a write subroutine to its controlling terminal, the TOSTOP flag is set, the process is neither ignoring nor blocking the SIGTTOU signal and the process group of the process is orphaned. 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 first-in-first-out (FIFO) that is not open for reading by any process. A SIGPIPE signal will also be sent to the process. |
The fputc subroutine may fail if:
| Item | Description |
|---|---|
| ENOMEM | Insufficient storage space is available. |
| ENXIO | A request was made of a nonexistent device, or the request was outside the capabilities of the device. |