1.\" $OpenBSD: fopen.3,v 1.20 2007/05/31 19:19:31 jmc 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: May 31 2007 $ 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 a third 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.Pf \\*q Dv S_IRUSR 107\&| 108.Dv S_IWUSR 109\&| 110.Dv S_IRGRP 111\&| 112.Dv S_IWGRP 113\&| 114.Dv S_IROTH 115\&| 116.Dv S_IWOTH Ns \\*q 117.Pq Li 0666 , 118as modified by the process' 119umask value (see 120.Xr umask 2 ) . 121.Pp 122Reads and writes cannot be arbitrarily intermixed on read/write streams. 123.Tn ANSI C 124requires that 125a file positioning function intervene between output and input, unless 126an input operation encounters end-of-file. 127.Pp 128The 129.Fn fdopen 130function associates a stream with the existing file descriptor 131.Fa fildes . 132The 133.Fa mode 134of the stream must be compatible with the mode of the file descriptor. 135The stream is positioned at the file offset of the file descriptor. 136If 137.Fn fdopen 138fails, the file descriptor 139.Fa fildes 140is not affected in any way. 141.Pp 142The 143.Fn freopen 144function opens the file whose name is the string pointed to by 145.Fa path 146and associates the stream pointed to by 147.Fa stream 148with it. 149The original stream (if it exists) is always closed, even if 150.Fn freopen 151fails. 152The 153.Fa mode 154argument is used just as in the 155.Fn fopen 156function. 157The primary use of the 158.Fn freopen 159function is to change the file associated with a standard text stream 160.Pf ( Em stderr , 161.Em stdin , 162or 163.Em stdout ) . 164.Sh RETURN VALUES 165Upon successful completion, 166.Fn fopen , 167.Fn fdopen , 168and 169.Fn freopen 170return a 171.Vt FILE 172pointer. 173Otherwise, 174.Dv NULL 175is returned and the global variable 176.Va errno 177is set to indicate the error. 178.Sh ERRORS 179.Bl -tag -width Er 180.It Bq Er EINVAL 181The 182.Fa mode 183provided to 184.Fn fopen , 185.Fn fdopen , 186or 187.Fn freopen 188was invalid. 189.El 190.Pp 191The 192.Fn fopen , 193.Fn fdopen 194and 195.Fn freopen 196functions may also fail and set 197.Va errno 198for any of the errors specified for the routine 199.Xr malloc 3 . 200.Pp 201The 202.Fn fopen 203function may also fail and set 204.Va errno 205for any of the errors specified for the routine 206.Xr open 2 . 207.Pp 208The 209.Fn fdopen 210function may also fail and set 211.Va errno 212for any of the errors specified for the routine 213.Xr fcntl 2 . 214.Pp 215The 216.Fn freopen 217function may also fail and set 218.Va errno 219for any of the errors specified for the routines 220.Xr open 2 , 221.Xr fclose 3 , 222and 223.Xr fflush 3 . 224.Sh SEE ALSO 225.Xr open 2 , 226.Xr fclose 3 , 227.Xr fseek 3 , 228.Xr funopen 3 229.Sh STANDARDS 230The 231.Fn fopen 232and 233.Fn freopen 234functions conform to 235.St -ansiC . 236The 237.Fn fdopen 238function conforms to 239.St -p1003.1-88 . 240.Sh CAVEATS 241Proper code using 242.Fn fdopen 243with error checking should 244.Xr close 2 245.Fa fildes 246in case of failure, and 247.Xr fclose 3 248the resulting 249.Vt FILE * 250in case of success. 251.Bd -literal 252 FILE *file; 253 int fd; 254 255 if ((file = fdopen(fd, "r")) != NULL) { 256 /* perform operations on the FILE * */ 257 fclose(file); 258 } else { 259 /* failure, report the error */ 260 close(fd); 261 } 262.Ed 263