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 .\" 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 .Fn fputc "int c" "FILE *stream"
  56 .Ft int
  57 .Fn putc "int c" "FILE *stream"
  58 .Ft int
  59 .Fn putc_unlocked "int c" "FILE *stream"
  60 .Ft int
  61 .Fn putchar "int c"
  62 .Ft int
  63 .Fn putchar_unlocked "int c"
  64 .Ft int
  65 .Fn putw "int w" "FILE *stream"
  66 .Sh DESCRIPTION
  67 The
  68 .Fn fputc
  69 function
  70 writes the character
  71 .Fa c
  72 (converted to an ``unsigned char'')
  73 to the output stream pointed to by
  74 .Fa stream .
  75 .Pp
  76 The
  77 .Fn putc
  78 macro acts essentially identically to
  79 .Fn fputc ,
  80 but is a macro that expands in-line.
  81 It may evaluate
  82 .Fa stream
  83 more than once, so arguments given to
  84 .Fn putc
  85 should not be expressions with potential side effects.
  86 .Pp
  87 The
  88 .Fn putchar
  89 function
  90 is identical to
  91 .Fn putc
  92 with an output stream of
  93 .Dv stdout .
  94 .Pp
  95 The
  96 .Fn putw
  97 function
  98 writes the specified
  99 .Vt int
 100 to the named output
 101 .Fa stream .
 102 .Pp
 103 The
 104 .Fn putc_unlocked
 105 and
 106 .Fn putchar_unlocked
 107 functions are equivalent to
 108 .Fn putc
 109 and
 110 .Fn putchar
 111 respectively,
 112 except that the caller is responsible for locking the stream
 113 with
 114 .Xr flockfile 3
 115 before calling them.
 116 These functions may be used to avoid the overhead of locking the stream
 117 for each character, and to avoid output being interspersed from multiple
 118 threads writing to the same stream.
 119 .Sh RETURN VALUES
 120 The functions,
 121 .Fn fputc ,
 122 .Fn putc ,
 123 .Fn putchar ,
 124 .Fn putc_unlocked
 125 and
 126 .Fn putchar_unlocked
 127 return the character written.
 128 If an error occurs, the value
 129 .Dv EOF
 130 is returned.
 131 The
 132 .Fn putw
 133 function
 134 returns 0 on success;
 135 .Dv EOF
 136 is returned if
 137 a write error occurs,
 138 or if an attempt is made to write a read-only stream.
 139 .Sh SEE ALSO
 140 .Xr ferror 3 ,
 141 .Xr flockfile 3 ,
 142 .Xr fopen 3 ,
 143 .Xr getc 3 ,
 144 .Xr putwc 3 ,
 145 .Xr stdio 3
 146 .Sh STANDARDS
 147 The functions
 148 .Fn fputc ,
 149 .Fn putc ,
 150 and
 151 .Fn putchar ,
 152 conform to
 153 .St -isoC .
 154 The
 155 .Fn putc_unlocked
 156 and
 157 .Fn putchar_unlocked
 158 functions conform to
 159 .St -p1003.1-2001 .
 160 A function
 161 .Fn putw
 162 function appeared in
 163 .At v6 .
 164 .Sh BUGS
 165 The size and byte order of an
 166 .Vt int
 167 varies from one machine to another, and
 168 .Fn putw
 169 is not recommended for portable applications.