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