PUTC(3s,L) AIX Technical Reference PUTC(3s,L) ------------------------------------------------------------------------------- putc, putchar, fputc, putw, putwc, putwchar, fputwc PURPOSE Writes a character or a word to a stream. LIBRARY Standard C Library (libc.a) SYNTAX #include int putc(c, stream) int fputc(c, stream) char c; char c; FILE *stream; FILE *stream; int putchar(c) int putw(w, stream) char c; int w; FILE *stream; wchar_t putwc (c, stream) wchar_t c; wchar_t fputwc (c, stream) FILE *stream; wchar_t c; FILE *stream; wchar_t putwchar (c) wchar_t c; 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 subroutine works the same as putc, but fputc is a true subroutine rather than a macro. It runs more slowly than putc, but takes less space per invocation. Because putc is implemented as a macro, it treats incorrectly a stream parameter with side effects, such as "putc(c, *f++)". For such cases, use Processed November 7, 1990 PUTC(3s,L) 1 PUTC(3s,L) AIX Technical Reference PUTC(3s,L) fputc instead. Also, use fputc whenever you need to pass a pointer to this subroutine as a parameter to another subroutine. The putw subroutine 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 subroutine 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 subroutine are machine-dependent, and may not be readable using the getw subroutine 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 subroutine causes it to become buffered or line-buffered. Use the setbuf subroutine to change the stream's 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 new-line character is written or terminal input is requested). The putwchar subroutine returns the character written. If a write error occurs, the error indicator for the stream is set and putwchar returns WEOF. The fputwc subroutine writes the character specified by c to the output stream pointed to by stream, as a multibyte character at the position indicated by the associated file position indicator for the stream (if defined), and it advances the indicator appropriately. If the file cannot support positioning requests, or if the stream was opened with append mode, the character is appended to the output stream. RETURN VALUE Upon successful completion, each of these functions (with the exception of putw) returns the value it has written. putw returns ferror (stream). If these functions fail, they return the constant EOF. They fail if the stream is not open for writing, or if the output file size cannot be increased. Because EOF is a valid integer, you should use the ferror subroutine to detect putw errors. The putwc subroutine returns the argument path to it. If a write error occurs, the error indicator for the stream is set and putwc returns WEOF. The putwchar subroutine is equivalent to putwc with the second argument stdout. The fputwc subroutine returns the wide character written. If a write error occurs, the error indicator for the stream is set and fputwc returns WEOF. Processed November 7, 1990 PUTC(3s,L) 2 PUTC(3s,L) AIX Technical Reference PUTC(3s,L) ERROR CONDITIONS The putc, putchar, fputc, and putw subroutines fail if one or more of the following are true: EAGAIN The O_NONBLOCK flag is set for the file descriptor underlying stream and the process is delayed in the write operation. EBADF The file descriptor underlying stream is not a valid file descriptor open for writing. Note: If a wide character routine fails and errno is not set, this indicates that the translation from wide code to file code has failed. EFBIG An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size. EINTR The write operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfers for this file. 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. ENXIO A request was made of a non-existent device, or the request was outside the capabilities of the device. RELATED INFORMATION In this book: "fclose, fflush," "feof, ferror, clearerr, fileno," "fopen, freopen, fdopen," "fread, fwrite," "getc, fgetc, getchar, getw, getwc, fgetwc, getwchar," "printf, fprintf, sprintf, NLprintf, NLfprintf, NLsprintf, wsprintf," "puts, fputs, putws, fputws," "setbuf, setvbuf," and "stdio." AIX Guide to Multibyte Character Set (MBCS) Support. Processed November 7, 1990 PUTC(3s,L) 3