putc(), putchar() — Write a character

Standards

Standards / Extensions	C or C++	Dependencies
ISO C POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#include <stdio.h>

int putc(int c, FILE *stream);
int putchar(int c);

General description

Converts c to unsigned char and then writes c to the output stream at the current position. The putchar() function is identical to:

putc(c, stdout);

These functions are also available as macros in the z/OS® XL C/C++ product. For performance purposes, it is recommended that the macro forms rather than the functional forms be used.

By default, if the stdio.h header file is included, the macro is invoked. Therefore, the stream argument expression should never be an expression with side effects.

The actual function can be accessed using one of the following methods:

For C only: do not include stdio.h.
Specify #undef, for example, #undef putc.
Surround the function name by parentheses, for example: (putchar)('a').

In a multithread application, in the presence of the feature test macro, _OPEN_THREADS, these macros are in an #undef status because they are not thread-safe.

putc() and putchar() are not supported for files opened with type=record or type=blocked.

putc() and putchar() have the same restriction as any write operation for a read immediately following a write or a write immediately following a read. Between a write and a subsequent read, there must be an intervening flush or reposition. Between a read and a subsequent write, there must also be an intervening flush or reposition unless an EOF has been reached.

If the application is not multithreaded, then setting the _ALL_SOURCE_NO_THREADS feature test macro may improve performance of the application, because it allows use of the inline version of this function.

Returned value

If successful, putc() and putchar() return the character written.

If unsuccessful, putc() and putchar() return EOF.

Example

CELEBP54

⁄* CELEBP54

   This example writes the contents of a buffer to a data
   stream.
   The body of the "for" statement is null because the
   example carries out the writing operation in the test
   expression.

 *⁄
#include <stdio.h>
#include <string.h>
#define  LENGTH 80

int main(void)
{
   FILE *stream = stdout;
   int i, ch;
   char buffer[LENGTH + 1] = "Hello world\n";

   ⁄* This could be replaced by using the fwrite routine *⁄
   for ( i = 0;
        (i < strlen(buffer)) && ((ch = putc(buffer[i], stream)) != EOF);
         ++i);
}

Output:

Hello world