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