stdio/putc.3

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