lib/libc/stdio/fclose.3

   1 .\" Copyright (c) 1990, 1991, 1993 The Regents of the University of California.
   2 .\" Copyright (c) 2015 Mariusz Zaborski <oshogbo@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to Berkeley by
   6 .\" Chris Torek and the American National Standards Committee X3,
   7 .\" on Information Processing Systems.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)fclose.3    8.1 (Berkeley) 6/4/93
  34 .\" $FreeBSD$
  35 .\"
  36 .Dd July 4, 2015
  37 .Dt FCLOSE 3
  38 .Os
  39 .Sh NAME
  40 .Nm fclose ,
  41 .Nm fdclose ,
  42 .Nm fcloseall
  43 .Nd close a stream
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In stdio.h
  48 .Ft int
  49 .Fn fclose "FILE *stream"
  50 .Ft int
  51 .Fn fdclose "FILE *stream" "int *fdp"
  52 .Ft void
  53 .Fn fcloseall void
  54 .Sh DESCRIPTION
  55 The
  56 .Fn fclose
  57 function
  58 dissociates the named
  59 .Fa stream
  60 from its underlying file or set of functions.
  61 If the stream was being used for output, any buffered data is written
  62 first, using
  63 .Xr fflush 3 .
  64 .Pp
  65 The
  66 .Fn fdclose
  67 function is equivalent to
  68 .Fn fclose
  69 except that it does not close the underlying file descriptor.
  70 If
  71 .Fa fdp
  72 is not
  73 .Dv NULL ,
  74 the file descriptor will be written to it.
  75 If the
  76 .Fa fdp
  77 argument will be different then NULL the file descriptor will be returned in it,
  78 If the stream does not have an associated file descriptor,
  79 .Fa fdp
  80 will be set to -1.
  81 This type of stream is created with functions such as
  82 .Xr fmemopen 3 ,
  83 .Xr funopen 3 ,
  84 or
  85 .Xr open_memstream 3 .
  86 .Pp
  87 The
  88 .Fn fcloseall
  89 function calls
  90 .Fn fclose
  91 on all open streams.
  92 .Sh RETURN VALUES
  93 .Fn fcloseall
  94 does not return a value.
  95 .Pp
  96 Upon successful completion the
  97 .Fn fclose
  98 and
  99 .Fn fdclose
 100 functions return 0.
 101 Otherwise,
 102 .Dv EOF
 103 is returned and the global variable
 104 .Va errno
 105 is set to indicate the error.
 106 .Sh ERRORS
 107 .Fn fdclose
 108 fails if:
 109 .Bl -tag -width Er
 110 .It Bq Er EOPNOTSUPP
 111 The stream does not have an associated file descriptor.
 112 .El
 113 .Pp
 114 The
 115 .Fn fclose
 116 and
 117 .Fn fdclose
 118 functions may also fail and set
 119 .Va errno
 120 for any of the errors specified for
 121 .Xr fflush 3 .
 122 .Pp
 123 The
 124 .Fn fclose
 125 function may also fail and set errno for any of the errors specified for
 126 .Xr close 2 .
 127 .Sh NOTES
 128 The
 129 .Fn fclose
 130 and
 131 .Fn fdclose
 132 functions do not handle NULL arguments in the
 133 .Fa stream
 134 variable; this will result in a segmentation violation.
 135 This is intentional.
 136 It makes it easier to make sure programs written under
 137 .Fx
 138 are bug free.
 139 This behaviour is an implementation detail, and programs should not
 140 rely upon it.
 141 .Sh SEE ALSO
 142 .Xr close 2 ,
 143 .Xr fflush 3 ,
 144 .Xr fopen 3 ,
 145 .Xr setbuf 3
 146 .Sh STANDARDS
 147 The
 148 .Fn fclose
 149 function
 150 conforms to
 151 .St -isoC .
 152 .Sh HISTORY
 153 The
 154 .Fn fcloseall
 155 function first appeared in
 156 .Fx 7.0 .
 157 .Pp
 158 The
 159 .Fn fdclose
 160 function first appeared in
 161 .Fx 11.0 .