1.\" $OpenBSD: fopen.3,v 1.12 2001/02/12 16:08:43 aaron 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. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.Dd June 4, 1993 39.Dt FOPEN 3 40.Os 41.Sh NAME 42.Nm fopen , 43.Nm fdopen , 44.Nm freopen 45.Nd stream open functions 46.Sh SYNOPSIS 47.Fd #include <stdio.h> 48.Ft FILE * 49.Fn fopen "char *path" "char *mode" 50.Ft FILE * 51.Fn fdopen "int fildes" "char *mode" 52.Ft FILE * 53.Fn freopen "char *path" "char *mode" "FILE *stream" 54.Sh DESCRIPTION 55The 56.Fn fopen 57function opens the file whose name is the string pointed to by 58.Fa path 59and associates a stream with it. 60.Pp 61The argument 62.Fa mode 63points to a string beginning with one of the following 64sequences (additional characters may follow these sequences): 65.Bl -tag -width indent 66.It Dq Li r 67Open text file for reading. 68The stream is positioned at the beginning of the file. 69.It Dq Li r+ 70Open for reading and writing. 71The stream is positioned at the beginning of the file. 72.It Dq Li w 73Truncate file to zero length or create text file for writing. 74The stream is positioned at the beginning of the file. 75.It Dq Li w+ 76Open for reading and writing. 77The file is created if it does not exist, otherwise it is truncated. 78The stream is positioned at the beginning of the file. 79.It Dq Li a 80Open for writing. 81The file is created if it does not exist. 82The stream is positioned at the end of the file. 83.It Dq Li a+ 84Open for reading and writing. 85The file is created if it does not exist. 86The stream is positioned at the end of the file. 87.El 88.Pp 89The 90.Fa mode 91string can also include the letter ``b'' either as a third character or 92as a character between the characters in any of the two-character strings 93described above. 94This is strictly for compatibility with 95.St -ansiC 96and has no effect; the ``b'' is ignored. 97.Pp 98Any created files will have mode 99.Pf \\*q Dv S_IRUSR 100\&| 101.Dv S_IWUSR 102\&| 103.Dv S_IRGRP 104\&| 105.Dv S_IWGRP 106\&| 107.Dv S_IROTH 108\&| 109.Dv S_IWOTH Ns \\*q 110.Pq Li 0666 , 111as modified by the process' 112umask value (see 113.Xr umask 2 ) . 114.Pp 115Reads and writes cannot be arbitrarily intermixed on read/write streams. 116.Tn ANSI C 117requires that 118a file positioning function intervene between output and input, unless 119an input operation encounters end-of-file. 120.Pp 121The 122.Fn fdopen 123function associates a stream with the existing file descriptor 124.Fa fildes . 125The 126.Fa mode 127of the stream must be compatible with the mode of the file descriptor. 128If 129.Fn fdopen 130fails, the file descriptor 131.Fa fildes 132is not affected in any way. 133.Pp 134The 135.Fn freopen 136function opens the file whose name is the string pointed to by 137.Fa path 138and associates the stream pointed to by 139.Fa stream 140with it. 141The original stream (if it exists) is always closed, even if 142.Fn freopen 143fails. 144The 145.Fa mode 146argument is used just as in the 147.Xr fopen 148function. 149The primary use of the 150.Fn freopen 151function is to change the file associated with a standard text stream 152.Pf ( Em stderr , 153.Em stdin , 154or 155.Em stdout ) . 156.Sh RETURN VALUES 157Upon successful completion 158.Fn fopen , 159.Fn fdopen 160and 161.Fn freopen 162return a 163.Tn FILE 164pointer. 165Otherwise, 166.Dv NULL 167is returned and the global variable 168.Va errno 169is set to indicate the error. 170.Sh ERRORS 171.Bl -tag -width Er 172.It Bq Er EINVAL 173The 174.Fa mode 175provided to 176.Fn fopen , 177.Fn fdopen , 178or 179.Fn freopen 180was invalid. 181.El 182.Pp 183The 184.Fn fopen , 185.Fn fdopen 186and 187.Fn freopen 188functions may also fail and set 189.Va errno 190for any of the errors specified for the routine 191.Xr malloc 3 . 192.Pp 193The 194.Fn fopen 195function may also fail and set 196.Va errno 197for any of the errors specified for the routine 198.Xr open 2 . 199.Pp 200The 201.Fn fdopen 202function may also fail and set 203.Va errno 204for any of the errors specified for the routine 205.Xr fcntl 2 . 206.Pp 207The 208.Fn freopen 209function may also fail and set 210.Va errno 211for any of the errors specified for the routines 212.Xr open 2 , 213.Xr fclose 3 214and 215.Xr fflush 3 . 216.Sh SEE ALSO 217.Xr open 2 , 218.Xr fclose 3 , 219.Xr fseek 3 , 220.Xr funopen 3 221.Sh STANDARDS 222The 223.Fn fopen 224and 225.Fn freopen 226functions conform to 227.St -ansiC . 228The 229.Fn fdopen 230function conforms to 231.St -p1003.1-88 . 232.Sh CAVEATS 233Proper code using 234.Fn fdopen 235with error checking should 236.Xr close 2 237.Fa fildes 238in case of failure, and 239.Xr fclose 3 240the resulting FILE * in case of success. 241.Bd -literal 242 FILE *file; 243 int fd; 244 245 if ((file = fdopen(fd, "r")) != NULL) { 246 /* perform operations on the FILE * */ 247 fclose(file); 248 } else { 249 /* failure, report the error */ 250 close(fd); 251 } 252.Ed 253