1.\" $OpenBSD: fopen.3,v 1.30 2014/11/15 14:41:02 bentley 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.Dd $Mdocdate: November 15 2014 $ 35.Dt FOPEN 3 36.Os 37.Sh NAME 38.Nm fopen , 39.Nm fdopen , 40.Nm freopen 41.Nd stream open functions 42.Sh SYNOPSIS 43.In stdio.h 44.Ft FILE * 45.Fn fopen "const char *path" "const char *mode" 46.Ft FILE * 47.Fn fdopen "int fildes" "const char *mode" 48.Ft FILE * 49.Fn freopen "const char *path" "const char *mode" "FILE *stream" 50.Sh DESCRIPTION 51The 52.Fn fopen 53function opens the file whose name is the string pointed to by 54.Fa path 55and associates a stream with it. 56.Pp 57The argument 58.Fa mode 59points to a string beginning with one of the following 60sequences (additional characters may follow these sequences): 61.Bl -tag -width indent 62.It Do Li r Dc or Do Li rb Dc 63Open file for reading. 64.It Do Li r+ Dc or Do Li rb+ Dc or Do Li r+b Dc 65Open for reading and writing. 66.It Do Li w Dc or Do Li wb Dc 67Open for writing. 68The file is created if it does not exist, otherwise it is truncated. 69.It Do Li w+ Dc or Do Li wb+ Dc or Do Li w+b Dc 70Open for reading and writing. 71The file is created if it does not exist, otherwise it is truncated. 72.It Do Li a Dc or Do Li ab Dc 73Open for writing. 74The file is created if it does not exist. 75.It Do Li a+ Dc or Do Li ab+ Dc or Do Li a+b Dc 76Open for reading and writing. 77The file is created if it does not exist. 78.El 79.Pp 80The letter 81.Dq b 82in the 83.Fa mode 84strings above is strictly for compatibility with 85.St -ansiC 86and has no effect; the 87.Dq b 88is ignored. 89.Pp 90After any of the above prefixes, the 91.Fa mode 92string can also include zero or more of the following: 93.Bl -tag -width indent 94.It Dq Li e 95The close-on-exec flag is set on the underlying file descriptor of the new 96.Vt FILE . 97.It Dq Li x 98If the 99.Fa mode 100string starts with 101.Dq w 102or 103.Dq a 104then the function shall fail if file 105.Fa path 106already exist, as if the 107.Dv O_EXCL 108flag was passed to the 109.Xr open 2 110function. 111It has no effect if used with 112.Fn fdopen 113or the 114.Fa mode 115string begins with 116.Dq r . 117.El 118.Pp 119The 120.Fn fopen 121and 122.Fn freopen 123functions initially position the stream at the start of the file 124unless the file is opened in append mode 125.Po 126.Sq a 127or 128.Sq a+ 129.Pc , 130in which case the stream is initially positioned at the end of the file. 131.Pp 132Opening a file in append mode causes all subsequent writes to it 133to be forced to the current end-of-file, regardless of intervening 134repositioning of the stream. 135.Pp 136Any created files will have mode 137.Qq Dv S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH 138.Pq Li 0666 , 139as modified by the process' 140umask value (see 141.Xr umask 2 ) . 142.Pp 143Reads and writes cannot be arbitrarily intermixed on read/write streams. 144.Tn ANSI C 145requires that 146a file positioning function intervene between output and input, unless 147an input operation encounters end-of-file. 148.Pp 149The 150.Fn fdopen 151function associates a stream with the existing file descriptor 152.Fa fildes . 153The 154.Fa mode 155of the stream must be compatible with the mode of the file descriptor. 156The stream is positioned at the file offset of the file descriptor. 157If 158.Fn fdopen 159fails, the file descriptor 160.Fa fildes 161is not affected in any way. 162.Pp 163The 164.Fn freopen 165function opens the file whose name is the string pointed to by 166.Fa path 167and associates the stream pointed to by 168.Fa stream 169with it. 170The original stream (if it exists) is always closed, even if 171.Fn freopen 172fails. 173The 174.Fa mode 175argument is used just as in the 176.Fn fopen 177function. 178The primary use of the 179.Fn freopen 180function is to change the file associated with a standard text stream 181.Pf ( Em stderr , 182.Em stdin , 183or 184.Em stdout ) . 185.Sh RETURN VALUES 186Upon successful completion, 187.Fn fopen , 188.Fn fdopen , 189and 190.Fn freopen 191return a 192.Vt FILE 193pointer. 194Otherwise, 195.Dv NULL 196is returned and the global variable 197.Va errno 198is set to indicate the error. 199.Sh ERRORS 200.Bl -tag -width Er 201.It Bq Er EINVAL 202The 203.Fa mode 204provided to 205.Fn fopen , 206.Fn fdopen , 207or 208.Fn freopen 209was invalid. 210.El 211.Pp 212The 213.Fn fopen , 214.Fn fdopen 215and 216.Fn freopen 217functions may also fail and set 218.Va errno 219for any of the errors specified for the routine 220.Xr malloc 3 . 221.Pp 222The 223.Fn fopen 224function may also fail and set 225.Va errno 226for any of the errors specified for the routine 227.Xr open 2 . 228.Pp 229The 230.Fn fdopen 231function may also fail and set 232.Va errno 233for any of the errors specified for the routine 234.Xr fcntl 2 . 235.Pp 236The 237.Fn freopen 238function may also fail and set 239.Va errno 240for any of the errors specified for the routines 241.Xr open 2 , 242.Xr fclose 3 , 243and 244.Xr fflush 3 . 245.Sh SEE ALSO 246.Xr open 2 , 247.Xr fclose 3 , 248.Xr fseek 3 , 249.Xr funopen 3 250.Sh STANDARDS 251The 252.Fn fopen 253and 254.Fn freopen 255functions conform to 256.St -ansiC . 257The 258.Fn fdopen 259function conforms to 260.St -p1003.1-88 . 261.Sh HISTORY 262The 263.Fn fopen 264function first appeared in 265.At v1 . 266The 267.Fn fdopen 268and 269.Fn freopen 270functions first appeared in 271.At v7 . 272.Pp 273Opening a file for both reading and writing has been possible since 274.Bx 2 . 275.Pp 276Support for the 277.Dq e 278and 279.Dq x 280mode letters appeared in 281.Ox 5.7 . 282.Sh AUTHORS 283.An Dennis Ritchie 284originally implemented 285.Fn fopen 286in PDP-11 assembler. 287.An Keith Sklower 288first implemented read-write access. 289.Sh CAVEATS 290Proper code using 291.Fn fdopen 292with error checking should 293.Xr close 2 294.Fa fildes 295in case of failure, and 296.Xr fclose 3 297the resulting 298.Vt FILE * 299in case of success. 300.Bd -literal 301 FILE *file; 302 int fd; 303 304 if ((file = fdopen(fd, "r")) != NULL) { 305 /* perform operations on the FILE * */ 306 fclose(file); 307 } else { 308 /* failure, report the error */ 309 close(fd); 310 } 311.Ed 312