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