1.\" $NetBSD: putc.3,v 1.12 2010/05/06 09:01:34 jruoho Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Chris Torek and the American National Standards Committee X3, 8.\" on Information Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)putc.3 8.1 (Berkeley) 6/4/93 35.\" 36.Dd May 6, 2010 37.Dt PUTC 3 38.Os 39.Sh NAME 40.Nm fputc , 41.Nm putc , 42.Nm putchar , 43.Nm putc_unlocked , 44.Nm putchar_unlocked , 45.Nm putw 46.Nd output a character or word to a stream 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.In stdio.h 51.Ft int 52.Fn fputc "int c" "FILE *stream" 53.Ft int 54.Fn putc "int c" "FILE *stream" 55.Ft int 56.Fn putchar "int c" 57.Ft int 58.Fn putc_unlocked "int c" "FILE *stream" 59.Ft int 60.Fn putchar_unlocked "int c" 61.Ft int 62.Fn putw "int w" "FILE *stream" 63.Sh DESCRIPTION 64The 65.Fn fputc 66function 67writes the character 68.Fa c 69(converted to an ``unsigned char'') 70to the output stream pointed to by 71.Fa stream . 72.Pp 73.Fn putc 74acts essentially identically to 75.Fn fputc , 76but is a macro that expands in-line. 77It may evaluate 78.Fa stream 79more than once, so arguments given to 80.Fn putc 81should not be expressions with potential side effects. 82.Pp 83.Fn putchar 84is identical to 85.Fn putc 86with an output stream of 87.Em stdout . 88.Pp 89The 90.Fn putc_unlocked 91and 92.Fn putchar_unlocked 93functions provide functionality identical to that of 94.Fn putc 95and 96.Fn putchar , 97respectively, but do not perform implicit locking of the streams they 98operate on. 99In multi-threaded programs they may be used 100.Em only 101within a scope in which the stream 102has been successfully locked by the calling thread using either 103.Xr flockfile 3 104or 105.Xr ftrylockfile 3 , 106and may later be released using 107.Xr funlockfile 3 . 108.Pp 109The 110.Fn putw 111function 112writes the specified 113.Em int 114to the named output 115.Fa stream . 116.Sh RETURN VALUES 117The functions, 118.Fn fputc , 119.Fn putc 120and 121.Fn putchar 122return the character written. 123If an error occurs, the value 124.Dv EOF 125is returned. 126The 127.Fn putw 128function 129returns 0 on success; 130.Dv EOF 131is returned if 132a write error occurs, 133or if an attempt is made to write a read-only stream. 134.Sh SEE ALSO 135.Xr ferror 3 , 136.Xr fopen 3 , 137.Xr getc 3 , 138.Xr stdio 3 139.Sh STANDARDS 140The functions 141.Fn fputc , 142.Fn putc , 143and 144.Fn putchar , 145conform to 146.St -ansiC . 147The functions 148.Fn putc_unlocked 149and 150.Fn putchar_unlocked 151conform to 152.St -p1003.1-96 . 153.Sh HISTORY 154The functions 155.Fn putc , 156.Fn putchar , 157and 158.Fn putw 159first appeared in 160.At v6 . 161The function 162.Fn fputc 163appeared in 164.At v7 . 165.Sh BUGS 166The size and byte order of an 167.Em int 168varies from one machine to another, and 169.Fn putw 170is not recommended for portable applications. 171