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 30, 2013 36.Dt FOPEN 3 37.Os 38.Sh NAME 39.Nm fopen , 40.Nm fdopen , 41.Nm freopen , 42.Nm fmemopen 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.Ft FILE * 55.Fn fmemopen "void *restrict *buf" "size_t size" "const char * restrict mode" 56.Sh DESCRIPTION 57The 58.Fn fopen 59function 60opens the file whose name is the string pointed to by 61.Fa path 62and associates a stream with it. 63.Pp 64The argument 65.Fa mode 66points to a string beginning with one of the following letters: 67.Bl -tag -width indent 68.It Dq Li r 69Open for reading. 70The stream is positioned at the beginning of the file. 71Fail if the file does not exist. 72.It Dq Li w 73Open for writing. 74The stream is positioned at the beginning of the file. 75Create the file if it does not exist. 76.It Dq Li a 77Open for writing. 78The stream is positioned at the end of the file. 79Subsequent writes to the file will always end up at the then current 80end of file, irrespective of any intervening 81.Xr fseek 3 82or similar. 83Create the file if it does not exist. 84.El 85.Pp 86An optional 87.Dq Li + 88following 89.Dq Li r , 90.Dq Li w , 91or 92.Dq Li a 93opens the file for both reading and writing. 94An optional 95.Dq Li x 96following 97.Dq Li w 98or 99.Dq Li w+ 100causes the 101.Fn fopen 102call to fail if the file already exists. 103An optional 104.Dq Li e 105following the above 106causes the 107.Fn fopen 108call to set the 109.Dv FD_CLOEXEC 110flag on the underlying file descriptor. 111.Pp 112The 113.Fa mode 114string can also include the letter 115.Dq Li b 116after either the 117.Dq Li + 118or the first letter. 119This is strictly for compatibility with 120.St -isoC 121and has effect only for 122.Fn fmemopen 123; otherwise 124.Dq Li b 125is ignored. 126.Pp 127Any created files will have mode 128.Do Dv S_IRUSR 129\&| 130.Dv S_IWUSR 131\&| 132.Dv S_IRGRP 133\&| 134.Dv S_IWGRP 135\&| 136.Dv S_IROTH 137\&| 138.Dv S_IWOTH Dc 139.Pq Li 0666 , 140as modified by the process' 141umask value (see 142.Xr umask 2 ) . 143.Pp 144Reads and writes may be intermixed on read/write streams in any order, 145and do not require an intermediate seek as in previous versions of 146.Em stdio . 147This is not portable to other systems, however; 148.Tn ANSI C 149requires that 150a file positioning function intervene between output and input, unless 151an input operation encounters end-of-file. 152.Pp 153The 154.Fn fdopen 155function associates a stream with the existing file descriptor, 156.Fa fildes . 157The mode 158of the stream must be compatible with the mode of the file descriptor. 159The 160.Dq Li x 161mode option is ignored. 162If the 163.Dq Li e 164mode option is present, the 165.Dv FD_CLOEXEC 166flag is set, otherwise it remains unchanged. 167When the stream is closed via 168.Xr fclose 3 , 169.Fa fildes 170is closed also. 171.Pp 172The 173.Fn freopen 174function 175opens the file whose name is the string pointed to by 176.Fa path 177and associates the stream pointed to by 178.Fa stream 179with it. 180The original stream (if it exists) is closed. 181The 182.Fa mode 183argument is used just as in the 184.Fn fopen 185function. 186.Pp 187If the 188.Fa path 189argument is 190.Dv NULL , 191.Fn freopen 192attempts to re-open the file associated with 193.Fa stream 194with a new mode. 195The new mode must be compatible with the mode that the stream was originally 196opened with: 197Streams open for reading can only be re-opened for reading, 198streams open for writing can only be re-opened for writing, 199and streams open for reading and writing can be re-opened in any mode. 200The 201.Dq Li x 202mode option is not meaningful in this context. 203.Pp 204The primary use of the 205.Fn freopen 206function 207is to change the file associated with a 208standard text stream 209.Dv ( stderr , stdin , 210or 211.Dv stdout ) . 212.Pp 213The 214.Fn fmemopen 215function 216associates the buffer given by the 217.Fa buf 218and 219.Fa size 220arguments with a stream. 221The 222.Fa buf 223argument is either a null pointer or point to a buffer that 224is at least 225.Fa size 226bytes long. 227If a null pointer is specified as the 228.Fa buf 229argument, 230.Fn fmemopen 231allocates 232.Fa size 233bytes of memory. This buffer is automatically freed when the 234stream is closed. Buffers can be opened in text-mode (default) or binary-mode 235(if 236.Dq Li b 237is present in the second or third position of the 238.Fa mode 239argument). Buffers opened in text-mode make sure that writes are terminated with 240a NULL byte, if the last write hasn't filled up the whole buffer. Buffers 241opened in binary-mode never append a NULL byte. 242.Sh RETURN VALUES 243Upon successful completion 244.Fn fopen , 245.Fn fdopen 246and 247.Fn freopen 248return a 249.Tn FILE 250pointer. 251Otherwise, 252.Dv NULL 253is returned and the global variable 254.Va errno 255is set to indicate the error. 256.Sh ERRORS 257.Bl -tag -width Er 258.It Bq Er EINVAL 259The 260.Fa mode 261argument 262to 263.Fn fopen , 264.Fn fdopen , 265.Fn freopen , 266or 267.Fn fmemopen 268was invalid. 269.El 270.Pp 271The 272.Fn fopen , 273.Fn fdopen , 274.Fn freopen 275and 276.Fn fmemopen 277functions 278may also fail and set 279.Va errno 280for any of the errors specified for the routine 281.Xr malloc 3 . 282.Pp 283The 284.Fn fopen 285function 286may also fail and set 287.Va errno 288for any of the errors specified for the routine 289.Xr open 2 . 290.Pp 291The 292.Fn fdopen 293function 294may also fail and set 295.Va errno 296for any of the errors specified for the routine 297.Xr fcntl 2 . 298.Pp 299The 300.Fn freopen 301function 302may also fail and set 303.Va errno 304for any of the errors specified for the routines 305.Xr open 2 , 306.Xr fclose 3 307and 308.Xr fflush 3 . 309.Pp 310The 311.Fn fmemopen 312function 313may also fail and set 314.Va errno 315if the 316.Fa size 317argument is 0. 318.Sh SEE ALSO 319.Xr open 2 , 320.Xr fclose 3 , 321.Xr fileno 3 , 322.Xr fseek 3 , 323.Xr funopen 3 324.Sh STANDARDS 325The 326.Fn fopen 327and 328.Fn freopen 329functions 330conform to 331.St -isoC , 332with the exception of the 333.Dq Li x 334mode option which conforms to 335.St -isoC-2011 . 336The 337.Fn fdopen 338function 339conforms to 340.St -p1003.1-88 . 341The 342.Dq Li e 343mode option does not conform to any standard 344but is also supported by glibc. 345The 346.Fn fmemopen 347function 348conforms to 349.St -p1003.1-2008 . 350The 351.Dq Li b 352mode does not conform to any standard 353but is also supported by glibc. 354