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