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.14 2003/02/23 01:47:47 ru 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 function acts essentially identically to
  79 .Fn fputc .
  80 .Pp
  81 The
  82 .Fn putchar
  83 function
  84 is identical to
  85 .Fn putc
  86 with an output stream of
  87 .Dv stdout .
  88 .Pp
  89 The
  90 .Fn putw
  91 function
  92 writes the specified
  93 .Vt int
  94 to the named output
  95 .Fa stream .
  96 .Pp
  97 The
  98 .Fn putc_unlocked
  99 and
 100 .Fn putchar_unlocked
 101 functions are equivalent to
 102 .Fn putc
 103 and
 104 .Fn putchar
 105 respectively,
 106 except that the caller is responsible for locking the stream
 107 with
 108 .Xr flockfile 3
 109 before calling them.
 110 These functions may be used to avoid the overhead of locking the stream
 111 for each character, and to avoid output being interspersed from multiple
 112 threads writing to the same stream.
 113 .Sh RETURN VALUES
 114 The functions,
 115 .Fn fputc ,
 116 .Fn putc ,
 117 .Fn putchar ,
 118 .Fn putc_unlocked
 119 and
 120 .Fn putchar_unlocked
 121 return the character written.
 122 If an error occurs, the value
 123 .Dv EOF
 124 is returned.
 125 The
 126 .Fn putw
 127 function
 128 returns 0 on success;
 129 .Dv EOF
 130 is returned if
 131 a write error occurs,
 132 or if an attempt is made to write a read-only stream.
 133 .Sh SEE ALSO
 134 .Xr ferror 3 ,
 135 .Xr flockfile 3 ,
 136 .Xr fopen 3 ,
 137 .Xr getc 3 ,
 138 .Xr putwc 3 ,
 139 .Xr stdio 3
 140 .Sh STANDARDS
 141 The functions
 142 .Fn fputc ,
 143 .Fn putc ,
 144 and
 145 .Fn putchar ,
 146 conform to
 147 .St -isoC .
 148 The
 149 .Fn putc_unlocked
 150 and
 151 .Fn putchar_unlocked
 152 functions conform to
 153 .St -p1003.1-2001 .
 154 A function
 155 .Fn putw
 156 function appeared in
 157 .At v6 .
 158 .Sh BUGS
 159 The size and byte order of an
 160 .Vt int
 161 varies from one machine to another, and
 162 .Fn putw
 163 is not recommended for portable applications.