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