OSF

NAME

putc, putchar, fputc, putw − Writes a character or a word to a stream

LIBRARY

Standard I/O Package (libc.a)

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 );

PARAMETERS

streamPoints to the file structure of an open file. 

cSpecifies the character to be written. 

wSpecifies the word to be written. 

DESCRIPTION

The putc() macro writes the character c 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() function works the same as the putc() macro, but fputc() is a true function 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() function.  Also, use fputc() when you need to pass a pointer to this function as a parameter to another function. 

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 machine to machine. 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. 

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() function causes it to become buffered or line-buffered. Use the setbuf() function 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 newline character is written or terminal input is requested). 

The st_ctime and st_mtime fields of the file are marked for update between the successful execution of the putc(), putw(), putchar(), or fputc() function, and the next successful completion of a call to the fflush() or fclose() function on the same stream, or a call to the exit() or abort() function. 

NOTES

The reentrant versions of these functions are locked against multiple threads calling them simultaneously.  This will incur an overhead to ensure integrity of the stream.  The unlocked versions of these calls may be used safely, providing that the stream is locked when the calls are used with the flockfile() and funlockfile() functions. 

AES Support Level:
Full use (putc(), fputc(), putchar()) Trial use (putw())

RETURN VALUES

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() function to detect the putw() parameter errors. 

ERRORS

The putc(), putw(), putchar(), and fputc() functions fail if either the stream is unbuffered, or the stream’s buffer needed to be flushed and the function call caused an underlying write() or lseek() to be invoked.  In addition, if the putc(), putw(), putchar(), or fputc() function fails, errno may be set to one of the following values:

[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’ file size limit or the maximum file size. 

[EINTR]The read operation was interrupted by a signal which was caught, and no data was transferred. 

[EIO]The implementation supports job control, the process is a member of a background process group attempting 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 implementation-defined conditions. 

[ENOSPC]There was no free space remaining on the device containing the file. 

[EPIPE]An attempt 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: getc(3), getwc(3), printf(3), puts(3), putwc(3), unlocked_putc(3), unlocked_putchar(3)