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