stdio/fputs.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 .\"     @(#)fputs.3     8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/stdio/fputs.3,v 1.11 2002/12/19 09:40:24 ru Exp $
  38 .\"
  39 .Dd June 4, 1993
  40 .Dt FPUTS 3
  41 .Os
  42 .Sh NAME
  43 .Nm fputs ,
  44 .Nm puts
  45 .Nd output a line to a stream
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In stdio.h
  50 .Ft int
  51 .Fo fputs
  52 .Fa "const char *restrict s"
  53 .Fa "FILE *restrict stream"
  54 .Fc
  55 .Ft int
  56 .Fo puts
  57 .Fa "const char *s"
  58 .Fc
  59 .Sh DESCRIPTION
  60 The function
  61 .Fn fputs
  62 writes the string pointed to by
  63 .Fa s
  64 to the stream pointed to by
  65 .Fa stream .
  66 .\" The terminating
  67 .\" .Dv NUL
  68 .\" character is not written.
  69 .Pp
  70 The function
  71 .Fn puts
  72 writes the string
  73 .Fa s ,
  74 and a terminating newline character,
  75 to the stream
  76 .Dv stdout .
  77 .Sh RETURN VALUES
  78 The
  79 .Fn fputs
  80 function
  81 returns 0 on success and
  82 .Dv EOF
  83 on error;
  84 .Fn puts
  85 returns a nonnegative integer on success and
  86 .Dv EOF
  87 on error.
  88 .Sh ERRORS
  89 .Bl -tag -width Er
  90 .It Bq Er EBADF
  91 The
  92 .Fa stream
  93 argument
  94 is not a writable stream.
  95 .El
  96 .Pp
  97 The functions
  98 .Fn fputs
  99 and
 100 .Fn puts
 101 may also fail and set
 102 .Va errno
 103 for any of the errors specified for the routines
 104 .Xr write 2 .
 105 .Sh COMPATIBILITY
 106 .Fn fputs
 107 now returns a non-negative number (as opposed to 0)
 108 on successful completion.
 109 As a result, many tests (e.g., "fputs() == 0", "fputs() != 0")
 110 do not give the desired result.
 111 Use "fputs() != EOF" or "fputs() == EOF"
 112 to determine success or failure.
 113 .Sh SEE ALSO
 114 .Xr ferror 3 ,
 115 .Xr fputws 3 ,
 116 .Xr putc 3 ,
 117 .Xr stdio 3
 118 .Sh STANDARDS
 119 The functions
 120 .Fn fputs
 121 and
 122 .Fn puts
 123 conform to
 124 .St -isoC .
 125 While not mentioned in the standard, both
 126 .Fn fputs
 127 and
 128 .Fn puts
 129 print
 130 .Ql (null)
 131 if
 132 .Fa str
 133 is
 134 .Dv NULL .