1.\" $NetBSD: fopen.3,v 1.21 2003/04/16 13:34:44 wiz Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Chris Torek and the American National Standards Committee X3, 8.\" on Information Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)fopen.3 8.1 (Berkeley) 6/4/93 39.\" 40.Dd June 4, 1993 41.Dt FOPEN 3 42.Os 43.Sh NAME 44.Nm fopen , 45.Nm fdopen , 46.Nm freopen 47.Nd stream open functions 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.In stdio.h 52.Ft FILE * 53.Fn fopen "const char *path" "const char *mode" 54.Ft FILE * 55.Fn fdopen "int fildes" "const char *mode" 56.Ft FILE * 57.Fn freopen "const char *path" "const char *mode" "FILE * restrict stream" 58.Sh DESCRIPTION 59The 60.Fn fopen 61function 62opens the file whose name is the string pointed to by 63.Fa path 64and associates a stream with it. 65.Pp 66The argument 67.Fa mode 68points to a string beginning with one of the following 69sequences (Additional characters may follow these sequences.): 70.Bl -tag -width indent 71.It Dq Li r 72Open for reading. 73.It Dq Li r+ 74Open for reading and writing. 75.It Dq Li w 76Open for writing. 77Truncate file to zero length or create file. 78.It Dq Li w+ 79Open for reading and writing. 80Truncate file to zero length or create file. 81.It Dq Li a 82Append; open for writing. 83The file is created if it does not exist. 84.It Dq Li a+ 85Append; open for reading and writing. 86The file is created if it does not exist. 87.El 88.Pp 89The 90.Fa mode 91string can also include the letter ``b'' either as a last character or 92as a character between the characters in any of the two-character strings 93described above. 94This is strictly for compatibility with 95.St -ansiC 96and has no effect; the ``b'' is ignored. 97.Pp 98The letter ``f'' in the mode string restricts fopen to regular 99files; if the file opened is not a regular file, 100.Fn fopen 101will fail. 102This is a non 103.St -ansiC 104extension. 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 123Opening a file with append mode causes all subsequent writes to it 124to be forced to the then current end of file, regardless of intervening 125repositioning of the stream. 126.Pp 127The 128.Fn fopen 129and 130.Fn freopen 131functions initially position the stream at the start of the file 132unless the file is opened with append mode, 133in which case the stream is initially positioned at the end of the file. 134.\" PR 6072 claims this paragraph is not correct. 135.\" .Pp 136.\" Reads and writes may be intermixed on read/write streams in any order, 137.\" and do not require an intermediate seek as in previous versions of 138.\" .Em stdio . 139.\" This is not portable to other systems, however; 140.\" .Tn ANSI C 141.\" requires that 142.\" a file positioning function intervene between output and input, unless 143.\" an input operation encounters end-of-file. 144.Pp 145The 146.Fn fdopen 147function associates a stream with the existing file descriptor, 148.Fa fildes . 149The 150.Fa mode 151of the stream must be compatible with the mode of the file descriptor. 152The stream is positioned at the file offset of the file descriptor. 153.Pp 154The 155.Fn freopen 156function 157opens the file whose name is the string pointed to by 158.Fa path 159and associates the stream pointed to by 160.Fa stream 161with it. 162The original stream (if it exists) is closed. 163The 164.Fa mode 165argument is used just as in the 166.Fn fopen 167function. 168The primary use of the 169.Fn freopen 170function 171is to change the file associated with a 172standard text stream 173.Pf ( Em stderr , 174.Em stdin , 175or 176.Em stdout ) . 177.Sh RETURN VALUES 178Upon successful completion 179.Fn fopen , 180.Fn fdopen 181and 182.Fn freopen 183return a 184.Tn FILE 185pointer. 186Otherwise, 187.Dv NULL 188is returned and the global variable 189.Va errno 190is set to indicate the error. 191.Sh ERRORS 192.Bl -tag -width Er 193.It Bq Er EINVAL 194The 195.Fa mode 196provided to 197.Fn fopen , 198.Fn fdopen , 199or 200.Fn freopen 201was invalid. 202.It Bq Er EFTYPE 203The file is not a regular file and the character ``f'' is specified 204in the mode. 205.El 206.Pp 207The 208.Fn fopen , 209.Fn fdopen 210and 211.Fn freopen 212functions 213may also fail and set 214.Va errno 215for any of the errors specified for the routine 216.Xr malloc 3 . 217.Pp 218The 219.Fn fopen 220function 221may also fail and set 222.Va errno 223for any of the errors specified for the routine 224.Xr open 2 . 225.Pp 226The 227.Fn fdopen 228function 229may also fail and set 230.Va errno 231for any of the errors specified for the routine 232.Xr fcntl 2 . 233.Pp 234The 235.Fn freopen 236function 237may also fail and set 238.Va errno 239for any of the errors specified for the routines 240.Xr open 2 , 241.Xr fclose 3 242and 243.Xr fflush 3 . 244.Sh SEE ALSO 245.Xr open 2 , 246.Xr fclose 3 , 247.Xr fileno 3 , 248.Xr fseek 3 , 249.Xr funopen 3 250.Sh STANDARDS 251The 252.Fn fopen 253and 254.Fn freopen 255functions 256conform to 257.St -ansiC . 258The 259.Fn fdopen 260function conforms to 261.St -p1003.1-90 . 262.Sh CAVEATS 263Proper code using 264.Fn fdopen 265with error checking should 266.Xr close 2 267.Fa fildes 268in case of failure, and 269.Xr fclose 3 270the resulting FILE * in case of success. 271.Bd -literal 272 FILE *file; 273 int fd; 274 275 if ((file = fdopen(fd, "r")) != NULL) { 276 /* perform operations on the FILE * */ 277 fclose(file); 278 } else { 279 /* failure, report the error */ 280 close(fd); 281 } 282.Ed 283