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.\" 3. 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. 75Truncate the file to zero length if it exists or create 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 ; 123otherwise 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. 234This buffer is automatically freed when the stream is closed. 235Buffers can be opened in text-mode (default) or binary-mode 236(if 237.Dq Li b 238is present in the second or third position of the 239.Fa mode 240argument). 241Buffers opened in text-mode make sure that writes are terminated with a 242.Dv NULL 243byte, if the last write hasn't filled up the whole buffer. 244Buffers opened in binary-mode never append a 245.Dv NULL 246byte. 247.Sh RETURN VALUES 248Upon successful completion 249.Fn fopen , 250.Fn fdopen 251and 252.Fn freopen 253return a 254.Tn FILE 255pointer. 256Otherwise, 257.Dv NULL 258is returned and the global variable 259.Va errno 260is set to indicate the error. 261.Sh ERRORS 262.Bl -tag -width Er 263.It Bq Er EINVAL 264The 265.Fa mode 266argument 267to 268.Fn fopen , 269.Fn fdopen , 270.Fn freopen , 271or 272.Fn fmemopen 273was invalid. 274.El 275.Pp 276The 277.Fn fopen , 278.Fn fdopen , 279.Fn freopen 280and 281.Fn fmemopen 282functions 283may also fail and set 284.Va errno 285for any of the errors specified for the routine 286.Xr malloc 3 . 287.Pp 288The 289.Fn fopen 290function 291may also fail and set 292.Va errno 293for any of the errors specified for the routine 294.Xr open 2 . 295.Pp 296The 297.Fn fdopen 298function 299may also fail and set 300.Va errno 301for any of the errors specified for the routine 302.Xr fcntl 2 . 303.Pp 304The 305.Fn freopen 306function 307may also fail and set 308.Va errno 309for any of the errors specified for the routines 310.Xr open 2 , 311.Xr fclose 3 312and 313.Xr fflush 3 . 314.Pp 315The 316.Fn fmemopen 317function 318may also fail and set 319.Va errno 320if the 321.Fa size 322argument is 0. 323.Sh SEE ALSO 324.Xr open 2 , 325.Xr fclose 3 , 326.Xr fileno 3 , 327.Xr fseek 3 , 328.Xr funopen 3 329.Sh STANDARDS 330The 331.Fn fopen 332and 333.Fn freopen 334functions 335conform to 336.St -isoC , 337with the exception of the 338.Dq Li x 339mode option which conforms to 340.St -isoC-2011 . 341The 342.Fn fdopen 343function 344conforms to 345.St -p1003.1-88 . 346The 347.Dq Li e 348mode option does not conform to any standard 349but is also supported by glibc. 350The 351.Fn fmemopen 352function 353conforms to 354.St -p1003.1-2008 . 355The 356.Dq Li b 357mode does not conform to any standard 358but is also supported by glibc. 359