1.\" $OpenBSD: fopen.3,v 1.32 2015/01/15 19:20:59 schwarze 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: January 15 2015 $ 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 the file specified by 105.Fa path 106already exists, 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. 144ANSI C requires that 145a file positioning function intervene between output and input, unless 146an input operation encounters end-of-file. 147.Pp 148The 149.Fn fdopen 150function associates a stream with the existing file descriptor 151.Fa fildes . 152The 153.Fa mode 154of the stream must be compatible with the mode of the file descriptor. 155The stream is positioned at the file offset of the file descriptor. 156If 157.Fn fdopen 158fails, the file descriptor 159.Fa fildes 160is not affected in any way. 161.Pp 162The 163.Fn freopen 164function opens the file whose name is the string pointed to by 165.Fa path 166and associates the stream pointed to by 167.Fa stream 168with it. 169The original stream (if it exists) is always closed, even if 170.Fn freopen 171fails. 172The 173.Fa mode 174argument is used just as in the 175.Fn fopen 176function. 177The primary use of the 178.Fn freopen 179function is to change the file associated with a standard text stream 180.Pf ( Em stderr , 181.Em stdin , 182or 183.Em stdout ) . 184.Sh RETURN VALUES 185Upon successful completion, 186.Fn fopen , 187.Fn fdopen , 188and 189.Fn freopen 190return a 191.Vt FILE 192pointer. 193Otherwise, 194.Dv NULL 195is returned and the global variable 196.Va errno 197is set to indicate the error. 198.Sh ERRORS 199.Bl -tag -width Er 200.It Bq Er EINVAL 201The 202.Fa mode 203provided to 204.Fn fopen , 205.Fn fdopen , 206or 207.Fn freopen 208was invalid. 209.El 210.Pp 211The 212.Fn fopen , 213.Fn fdopen 214and 215.Fn freopen 216functions may also fail and set 217.Va errno 218for any of the errors specified for the routine 219.Xr malloc 3 . 220.Pp 221The 222.Fn fopen 223function may also fail and set 224.Va errno 225for any of the errors specified for the routine 226.Xr open 2 . 227.Pp 228The 229.Fn fdopen 230function may also fail and set 231.Va errno 232for any of the errors specified for the routine 233.Xr fcntl 2 . 234.Pp 235The 236.Fn freopen 237function may also fail and set 238.Va errno 239for any of the errors specified for the routines 240.Xr open 2 , 241.Xr fclose 3 , 242and 243.Xr fflush 3 . 244.Sh SEE ALSO 245.Xr open 2 , 246.Xr fclose 3 , 247.Xr fseek 3 , 248.Xr funopen 3 249.Sh STANDARDS 250The 251.Fn fopen 252and 253.Fn freopen 254functions conform to 255.St -ansiC . 256The 257.Fn fdopen 258function conforms to 259.St -p1003.1-88 . 260.Sh HISTORY 261The 262.Fn fopen 263function first appeared in 264.At v1 . 265The 266.Fn fdopen 267and 268.Fn freopen 269functions first appeared in 270.At v7 . 271.Pp 272Opening a file for both reading and writing has been possible since 273.Bx 2 . 274.Pp 275Support for the 276.Dq e 277and 278.Dq x 279mode letters appeared in 280.Ox 5.7 . 281.Sh AUTHORS 282.An Dennis Ritchie 283originally implemented 284.Fn fopen 285in PDP-11 assembler. 286.An Keith Sklower 287first implemented read-write access. 288.Sh CAVEATS 289Proper code using 290.Fn fdopen 291with error checking should 292.Xr close 2 293.Fa fildes 294in case of failure, and 295.Xr fclose 3 296the resulting 297.Vt FILE * 298in case of success. 299.Bd -literal 300 FILE *file; 301 int fd; 302 303 if ((file = fdopen(fd, "r")) != NULL) { 304 /* perform operations on the FILE * */ 305 fclose(file); 306 } else { 307 /* failure, report the error */ 308 close(fd); 309 } 310.Ed 311