putc(3S)

NAME

putc(), putchar(), fputc(), putw() — put character or word on a stream

SYNOPSIS

#include <stdio.h>

int putc(int c, FILE *stream);

int putchar(int c);

int fputc(int c, FILE *stream);

int putw(int w, FILE *stream);

int putc_unlocked(int c, FILE *stream);

int putchar_unlocked(int c);

Obsolescent Interfaces

int putw_unlocked(int w, FILE *stream);

DESCRIPTION

putc(): Writes the character c onto the output stream at the position where the file pointer, if defined, is pointing. putchar(c) is defined as putc(c, stdout). putc() and putchar() are defined both as macros and as functions.
fputc(): Same as putc(), but is a function rather than a macro, and can therefore be used as an argument. fputc() runs more slowly than putc(), but takes less space per invocation, and its name can be passed as an argument to a function.
putw(): Writes the word (i.e., int in C) w to the output stream (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. putw() neither assumes nor causes special alignment in the file.

Output streams, with the exception of the standard error stream stderr, are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, stderr, is by default unbuffered, but use of freopen() (see fopen(3S)) causes it to become buffered or line-buffered. setbuf() or setvbuf() (see setbuf(3S)) can be used to change the stream's buffering strategy. putc_unlocked(), putchar_unlocked(), put character on a stream.

Obsolescent Interfaces

putw_unlocked() put character or word on a stream.

APPLICATION USAGE

After putc(), fputc(), putchar(), or putw() is applied to a stream, the stream becomes byte-oriented (see orientation(5)).

RETURN VALUE

On success, putc(), putc_unlocked(), fputc(), putchar() and putchar_unlocked() each return the value they have written. On failure, they return the constant EOF, set the error indicator for the stream, and set errno to indicate the error.

On success, putw() and putw_unlocked() return 0. Otherwise, a non-zero value is returned, the error indicator for the stream is set, and errno is set to indicate the error.

ERRORS

putc(), putc_unlocked(), putchar(), putchar_unlocked(), fputc(), putw(), and putw_unlocked() fail if, either the stream is unbuffered or stream's buffer needed to be flushed causing an underlying write() call to be invoked, and:

[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 (see ulimit(2)).
[EINTR]: A signal was caught during the write() system call.
[EIO]: A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, TOSTOP is set, the process is neither ignoring nor blocking the SIGTTOU signal, and the process group of the process is orphaned.
[ENOSPC]: There was no free space remaining on the device containing the file.
[EPIPE]: An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A SIGPIPE signal is also sent to the process.

Additional errno values can be set by the underlying write() function (see write(2)).

WARNINGS

The putc() and putchar() routines are implemented as both library functions and macros. The macro versions, which are used by default, are defined in <stdio.h>. To obtain the library function either use a #undef to remove the macro definition or, if compiling in ANSI-C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods:

#include <stdio.h> 
#undef putc 
  ...
main()
{
    int (*put_char()) ();
      ...
    return_val=putc(c,fd);
      ...
    return_val=(putc)(c,fd1);
      ...
    put_char = putchar;
};

Line buffering may cause confusion or malfunctioning of programs that use standard I/O routines but use read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to fflush() (see fclose(3S)) the standard output before beginning the computation.

The macro version of putc() incorrectly treats the argument stream with side effects. In particular, the following call may not work as expected:

putc(c, *f++); 

The function version of putc() or 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 readable by getw() on a different processor.

putw_unlocked() is an obsolescent interface supported only for compatibility with existing DCE applications. New multithreaded applications should use putc(), putchar() and putw().

Reentrant Interfaces

If _REENTRANT is defined, the locked versions of the library functions for putc() and putchar() are used by default.

STANDARDS CONFORMANCE

putc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

fputc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

putchar(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

putw(): AES, SVID2, SVID3, XPG2, XPG3, XPG4

putc(3S)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

Obsolescent Interfaces

DESCRIPTION

Obsolescent Interfaces

APPLICATION USAGE

RETURN VALUE

ERRORS

WARNINGS

Reentrant Interfaces

SEE ALSO

STANDARDS CONFORMANCE