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. 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.5.2.3 2001/12/14 18:33:57 ru Exp $
  38 .\"
  39 .Dd June 4, 1993
  40 .Dt PUTC 3
  41 .Os
  42 .Sh NAME
  43 .Nm fputc ,
  44 .Nm putc ,
  45 .Nm putchar ,
  46 .Nm putw
  47 .Nd output a character or word to a stream
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In stdio.h
  52 .Ft int
  53 .Fn fputc "int c" "FILE *stream"
  54 .Ft int
  55 .Fn putc "int c" "FILE *stream"
  56 .Ft int
  57 .Fn putchar "int c"
  58 .Ft int
  59 .Fn putw "int w" "FILE *stream"
  60 .Sh DESCRIPTION
  61 The
  62 .Fn fputc
  63 function
  64 writes the character
  65 .Fa c
  66 (converted to an ``unsigned char'')
  67 to the output stream pointed to by
  68 .Fa stream .
  69 .Pp
  70 The
  71 .Fn putc
  72 macro acts essentially identically to
  73 .Fn fputc ,
  74 but is a macro that expands in-line.
  75 It may evaluate
  76 .Fa stream
  77 more than once, so arguments given to
  78 .Fn putc
  79 should not be expressions with potential side effects.
  80 .Pp
  81 The
  82 .Fn putchar
  83 macro
  84 is identical to
  85 .Fn putc
  86 with an output stream of
  87 .Em stdout .
  88 .Pp
  89 The
  90 .Fn putw
  91 function
  92 writes the specified
  93 .Em int
  94 to the named output
  95 .Fa stream .
  96 .Sh RETURN VALUES
  97 The functions,
  98 .Fn fputc ,
  99 .Fn putc
 100 and
 101 .Fn putchar
 102 return the character written.
 103 If an error occurs, the value
 104 .Dv EOF
 105 is returned.
 106 The
 107 .Fn putw
 108 function
 109 returns 0 on success;
 110 .Dv EOF
 111 is returned if
 112 a write error occurs,
 113 or if an attempt is made to write a read-only stream.
 114 .Sh SEE ALSO
 115 .Xr ferror 3 ,
 116 .Xr fopen 3 ,
 117 .Xr getc 3 ,
 118 .Xr stdio 3
 119 .Sh STANDARDS
 120 The functions
 121 .Fn fputc ,
 122 .Fn putc ,
 123 and
 124 .Fn putchar ,
 125 conform to
 126 .St -isoC .
 127 A function
 128 .Fn putw
 129 function appeared in
 130 .At v6 .
 131 .Sh BUGS
 132 The size and byte order of an
 133 .Em int
 134 varies from one machine to another, and
 135 .Fn putw
 136 is not recommended for portable applications.