1.\" Copyright (c) 1990, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Chris Torek and the American National Standards Committee X3, 6.\" on Information Processing Systems. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)fopen.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD$ 34.\" 35.Dd October 17, 2011 36.Dt FOPEN 3 37.Os 38.Sh NAME 39.Nm fopen , 40.Nm fdopen , 41.Nm freopen 42.Nd stream open functions 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdio.h 47.Ft FILE * 48.Fn fopen "const char * restrict path" "const char * restrict mode" 49.Ft FILE * 50.Fn fdopen "int fildes" "const char *mode" 51.Ft FILE * 52.Fn freopen "const char *path" "const char *mode" "FILE *stream" 53.Sh DESCRIPTION 54The 55.Fn fopen 56function 57opens 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 letters: 64.Bl -tag -width indent 65.It Dq Li r 66Open for reading. 67The stream is positioned at the beginning of the file. 68Fail if the file does not exist. 69.It Dq Li w 70Open for writing. 71The stream is positioned at the beginning of the file. 72Create the file if it does not exist. 73.It Dq Li a 74Open for writing. 75The stream is positioned at the end of the file. 76Subsequent writes to the file will always end up at the then current 77end of file, irrespective of any intervening 78.Xr fseek 3 79or similar. 80Create the file if it does not exist. 81.El 82.Pp 83An optional 84.Dq Li + 85following 86.Dq Li r , 87.Dq Li w , 88or 89.Dq Li a 90opens the file for both reading and writing. 91An optional 92.Dq Li x 93following 94.Dq Li w 95or 96.Dq Li w+ 97causes the 98.Fn fopen 99call to fail if the file already exists. 100.Pp 101The 102.Fa mode 103string can also include the letter 104.Dq Li b 105after either the 106.Dq Li + 107or the first letter. 108This is strictly for compatibility with 109.St -isoC 110and has no effect; the ``b'' is ignored. 111.Pp 112Any created files will have mode 113.Do Dv S_IRUSR 114\&| 115.Dv S_IWUSR 116\&| 117.Dv S_IRGRP 118\&| 119.Dv S_IWGRP 120\&| 121.Dv S_IROTH 122\&| 123.Dv S_IWOTH Dc 124.Pq Li 0666 , 125as modified by the process' 126umask value (see 127.Xr umask 2 ) . 128.Pp 129Reads and writes may be intermixed on read/write streams in any order, 130and do not require an intermediate seek as in previous versions of 131.Em stdio . 132This is not portable to other systems, however; 133.Tn ANSI C 134requires that 135a file positioning function intervene between output and input, unless 136an input operation encounters end-of-file. 137.Pp 138The 139.Fn fdopen 140function associates a stream with the existing file descriptor, 141.Fa fildes . 142The mode 143of the stream must be compatible with the mode of the file descriptor. 144The 145.Dq Li x 146mode option is ignored. 147When the stream is closed via 148.Xr fclose 3 , 149.Fa fildes 150is closed also. 151.Pp 152The 153.Fn freopen 154function 155opens the file whose name is the string pointed to by 156.Fa path 157and associates the stream pointed to by 158.Fa stream 159with it. 160The original stream (if it exists) is closed. 161The 162.Fa mode 163argument is used just as in the 164.Fn fopen 165function. 166.Pp 167If the 168.Fa path 169argument is 170.Dv NULL , 171.Fn freopen 172attempts to re-open the file associated with 173.Fa stream 174with a new mode. 175The new mode must be compatible with the mode that the stream was originally 176opened with: 177Streams open for reading can only be re-opened for reading, 178streams open for writing can only be re-opened for writing, 179and streams open for reading and writing can be re-opened in any mode. 180The 181.Dq Li x 182mode option is not meaningful in this context. 183.Pp 184The primary use of the 185.Fn freopen 186function 187is to change the file associated with a 188standard text stream 189.Dv ( stderr , stdin , 190or 191.Dv stdout ) . 192.Sh RETURN VALUES 193Upon successful completion 194.Fn fopen , 195.Fn fdopen 196and 197.Fn freopen 198return a 199.Tn FILE 200pointer. 201Otherwise, 202.Dv NULL 203is returned and the global variable 204.Va errno 205is set to indicate the error. 206.Sh ERRORS 207.Bl -tag -width Er 208.It Bq Er EINVAL 209The 210.Fa mode 211argument 212to 213.Fn fopen , 214.Fn fdopen , 215or 216.Fn freopen 217was invalid. 218.El 219.Pp 220The 221.Fn fopen , 222.Fn fdopen 223and 224.Fn freopen 225functions 226may also fail and set 227.Va errno 228for any of the errors specified for the routine 229.Xr malloc 3 . 230.Pp 231The 232.Fn fopen 233function 234may also fail and set 235.Va errno 236for any of the errors specified for the routine 237.Xr open 2 . 238.Pp 239The 240.Fn fdopen 241function 242may also fail and set 243.Va errno 244for any of the errors specified for the routine 245.Xr fcntl 2 . 246.Pp 247The 248.Fn freopen 249function 250may also fail and set 251.Va errno 252for any of the errors specified for the routines 253.Xr open 2 , 254.Xr fclose 3 255and 256.Xr fflush 3 . 257.Sh SEE ALSO 258.Xr open 2 , 259.Xr fclose 3 , 260.Xr fileno 3 , 261.Xr fseek 3 , 262.Xr funopen 3 263.Sh STANDARDS 264The 265.Fn fopen 266and 267.Fn freopen 268functions 269conform to 270.St -isoC . 271The 272.Fn fdopen 273function 274conforms to 275.St -p1003.1-88 . 276