Content-type: text/html Man page of putc

putc

Section: C Library Functions (3)
Index Return to Main Contents
 

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 standards 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 industry 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 defined) 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 definitions). 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_unlocked() functions. The putc_unlocked() and putchar_unlocked() functions 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 funlockfile() 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 between 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 compile-time definitions used in the source). Consequently, you cannot use these interfaces where a function is necessary; for example, a subroutine 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 completion, 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 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.

[XPG4-UNIX]  A physical I/O error has occurred. There was no free space remaining on the device containing the file. 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: ferror(3), fgetws(3), flockfile(3), fputws(3), funlockfile(3), getc(3), getwc(3), printf(3), puts(3), putwc(3)

Standards: standards(5) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:41:28 GMT, October 02, 2010