[Go to CFHT Home Page] Man Pages
Back to Software Index  BORDER=0Manpage Top Level
    putc(3S) manual page Table of Contents

Name

putc, putc_unlocked, putchar, putchar_unlocked, fputc, putw - put character or word on a stream

Synopsis

#include <stdio.h>

int putc(int c, FILE *stream);

int putc_unlocked(int c, FILE *stream);

int putchar(int c);

int putchar_unlocked(int c);

int fputc(int c, FILE *stream);

int putw(int w, FILE *stream);

MT-Level

See the NOTES section of this page.

Description

putc() writes c (converted to an unsigned char) onto the output stream (see intro(3) ) at the position where the file pointer (if defined) is pointing, and advances the file pointer appropriately. If the file cannot support positioning requests, or stream was opened with append mode, the character is appended to the output stream. putchar(c) is defined as putc(c, stdout). putc() and putchar() are macros.

putc_unlocked() and putchar_unlocked() are respectively variants of putc() and putchar() that do not lock the stream. It is the caller’s responsibility to acquire the stream lock before calling these functions and releasing the lock afterwards; see flockfile(3S) and stdio(3S) .

fputc() behaves like putc(), but is a function rather than a macro. fputc() runs more slowly than putc(), but it takes less space per invocation and its name can be passed as an argument to a function.

putw() writes the C int (word) w to the standard I/O output stream (at the position of the file pointer, if defined). The size of a word is the size of an integer and varies from machine to machine. putw() neither assumes nor causes special alignment in the file.

Return Values

On success, putc(), fputc(), and putchar() return the value that was written. On error, those functions return the constant EOF. putw() returns ferror(stream), so that it returns 0 on success and 1 on failure.

Failure will occur, for example, if the file stream is not open for writing or if the output file cannot grow.

See Also

write(2) , intro(3) , fclose(3S) , ferror(3S) , flockfile(3S) , fopen(3S) , printf(3S) , puts(3S) , setbuf(3S) , stdio(3S)

Notes

Because it is implemented as a macro, putc() evaluates a stream argument more than once. In particular, putc(c, *f++); does not work sensibly. fputc() should be used instead.

Because of possible differences in word length and byte ordering, files written using putw() are machine-dependent, and may not be read using getw() on a different processor.

Functions exist for all the above defined macros. To get the function form, the macro name must be undefined (for example, #undef putc).

fputc(), putc(), putchar(), and putw() are MT-Safe in multi-thread applications. putc_unlocked() and putchar_unlocked() are unsafe in multi-thread applications.

Table of Contents