lib/libc/stdio/putc.3

   1 .\"     $NetBSD: putc.3,v 1.12 2010/05/06 09:01:34 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Chris Torek and the American National Standards Committee X3,
   8 .\" on Information Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)putc.3      8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd May 6, 2010
  37 .Dt PUTC 3
  38 .Os
  39 .Sh NAME
  40 .Nm fputc ,
  41 .Nm putc ,
  42 .Nm putchar ,
  43 .Nm putc_unlocked ,
  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 putchar "int c"
  57 .Ft int
  58 .Fn putc_unlocked "int c" "FILE *stream"
  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 .Fn putc
  74 acts essentially identically to
  75 .Fn fputc ,
  76 but is a macro that expands in-line.
  77 It may evaluate
  78 .Fa stream
  79 more than once, so arguments given to
  80 .Fn putc
  81 should not be expressions with potential side effects.
  82 .Pp
  83 .Fn putchar
  84 is identical to
  85 .Fn putc
  86 with an output stream of
  87 .Em stdout .
  88 .Pp
  89 The
  90 .Fn putc_unlocked
  91 and
  92 .Fn putchar_unlocked
  93 functions provide functionality identical to that of
  94 .Fn putc
  95 and
  96 .Fn putchar ,
  97 respectively, but do not perform implicit locking of the streams they
  98 operate on.
  99 In multi-threaded programs they may be used
 100 .Em only
 101 within a scope in which the stream
 102 has been successfully locked by the calling thread using either
 103 .Xr flockfile 3
 104 or
 105 .Xr ftrylockfile 3 ,
 106 and may later be released using
 107 .Xr funlockfile 3 .
 108 .Pp
 109 The
 110 .Fn putw
 111 function
 112 writes the specified
 113 .Em int
 114 to the named output
 115 .Fa stream .
 116 .Sh RETURN VALUES
 117 The functions,
 118 .Fn fputc ,
 119 .Fn putc
 120 and
 121 .Fn putchar
 122 return the character written.
 123 If an error occurs, the value
 124 .Dv EOF
 125 is returned.
 126 The
 127 .Fn putw
 128 function
 129 returns 0 on success;
 130 .Dv EOF
 131 is returned if
 132 a write error occurs,
 133 or if an attempt is made to write a read-only stream.
 134 .Sh SEE ALSO
 135 .Xr ferror 3 ,
 136 .Xr fopen 3 ,
 137 .Xr getc 3 ,
 138 .Xr stdio 3
 139 .Sh STANDARDS
 140 The functions
 141 .Fn fputc ,
 142 .Fn putc ,
 143 and
 144 .Fn putchar ,
 145 conform to
 146 .St -ansiC .
 147 The functions
 148 .Fn putc_unlocked
 149 and
 150 .Fn putchar_unlocked
 151 conform to
 152 .St -p1003.1-96 .
 153 .Sh HISTORY
 154 The functions
 155 .Fn putc ,
 156 .Fn putchar ,
 157 and
 158 .Fn putw
 159 first appeared in
 160 .At v6 .
 161 The function
 162 .Fn fputc
 163 appeared in
 164 .At v7 .
 165 .Sh BUGS
 166 The size and byte order of an
 167 .Em int
 168 varies from one machine to another, and
 169 .Fn putw
 170 is not recommended for portable applications.