1.\" $OpenBSD: fopen.3,v 1.25 2012/01/22 13:02:45 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 22 2012 $ 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.Fd #include <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 Dq Li r 63Open file for reading. 64.It Dq Li r+ 65Open for reading and writing. 66.It Dq Li w 67Truncate file to zero length or create text file for writing. 68.It Dq Li w+ 69Open for reading and writing. 70The file is created if it does not exist, otherwise it is truncated. 71.It Dq Li a 72Open for writing. 73The file is created if it does not exist. 74.It Dq Li a+ 75Open for reading and writing. 76The file is created if it does not exist. 77.El 78.Pp 79The 80.Fa mode 81string can also include the letter ``b'' either as the last character or 82as a character between the characters in any of the two-character strings 83described above. 84This is strictly for compatibility with 85.St -ansiC 86and has no effect; the ``b'' is ignored. 87.Pp 88The 89.Fn fopen 90and 91.Fn freopen 92functions initially position the stream at the start of the file 93unless the file is opened in append mode 94.Po 95.Sq a 96or 97.Sq a+ 98.Pc , 99in which case the stream is initially positioned at the end of the file. 100.Pp 101Opening a file in append mode causes all subsequent writes to it 102to be forced to the current end-of-file, regardless of intervening 103repositioning of the stream. 104.Pp 105Any created files will have mode 106.Qq Dv S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH 107.Pq Li 0666 , 108as modified by the process' 109umask value (see 110.Xr umask 2 ) . 111.Pp 112Reads and writes cannot be arbitrarily intermixed on read/write streams. 113.Tn ANSI C 114requires that 115a file positioning function intervene between output and input, unless 116an input operation encounters end-of-file. 117.Pp 118The 119.Fn fdopen 120function associates a stream with the existing file descriptor 121.Fa fildes . 122The 123.Fa mode 124of the stream must be compatible with the mode of the file descriptor. 125The stream is positioned at the file offset of the file descriptor. 126If 127.Fn fdopen 128fails, the file descriptor 129.Fa fildes 130is not affected in any way. 131.Pp 132The 133.Fn freopen 134function opens the file whose name is the string pointed to by 135.Fa path 136and associates the stream pointed to by 137.Fa stream 138with it. 139The original stream (if it exists) is always closed, even if 140.Fn freopen 141fails. 142The 143.Fa mode 144argument is used just as in the 145.Fn fopen 146function. 147The primary use of the 148.Fn freopen 149function is to change the file associated with a standard text stream 150.Pf ( Em stderr , 151.Em stdin , 152or 153.Em stdout ) . 154.Sh RETURN VALUES 155Upon successful completion, 156.Fn fopen , 157.Fn fdopen , 158and 159.Fn freopen 160return a 161.Vt FILE 162pointer. 163Otherwise, 164.Dv NULL 165is returned and the global variable 166.Va errno 167is set to indicate the error. 168.Sh ERRORS 169.Bl -tag -width Er 170.It Bq Er EINVAL 171The 172.Fa mode 173provided to 174.Fn fopen , 175.Fn fdopen , 176or 177.Fn freopen 178was invalid. 179.El 180.Pp 181The 182.Fn fopen , 183.Fn fdopen 184and 185.Fn freopen 186functions may also fail and set 187.Va errno 188for any of the errors specified for the routine 189.Xr malloc 3 . 190.Pp 191The 192.Fn fopen 193function may also fail and set 194.Va errno 195for any of the errors specified for the routine 196.Xr open 2 . 197.Pp 198The 199.Fn fdopen 200function may also fail and set 201.Va errno 202for any of the errors specified for the routine 203.Xr fcntl 2 . 204.Pp 205The 206.Fn freopen 207function may also fail and set 208.Va errno 209for any of the errors specified for the routines 210.Xr open 2 , 211.Xr fclose 3 , 212and 213.Xr fflush 3 . 214.Sh SEE ALSO 215.Xr open 2 , 216.Xr fclose 3 , 217.Xr fseek 3 , 218.Xr funopen 3 219.Sh STANDARDS 220The 221.Fn fopen 222and 223.Fn freopen 224functions conform to 225.St -ansiC . 226The 227.Fn fdopen 228function conforms to 229.St -p1003.1-88 . 230.Sh HISTORY 231The 232.Fn fopen 233function first appeared in 234.At v1 . 235The 236.Fn fdopen 237and 238.Fn freopen 239functions first appeared in 240.At v7 . 241.Pp 242Opening a file for both reading and writing has been possible since 243.Bx 2 . 244.Sh AUTHORS 245.An Dennis Ritchie 246originally implemented 247.Fn fopen 248in PDP-11 assembler. 249.An Keith Sklower 250first implemented read-write access. 251.Sh CAVEATS 252Proper code using 253.Fn fdopen 254with error checking should 255.Xr close 2 256.Fa fildes 257in case of failure, and 258.Xr fclose 3 259the resulting 260.Vt FILE * 261in case of success. 262.Bd -literal 263 FILE *file; 264 int fd; 265 266 if ((file = fdopen(fd, "r")) != NULL) { 267 /* perform operations on the FILE * */ 268 fclose(file); 269 } else { 270 /* failure, report the error */ 271 close(fd); 272 } 273.Ed 274