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 January 26, 2003 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. 161.Pp 162If the 163.Fa path 164argument is 165.Dv NULL , 166.Fn freopen 167attempts to re-open the file associated with 168.Fa stream 169with a new mode. 170The new mode must be compatible with the mode that the stream was originally 171opened with: 172.Bl -bullet -offset indent 173.It 174Streams originally opened with mode 175.Dq Li r 176can only be reopened with that same mode. 177.It 178Streams originally opened with mode 179.Dq Li a 180can be reopened with the same mode, or mode 181.Dq Li w . 182.It 183Streams originally opened with mode 184.Dq Li w 185can be reopened with the same mode, or mode 186.Dq Li a . 187.It 188Streams originally opened with mode 189.Dq Li r+ , 190.Dq Li w+ , 191or 192.Dq Li a+ 193can be reopened with any mode. 194.El 195.Pp 196The primary use of the 197.Fn freopen 198function 199is to change the file associated with a 200standard text stream 201.Dv ( stderr , stdin , 202or 203.Dv stdout ) . 204.Sh RETURN VALUES 205Upon successful completion 206.Fn fopen , 207.Fn fdopen 208and 209.Fn freopen 210return a 211.Tn FILE 212pointer. 213Otherwise, 214.Dv NULL 215is returned and the global variable 216.Va errno 217is set to indicate the error. 218.Sh ERRORS 219.Bl -tag -width Er 220.It Bq Er EINVAL 221The 222.Fa mode 223argument 224to 225.Fn fopen , 226.Fn fdopen , 227or 228.Fn freopen 229was invalid. 230.El 231.Pp 232The 233.Fn fopen , 234.Fn fdopen 235and 236.Fn freopen 237functions 238may also fail and set 239.Va errno 240for any of the errors specified for the routine 241.Xr malloc 3 . 242.Pp 243The 244.Fn fopen 245function 246may also fail and set 247.Va errno 248for any of the errors specified for the routine 249.Xr open 2 . 250.Pp 251The 252.Fn fdopen 253function 254may also fail and set 255.Va errno 256for any of the errors specified for the routine 257.Xr fcntl 2 . 258.Pp 259The 260.Fn freopen 261function 262may also fail and set 263.Va errno 264for any of the errors specified for the routines 265.Xr open 2 , 266.Xr fclose 3 267and 268.Xr fflush 3 . 269.Sh SEE ALSO 270.Xr open 2 , 271.Xr fclose 3 , 272.Xr fileno 3 , 273.Xr fseek 3 , 274.Xr funopen 3 275.Sh STANDARDS 276The 277.Fn fopen 278and 279.Fn freopen 280functions 281conform to 282.St -isoC . 283The 284.Fn fdopen 285function 286conforms to 287.St -p1003.1-88 . 288