*** UNIX MANUAL PAGE BROWSER ***

putc(3) Library Functions Manual putc(3) NAME putc, fputc, putc_unlocked, putchar, putchar_unlocked, putw - Write a byte or a word to a stream LIBRARY Standard C Library (libc.so, 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); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: putc_unlocked, putchar_unlocked: POSIX.1c fputc(), putc(), putchar(), putw(): XPG4, XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry 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 de- fined) 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. [Digital] 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_un- locked() functions. The putc_unlocked() and putchar_unlocked() func- tions 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 funlock- file() 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 be- tween 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_NONBLOCK flag 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 interrupted by a signal that was caught, and no data was transferred. The implementation supports job control; the process is a member of a background process group attempt- ing 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 implementa- tion-defined conditions. [XPG4-UNIX] A physical I/O error has occurred. There was no free space remaining on the device containing the file. An at- tempt 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), funlock- file(3), getc(3), getwc(3), printf(3), puts(3), putwc(3) Standards: standards(5) delim off putc(3)