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 * restrict path" "const char * restrict 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 mode 141of the stream must be compatible with the mode of the file descriptor. 142When the stream is closed via 143.Xr fclose 3 , 144.Fa fildes 145is closed also. 146.Pp 147The 148.Fn freopen 149function 150opens the file whose name is the string pointed to by 151.Fa path 152and associates the stream pointed to by 153.Fa stream 154with it. 155The original stream (if it exists) is closed. 156The 157.Fa mode 158argument is used just as in the 159.Fn fopen 160function. 161The primary use of the 162.Fn freopen 163function 164is to change the file associated with a 165standard text stream 166.Dv ( stderr , stdin , 167or 168.Dv stdout ) . 169.Sh RETURN VALUES 170Upon successful completion 171.Fn fopen , 172.Fn fdopen 173and 174.Fn freopen 175return a 176.Tn FILE 177pointer. 178Otherwise, 179.Dv NULL 180is returned and the global variable 181.Va errno 182is set to indicate the error. 183.Sh ERRORS 184.Bl -tag -width Er 185.It Bq Er EINVAL 186The 187.Fa mode 188argument 189to 190.Fn fopen , 191.Fn fdopen , 192or 193.Fn freopen 194was invalid. 195.El 196.Pp 197The 198.Fn fopen , 199.Fn fdopen 200and 201.Fn freopen 202functions 203may also fail and set 204.Va errno 205for any of the errors specified for the routine 206.Xr malloc 3 . 207.Pp 208The 209.Fn fopen 210function 211may also fail and set 212.Va errno 213for any of the errors specified for the routine 214.Xr open 2 . 215.Pp 216The 217.Fn fdopen 218function 219may also fail and set 220.Va errno 221for any of the errors specified for the routine 222.Xr fcntl 2 . 223.Pp 224The 225.Fn freopen 226function 227may also fail and set 228.Va errno 229for any of the errors specified for the routines 230.Xr open 2 , 231.Xr fclose 3 232and 233.Xr fflush 3 . 234.Sh SEE ALSO 235.Xr open 2 , 236.Xr fclose 3 , 237.Xr fileno 3 , 238.Xr fseek 3 , 239.Xr funopen 3 240.Sh STANDARDS 241The 242.Fn fopen 243and 244.Fn freopen 245functions 246conform to 247.St -isoC . 248The 249.Fn fdopen 250function 251conforms to 252.St -p1003.1-88 . 253