1.\" $NetBSD: fopen.3,v 1.36 2019/09/02 00:32:55 sevan Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Chris Torek and the American National Standards Committee X3, 8.\" on Information Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)fopen.3 8.1 (Berkeley) 6/4/93 35.\" 36.Dd September 2, 2019 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 * restrict path" "const char * restrict mode" "FILE * restrict 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, which may be followed by additional modifiers 66as indicated below: 67.Bl -tag -width 4n 68.It Dq Li a 69Append; open an existing or new file for writing in append mode. 70The file is created if it does not exist. 71.It Dq Li a+ 72Open for reading and writing in append mode. 73The file is created if it does not exist. 74.It Dq Li r 75Read; open an existing file for reading. 76.It Dq Li r+ 77Open an existing file for reading and writing. 78.It Dq Li w 79Write; open an empty file for writing. 80Truncate an existing file to zero length or create a new file. 81.It Dq Li w+ 82Open an empty file for reading and writing. 83Truncate file to zero length or create file. 84.El 85.Pp 86After one of those, the 87.Fa mode 88string can also include one or more of the following modifier letters: 89.Bl -tag -width 4n 90.It Sq b 91The letter 92.Sq b 93may appear either as a last character or as a character between the 94characters in any of the two-character strings described above. 95This is strictly for compatibility with 96.St -ansiC , 97where it means open in 98.Dq binary 99mode which is identical to text mode here, 100so has no effect; the 101.Sq b 102is ignored. 103.It Sq e 104The letter 105.Sq e 106in the mode string sets the close-on-exec 107.Pq Dv O_CLOEXEC 108flag of the file descriptor, which means that it will not be available 109after an 110.Xr exec 3 111system call. 112This is a non 113.St -ansiC 114extension. 115.It Sq f 116The letter 117.Sq f 118in the mode string restricts 119.Fn fopen 120to regular files; if the file opened is not a regular file, 121.Fn fopen 122will close it, and fail. 123This is a non 124.St -ansiC 125extension. 126.It Sq l 127The letter 128.Sq l 129in the mode string turns the don't-follow-symlinks 130.Pq Dv O_NOFOLLOW 131flag of the file descriptor, which means that if the last path component 132is a symbolic link, it will not be followed. 133This is a non 134.St -ansiC 135extension. 136.It Sq x 137The letter 138.Sq x 139in the mode turns on exclusive open mode to the file 140.Pq Dv O_EXCL 141which means that the file will not be created if it already exists. 142In that case 143.Fn fopen 144will fail. 145.El 146.Pp 147Any created files will have mode 148.Pf \*q Dv S_IRUSR 149\&| 150.Dv S_IWUSR 151\&| 152.Dv S_IRGRP 153\&| 154.Dv S_IWGRP 155\&| 156.Dv S_IROTH 157\&| 158.Dv S_IWOTH Ns \*q 159.Pq Li 0666 , 160as modified by the process' 161.Xr umask 2 162value. 163.Pp 164Opening a file with append mode causes all subsequent writes to it 165to be forced to the then current end of file, regardless of intervening 166repositioning of the stream. 167.Pp 168The 169.Fn fopen 170and 171.Fn freopen 172functions initially position the stream at the start of the file 173unless the file is opened with append mode, 174in which case the stream is initially positioned at the end of the file. 175.\" PR 6072 claims this paragraph is not correct. 176.\" .Pp 177.\" Reads and writes may be intermixed on read/write streams in any order, 178.\" and do not require an intermediate seek as in previous versions of 179.\" .Em stdio . 180.\" This is not portable to other systems, however; 181.\" .Tn ANSI C 182.\" requires that 183.\" a file positioning function intervene between output and input, unless 184.\" an input operation encounters end-of-file. 185.Pp 186The 187.Fn fdopen 188function associates a stream with the existing file descriptor, 189.Fa fildes . 190The 191.Fa mode 192of the stream must be compatible with the mode of the file descriptor. 193The stream is positioned at the file offset of the file descriptor. 194.Pp 195The 196.Fn freopen 197function 198opens the file whose name is the string pointed to by 199.Fa path 200and associates the stream pointed to by 201.Fa stream 202with it. 203The original stream (if it exists) is closed. 204The 205.Fa mode 206argument is used just as in the 207.Fn fopen 208function. 209The primary use of the 210.Fn freopen 211function 212is to change the file associated with a 213standard text stream 214.Pf ( Em stderr , 215.Em stdin , 216or 217.Em stdout ) . 218.Pp 219Input and output against the opened stream will be fully buffered, unless 220it refers to an interactive terminal device, or a different kind of buffering 221is specified in the environment. 222See 223.Xr setvbuf 3 224for additional details. 225.Sh RETURN VALUES 226Upon successful completion 227.Fn fopen , 228.Fn fdopen 229and 230.Fn freopen 231return a FILE pointer. 232Otherwise, 233.Dv NULL 234is returned and the global variable 235.Va errno 236is set to indicate the error. 237.Sh ERRORS 238The functions may fail if: 239.Bl -tag -width Er 240.It Bq Er EFTYPE 241The file is not a regular file and the character ``f'' is specified 242in the mode. 243.It Bq Er EINVAL 244The specified 245.Fa mode 246was invalid. 247.El 248.Pp 249The 250.Fn fopen , 251.Fn fdopen 252and 253.Fn freopen 254functions 255may also fail and set 256.Va errno 257for any of the errors specified for the routine 258.Xr malloc 3 . 259.Pp 260The 261.Fn fopen 262function 263may also fail and set 264.Va errno 265for any of the errors specified for the routine 266.Xr open 2 . 267.Pp 268The 269.Fn fdopen 270function 271may also fail and set 272.Va errno 273for any of the errors specified for the routine 274.Xr fcntl 2 . 275.Pp 276The 277.Fn freopen 278function 279may also fail and set 280.Va errno 281for any of the errors specified for the routines 282.Xr open 2 , 283.Xr fclose 3 284and 285.Xr fflush 3 . 286.Sh SEE ALSO 287.Xr open 2 , 288.Xr fclose 3 , 289.Xr fileno 3 , 290.Xr fseek 3 , 291.Xr funopen 3 292.Sh STANDARDS 293The 294.Fn fopen 295and 296.Fn freopen 297functions conform to 298.St -ansiC . 299All three functions are specified in 300.St -p1003.1-2008 . 301.Sh HISTORY 302An 303.Fn fopen 304function appeared in 305.At v1 . 306.Sh CAVEATS 307Proper code using 308.Fn fdopen 309with error checking should 310.Xr close 2 311.Fa fildes 312in case of failure, and 313.Xr fclose 3 314the resulting FILE * in case of success. 315.Bd -literal 316 FILE *file; 317 int fd; 318 319 if ((file = fdopen(fd, "r")) != NULL) { 320 /* perform operations on the FILE * */ 321 fclose(file); 322 } else { 323 /* failure, report the error */ 324 close(fd); 325 } 326.Ed 327