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