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.\" %sccs.include.redist.man% 9.\" 10.\" @(#)fopen.3 8.1 (Berkeley) 06/04/93 11.\" 12.Dd 13.Dt FOPEN 3 14.Os 15.Sh NAME 16.Nm fopen , 17.Nm fdopen , 18.Nm freopen 19.Nd stream open functions 20.Sh SYNOPSIS 21.Fd #include <stdio.h> 22.Ft FILE * 23.Fn fopen "char *path" "char *mode" 24.Ft FILE * 25.Fn fdopen "int fildes" "char *mode" 26.Ft FILE * 27.Fn freopen "char *path" "char *mode" "FILE *stream" 28.Sh DESCRIPTION 29The 30.Fn fopen 31function 32opens the file whose name is the string pointed to by 33.Fa path 34and associates a stream with it. 35.Pp 36The argument 37.Fa mode 38points to a string beginning with one of the following 39sequences (Additional characters may follow these sequences.): 40.Bl -tag -width indent 41.It Dq Li r 42Open text file for reading. 43The stream is positioned at the beginning of the file. 44.It Dq Li r+ 45Open for reading and writing. 46The stream is positioned at the beginning of the file. 47.It Dq Li w 48Truncate file to zero length or create text file for writing. 49The stream is positioned at the beginning of the file. 50.No It Dq Li w+ 51Open for reading and writing. 52The file is created if it does not exist, otherwise it is truncated. 53The stream is positioned at the beginning of the file. 54.It Dq Li a 55Open for writing. 56The file is created if it does not exist. 57The stream is positioned at the end of the file. 58.It Dq Li a+ 59Open for reading and writing. 60The file is created if it does not exist. 61The stream is positioned at the end of the file. 62.El 63.Pp 64The 65.Fa mode 66string can also include the letter ``b'' either as a third character or 67as a character between the characters in any of the two-character strings 68described above. 69This is strictly for compatibility with 70.St -ansiC 71and has no effect; the ``b'' is ignored. 72.Pp 73Any created files will have mode 74.Pf \\*q Dv S_IRUSR 75\&| 76.Dv S_IWUSR 77\&| 78.Dv S_IRGRP 79\&| 80.Dv S_IWGRP 81\&| 82.Dv S_IROTH 83\&| 84.Dv S_IWOTH Ns \\*q 85.Pq Li 0666 , 86as modified by the process' 87umask value (see 88.Xr umask 2 ) . 89.Pp 90Reads and writes may be intermixed on read/write streams in any order, 91and do not require an intermediate seek as in previous versions of 92.Em stdio . 93This is not portable to other systems, however; 94.Tn ANSI C 95requires that 96a file positioning function intervene between output and input, unless 97an input operation encounters end-of-file. 98.Pp 99The 100.Fn fdopen 101function associates a stream with the existing file descriptor, 102.Fa fildes . 103The 104.Fa mode 105of the stream must be compatible with the mode of the file descriptor. 106.Pp 107The 108.Fn freopen 109function 110opens the file whose name is the string pointed to by 111.Fa path 112and associates the stream pointed to by 113.Fa stream 114with it. 115The original stream (if it exists) is closed. 116The 117.Fa mode 118argument is used just as in the 119.Xr fopen 120function. 121The primary use of the 122.Fn freopen 123function 124is to change the file associated with a 125standard text stream 126.Pf ( Em stderr , 127.Em stdin , 128or 129.Em stdout ) . 130.Sh RETURN VALUES 131Upon successful completion 132.Fn fopen , 133.Fn fdopen 134and 135.Fn freopen 136return a 137.Tn FILE 138pointer. 139Otherwise, 140.Dv NULL 141is returned and the global variable 142.Va errno 143is set to indicate the error. 144.Sh ERRORS 145.Bl -tag -width [EINVAL] 146.It Bq Er EINVAL 147The 148.Fa mode 149provided to 150.Fn fopen , 151.Fn fdopen , 152or 153.Fn freopen 154was invalid. 155.El 156.Pp 157The 158.Fn fopen , 159.Fn fdopen 160and 161.Fn freopen 162functions 163may also fail and set 164.Va errno 165for any of the errors specified for the routine 166.Xr malloc 3 . 167.Pp 168The 169.Fn fopen 170function 171may also fail and set 172.Va errno 173for any of the errors specified for the routine 174.Xr open 2 . 175.Pp 176The 177.Fn fdopen 178function 179may also fail and set 180.Va errno 181for any of the errors specified for the routine 182.Xr fcntl 2 . 183.Pp 184The 185.Fn freopen 186function 187may also fail and set 188.Va errno 189for any of the errors specified for the routines 190.Xr open 2 , 191.Xr fclose 3 192and 193.Xr fflush 3 . 194.Sh SEE ALSO 195.Xr open 2 , 196.Xr fclose 3 , 197.Xr fseek 3 , 198.Xr funopen 3 199.Sh STANDARDS 200The 201.Fn fopen 202and 203.Fn freopen 204functions 205conform to 206.St -ansiC . 207The 208.Fn fdopen 209function 210conforms to 211.St -p1003.1-88 . 212