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.\" 4. 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.\" @(#)fopen.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD$ 34.\" 35.Dd November 30, 2012 36.Dt FOPEN 3 37.Os 38.Sh NAME 39.Nm fopen , 40.Nm fdopen , 41.Nm freopen 42.Nd stream open functions 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdio.h 47.Ft FILE * 48.Fn fopen "const char * restrict path" "const char * restrict mode" 49.Ft FILE * 50.Fn fdopen "int fildes" "const char *mode" 51.Ft FILE * 52.Fn freopen "const char *path" "const char *mode" "FILE *stream" 53.Sh DESCRIPTION 54The 55.Fn fopen 56function 57opens the file whose name is the string pointed to by 58.Fa path 59and associates a stream with it. 60.Pp 61The argument 62.Fa mode 63points to a string beginning with one of the following letters: 64.Bl -tag -width indent 65.It Dq Li r 66Open for reading. 67The stream is positioned at the beginning of the file. 68Fail if the file does not exist. 69.It Dq Li w 70Open for writing. 71The stream is positioned at the beginning of the file. 72Create the file if it does not exist. 73.It Dq Li a 74Open for writing. 75The stream is positioned at the end of the file. 76Subsequent writes to the file will always end up at the then current 77end of file, irrespective of any intervening 78.Xr fseek 3 79or similar. 80Create the file if it does not exist. 81.El 82.Pp 83An optional 84.Dq Li + 85following 86.Dq Li r , 87.Dq Li w , 88or 89.Dq Li a 90opens the file for both reading and writing. 91An optional 92.Dq Li x 93following 94.Dq Li w 95or 96.Dq Li w+ 97causes the 98.Fn fopen 99call to fail if the file already exists. 100An optional 101.Dq Li e 102following the above 103causes the 104.Fn fopen 105call to set the 106.Dv FD_CLOEXEC 107flag on the underlying file descriptor. 108.Pp 109The 110.Fa mode 111string can also include the letter 112.Dq Li b 113after either the 114.Dq Li + 115or the first letter. 116This is strictly for compatibility with 117.St -isoC 118and has no effect; the ``b'' is ignored. 119.Pp 120Any created files will have mode 121.Do Dv S_IRUSR 122\&| 123.Dv S_IWUSR 124\&| 125.Dv S_IRGRP 126\&| 127.Dv S_IWGRP 128\&| 129.Dv S_IROTH 130\&| 131.Dv S_IWOTH Dc 132.Pq Li 0666 , 133as modified by the process' 134umask value (see 135.Xr umask 2 ) . 136.Pp 137Reads and writes may be intermixed on read/write streams in any order, 138and do not require an intermediate seek as in previous versions of 139.Em stdio . 140This is not portable to other systems, however; 141.Tn ANSI C 142requires that 143a file positioning function intervene between output and input, unless 144an input operation encounters end-of-file. 145.Pp 146The 147.Fn fdopen 148function associates a stream with the existing file descriptor, 149.Fa fildes . 150The mode 151of the stream must be compatible with the mode of the file descriptor. 152The 153.Dq Li x 154mode option is ignored. 155If the 156.Dq Li e 157mode option is present, the 158.Dv FD_CLOEXEC 159flag is set, otherwise it remains unchanged. 160When the stream is closed via 161.Xr fclose 3 , 162.Fa fildes 163is closed also. 164.Pp 165The 166.Fn freopen 167function 168opens the file whose name is the string pointed to by 169.Fa path 170and associates the stream pointed to by 171.Fa stream 172with it. 173The original stream (if it exists) is closed. 174The 175.Fa mode 176argument is used just as in the 177.Fn fopen 178function. 179.Pp 180If the 181.Fa path 182argument is 183.Dv NULL , 184.Fn freopen 185attempts to re-open the file associated with 186.Fa stream 187with a new mode. 188The new mode must be compatible with the mode that the stream was originally 189opened with: 190Streams open for reading can only be re-opened for reading, 191streams open for writing can only be re-opened for writing, 192and streams open for reading and writing can be re-opened in any mode. 193The 194.Dq Li x 195mode option is not meaningful in this context. 196.Pp 197The primary use of the 198.Fn freopen 199function 200is to change the file associated with a 201standard text stream 202.Dv ( stderr , stdin , 203or 204.Dv stdout ) . 205.Sh RETURN VALUES 206Upon successful completion 207.Fn fopen , 208.Fn fdopen 209and 210.Fn freopen 211return a 212.Tn FILE 213pointer. 214Otherwise, 215.Dv NULL 216is returned and the global variable 217.Va errno 218is set to indicate the error. 219.Sh ERRORS 220.Bl -tag -width Er 221.It Bq Er EINVAL 222The 223.Fa mode 224argument 225to 226.Fn fopen , 227.Fn fdopen , 228or 229.Fn freopen 230was invalid. 231.El 232.Pp 233The 234.Fn fopen , 235.Fn fdopen 236and 237.Fn freopen 238functions 239may also fail and set 240.Va errno 241for any of the errors specified for the routine 242.Xr malloc 3 . 243.Pp 244The 245.Fn fopen 246function 247may also fail and set 248.Va errno 249for any of the errors specified for the routine 250.Xr open 2 . 251.Pp 252The 253.Fn fdopen 254function 255may also fail and set 256.Va errno 257for any of the errors specified for the routine 258.Xr fcntl 2 . 259.Pp 260The 261.Fn freopen 262function 263may also fail and set 264.Va errno 265for any of the errors specified for the routines 266.Xr open 2 , 267.Xr fclose 3 268and 269.Xr fflush 3 . 270.Sh SEE ALSO 271.Xr open 2 , 272.Xr fclose 3 , 273.Xr fileno 3 , 274.Xr fseek 3 , 275.Xr funopen 3 276.Sh STANDARDS 277The 278.Fn fopen 279and 280.Fn freopen 281functions 282conform to 283.St -isoC , 284with the exception of the 285.Dq Li x 286mode option which conforms to 287.St -isoC-2011 . 288The 289.Fn fdopen 290function 291conforms to 292.St -p1003.1-88 . 293The 294.Dq Li e 295mode option does not conform to any standard 296but is also supported by glibc. 297