lib/libc/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. 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 .\"     @(#)fputs.3     8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd January 23, 2020
  36 .Dt FPUTS 3
  37 .Os
  38 .Sh NAME
  39 .Nm fputs ,
  40 .Nm fputs_unlocked ,
  41 .Nm puts
  42 .Nd output a line to a stream
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In stdio.h
  47 .Ft int
  48 .Fn fputs "const char *str" "FILE *stream"
  49 .Ft int
  50 .Fn fputs_unlocked "const char *str" "FILE *stream"
  51 .Ft int
  52 .Fn puts "const char *str"
  53 .Sh DESCRIPTION
  54 The function
  55 .Fn fputs
  56 writes the string pointed to by
  57 .Fa str
  58 to the stream pointed to by
  59 .Fa stream .
  60 .\" The terminating
  61 .\" .Dv NUL
  62 .\" character is not written.
  63 .Pp
  64 The
  65 .Fn fputs_unlocked
  66 function is equivalent to
  67 .Fn fputs ,
  68 except that the caller is responsible for locking the stream with
  69 .Xr flockfile 3
  70 before calling it.
  71 This function may be used to avoid the overhead of locking the stream and to
  72 prevent races when multiple threads are operating on the same stream.
  73 .Pp
  74 The function
  75 .Fn puts
  76 writes the string
  77 .Fa str ,
  78 and a terminating newline character,
  79 to the stream
  80 .Dv stdout .
  81 .Sh RETURN VALUES
  82 The functions
  83 .Fn fputs
  84 and
  85 .Fn puts
  86 return a nonnegative integer on success and
  87 .Dv EOF
  88 on error.
  89 .Sh ERRORS
  90 .Bl -tag -width Er
  91 .It Bq Er EBADF
  92 The
  93 .Fa stream
  94 argument
  95 is not a writable stream.
  96 .El
  97 .Pp
  98 The functions
  99 .Fn fputs
 100 and
 101 .Fn puts
 102 may also fail and set
 103 .Va errno
 104 for any of the errors specified for the routines
 105 .Xr write 2 .
 106 .Sh SEE ALSO
 107 .Xr ferror 3 ,
 108 .Xr fputws 3 ,
 109 .Xr putc 3 ,
 110 .Xr stdio 3
 111 .Sh STANDARDS
 112 The functions
 113 .Fn fputs
 114 and
 115 .Fn puts
 116 conform to
 117 .St -isoC .