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 January 26, 2003 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 64sequences (Additional characters may follow these sequences.): 65.Bl -tag -width indent 66.It Dq Li r 67Open text file for reading. 68The stream is positioned at the beginning of the file. 69.It Dq Li r+ 70Open for reading and writing. 71The stream is positioned at the beginning of the file. 72.It Dq Li w 73Truncate to zero length or create text file for writing. 74The stream is positioned at the beginning of the file. 75.It Dq Li w+ 76Open for reading and writing. 77The file is created if it does not exist, otherwise it is truncated. 78The stream is positioned at the beginning of the file. 79.It Dq Li a 80Open for writing. 81The file is created if it does not exist. 82The stream is positioned at the end of the file. 83Subsequent writes to the file will always end up at the then current 84end of file, irrespective of any intervening 85.Xr fseek 3 86or similar. 87.It Dq Li a+ 88Open for reading and writing. 89The file is created if it does not exist. 90The stream is positioned at the end of the file. 91Subsequent writes to the file will always end up at the then current 92end of file, irrespective of any intervening 93.Xr fseek 3 94or similar. 95.El 96.Pp 97The 98.Fa mode 99string can also include the letter ``b'' either as a third character or 100as a character between the characters in any of the two-character strings 101described above. 102This is strictly for compatibility with 103.St -isoC 104and has no effect; the ``b'' is ignored. 105.Pp 106Any created files will have mode 107.Pf \\*q Dv S_IRUSR 108\&| 109.Dv S_IWUSR 110\&| 111.Dv S_IRGRP 112\&| 113.Dv S_IWGRP 114\&| 115.Dv S_IROTH 116\&| 117.Dv S_IWOTH Ns \\*q 118.Pq Li 0666 , 119as modified by the process' 120umask value (see 121.Xr umask 2 ) . 122.Pp 123Reads and writes may be intermixed on read/write streams in any order, 124and do not require an intermediate seek as in previous versions of 125.Em stdio . 126This is not portable to other systems, however; 127.Tn ANSI C 128requires that 129a file positioning function intervene between output and input, unless 130an input operation encounters end-of-file. 131.Pp 132The 133.Fn fdopen 134function associates a stream with the existing file descriptor, 135.Fa fildes . 136The mode 137of the stream must be compatible with the mode of the file descriptor. 138When the stream is closed via 139.Xr fclose 3 , 140.Fa fildes 141is closed also. 142.Pp 143The 144.Fn freopen 145function 146opens the file whose name is the string pointed to by 147.Fa path 148and associates the stream pointed to by 149.Fa stream 150with it. 151The original stream (if it exists) is closed. 152The 153.Fa mode 154argument is used just as in the 155.Fn fopen 156function. 157.Pp 158If the 159.Fa path 160argument is 161.Dv NULL , 162.Fn freopen 163attempts to re-open the file associated with 164.Fa stream 165with a new mode. 166The new mode must be compatible with the mode that the stream was originally 167opened with: 168.Bl -bullet -offset indent 169.It 170Streams originally opened with mode 171.Dq Li r 172can only be reopened with that same mode. 173.It 174Streams originally opened with mode 175.Dq Li a 176can be reopened with the same mode, or mode 177.Dq Li w . 178.It 179Streams originally opened with mode 180.Dq Li w 181can be reopened with the same mode, or mode 182.Dq Li a . 183.It 184Streams originally opened with mode 185.Dq Li r+ , 186.Dq Li w+ , 187or 188.Dq Li a+ 189can be reopened with any mode. 190.El 191.Pp 192The primary use of the 193.Fn freopen 194function 195is to change the file associated with a 196standard text stream 197.Dv ( stderr , stdin , 198or 199.Dv stdout ) . 200.Sh RETURN VALUES 201Upon successful completion 202.Fn fopen , 203.Fn fdopen 204and 205.Fn freopen 206return a 207.Tn FILE 208pointer. 209Otherwise, 210.Dv NULL 211is returned and the global variable 212.Va errno 213is set to indicate the error. 214.Sh ERRORS 215.Bl -tag -width Er 216.It Bq Er EINVAL 217The 218.Fa mode 219argument 220to 221.Fn fopen , 222.Fn fdopen , 223or 224.Fn freopen 225was invalid. 226.El 227.Pp 228The 229.Fn fopen , 230.Fn fdopen 231and 232.Fn freopen 233functions 234may also fail and set 235.Va errno 236for any of the errors specified for the routine 237.Xr malloc 3 . 238.Pp 239The 240.Fn fopen 241function 242may also fail and set 243.Va errno 244for any of the errors specified for the routine 245.Xr open 2 . 246.Pp 247The 248.Fn fdopen 249function 250may also fail and set 251.Va errno 252for any of the errors specified for the routine 253.Xr fcntl 2 . 254.Pp 255The 256.Fn freopen 257function 258may also fail and set 259.Va errno 260for any of the errors specified for the routines 261.Xr open 2 , 262.Xr fclose 3 263and 264.Xr fflush 3 . 265.Sh SEE ALSO 266.Xr open 2 , 267.Xr fclose 3 , 268.Xr fileno 3 , 269.Xr fseek 3 , 270.Xr funopen 3 271.Sh STANDARDS 272The 273.Fn fopen 274and 275.Fn freopen 276functions 277conform to 278.St -isoC . 279The 280.Fn fdopen 281function 282conforms to 283.St -p1003.1-88 . 284