1.\" $NetBSD: fopen.3,v 1.28 2012/07/02 20:02:43 wiz 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 July 18, 2011 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 (Additional characters may follow these sequences.): 66.Bl -tag -width 4n 67.It Dq Li a 68Append; open for writing. 69The file is created if it does not exist. 70.It Dq Li a+ 71Append; open for reading and writing. 72The file is created if it does not exist. 73.It Dq Li r 74Open for reading. 75.It Dq Li r+ 76Open for reading and writing. 77.It Dq Li w 78Open for writing. 79Truncate file to zero length or create file. 80.It Dq Li w+ 81Open for reading and writing. 82Truncate file to zero length or create file. 83.El 84.Pp 85Additionally, the 86.Fa mode 87string can also include one of the following letters: 88.Bl -tag -width 4n 89.It Sq b 90The letter 91.Sq b 92may appear either as a last character or as a character between the 93characters in any of the two-character strings described above. 94This is strictly for compatibility with 95.St -ansiC 96and has no effect; the 97.Sq b 98is ignored. 99.It Sq e 100The letter 101.Sq e 102in the mode string sets the close-on-exec flag in the file descriptors of 103the newly opened file files; if the operation fails, 104.Fn fopen 105will fail. 106This is a non 107.St -ansiC 108extension. 109.It Sq f 110The letter 111.Sq f 112in the mode string restricts 113.Fn fopen 114to regular files; if the file opened is not a regular file, 115.Fn fopen 116will fail. 117This is a non 118.St -ansiC 119extension. 120.El 121.Pp 122Any created files will have mode 123.Pf \*q Dv S_IRUSR 124\&| 125.Dv S_IWUSR 126\&| 127.Dv S_IRGRP 128\&| 129.Dv S_IWGRP 130\&| 131.Dv S_IROTH 132\&| 133.Dv S_IWOTH Ns \*q 134.Pq Li 0666 , 135as modified by the process' 136.Xr umask 2 137value. 138.Pp 139Opening a file with append mode causes all subsequent writes to it 140to be forced to the then current end of file, regardless of intervening 141repositioning of the stream. 142.Pp 143The 144.Fn fopen 145and 146.Fn freopen 147functions initially position the stream at the start of the file 148unless the file is opened with append mode, 149in which case the stream is initially positioned at the end of the file. 150.\" PR 6072 claims this paragraph is not correct. 151.\" .Pp 152.\" Reads and writes may be intermixed on read/write streams in any order, 153.\" and do not require an intermediate seek as in previous versions of 154.\" .Em stdio . 155.\" This is not portable to other systems, however; 156.\" .Tn ANSI C 157.\" requires that 158.\" a file positioning function intervene between output and input, unless 159.\" an input operation encounters end-of-file. 160.Pp 161The 162.Fn fdopen 163function associates a stream with the existing file descriptor, 164.Fa fildes . 165The 166.Fa mode 167of the stream must be compatible with the mode of the file descriptor. 168The stream is positioned at the file offset of the file descriptor. 169.Pp 170The 171.Fn freopen 172function 173opens the file whose name is the string pointed to by 174.Fa path 175and associates the stream pointed to by 176.Fa stream 177with it. 178The original stream (if it exists) is closed. 179The 180.Fa mode 181argument is used just as in the 182.Fn fopen 183function. 184The primary use of the 185.Fn freopen 186function 187is to change the file associated with a 188standard text stream 189.Pf ( Em stderr , 190.Em stdin , 191or 192.Em stdout ) . 193.Sh RETURN VALUES 194Upon successful completion 195.Fn fopen , 196.Fn fdopen 197and 198.Fn freopen 199return a 200.Tn FILE 201pointer. 202Otherwise, 203.Dv NULL 204is returned and the global variable 205.Va errno 206is set to indicate the error. 207.Sh ERRORS 208The functions may fail if: 209.Bl -tag -width Er 210.It Bq Er EFTYPE 211The file is not a regular file and the character ``f'' is specified 212in the mode. 213.It Bq Er EINVAL 214The specified 215.Fa mode 216was invalid. 217.El 218.Pp 219The 220.Fn fopen , 221.Fn fdopen 222and 223.Fn freopen 224functions 225may also fail and set 226.Va errno 227for any of the errors specified for the routine 228.Xr malloc 3 . 229.Pp 230The 231.Fn fopen 232function 233may also fail and set 234.Va errno 235for any of the errors specified for the routine 236.Xr open 2 . 237.Pp 238The 239.Fn fdopen 240function 241may also fail and set 242.Va errno 243for any of the errors specified for the routine 244.Xr fcntl 2 . 245.Pp 246The 247.Fn freopen 248function 249may also fail and set 250.Va errno 251for any of the errors specified for the routines 252.Xr open 2 , 253.Xr fclose 3 254and 255.Xr fflush 3 . 256.Sh SEE ALSO 257.Xr open 2 , 258.Xr fclose 3 , 259.Xr fileno 3 , 260.Xr fseek 3 , 261.Xr funopen 3 262.Sh STANDARDS 263The 264.Fn fopen 265and 266.Fn freopen 267functions conform to 268.St -ansiC . 269All three functions are specified in 270.St -p1003.1-2008 . 271.Sh CAVEATS 272Proper code using 273.Fn fdopen 274with error checking should 275.Xr close 2 276.Fa fildes 277in case of failure, and 278.Xr fclose 3 279the resulting FILE * in case of success. 280.Bd -literal 281 FILE *file; 282 int fd; 283 284 if ((file = fdopen(fd, "r")) != NULL) { 285 /* perform operations on the FILE * */ 286 fclose(file); 287 } else { 288 /* failure, report the error */ 289 close(fd); 290 } 291.Ed 292