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 the ``b'' is ignored. 124.Pp 125Any created files will have mode 126.Do Dv S_IRUSR 127\&| 128.Dv S_IWUSR 129\&| 130.Dv S_IRGRP 131\&| 132.Dv S_IWGRP 133\&| 134.Dv S_IROTH 135\&| 136.Dv S_IWOTH Dc 137.Pq Li 0666 , 138as modified by the process' 139umask value (see 140.Xr umask 2 ) . 141.Pp 142Reads and writes may be intermixed on read/write streams in any order, 143and do not require an intermediate seek as in previous versions of 144.Em stdio . 145This is not portable to other systems, however; 146.Tn ANSI C 147requires that 148a file positioning function intervene between output and input, unless 149an input operation encounters end-of-file. 150.Pp 151The 152.Fn fdopen 153function associates a stream with the existing file descriptor, 154.Fa fildes . 155The mode 156of the stream must be compatible with the mode of the file descriptor. 157The 158.Dq Li x 159mode option is ignored. 160If the 161.Dq Li e 162mode option is present, the 163.Dv FD_CLOEXEC 164flag is set, otherwise it remains unchanged. 165When the stream is closed via 166.Xr fclose 3 , 167.Fa fildes 168is closed also. 169.Pp 170The 171.Fn freopen 172function 173opens the file whose name is the string pointed to by 174.Fa path 175and associates the stream pointed to by 176.Fa stream 177with it. 178The original stream (if it exists) is closed. 179The 180.Fa mode 181argument is used just as in the 182.Fn fopen 183function. 184.Pp 185If the 186.Fa path 187argument is 188.Dv NULL , 189.Fn freopen 190attempts to re-open the file associated with 191.Fa stream 192with a new mode. 193The new mode must be compatible with the mode that the stream was originally 194opened with: 195Streams open for reading can only be re-opened for reading, 196streams open for writing can only be re-opened for writing, 197and streams open for reading and writing can be re-opened in any mode. 198The 199.Dq Li x 200mode option is not meaningful in this context. 201.Pp 202The primary use of the 203.Fn freopen 204function 205is to change the file associated with a 206standard text stream 207.Dv ( stderr , stdin , 208or 209.Dv stdout ) . 210.Pp 211The 212.Fn fmemopen 213function 214associates the buffer given by the 215.Fa buf 216and 217.Fa size 218arguments with a stream. 219The 220.Fa buf 221argument is either a null pointer or point to a buffer that 222is at least 223.Fa size 224bytes long. 225If a null pointer is specified as the 226.Fa buf 227argument, 228.Fn fmemopen 229allocates 230.Fa size 231bytes of memory. This buffer is automatically freed when the 232stream is closed. Buffers can be opened in text-mode (default) or binary-mode 233(if ``b'' is present in the second or third position of the 234.Fa mode 235argument). Buffers opened in text-mode make sure that writes are terminated with 236a NULL byte, if the last write hasn't filled up the whole buffer. Buffers 237opened in binary-mode never append a NULL byte. 238.Sh RETURN VALUES 239Upon successful completion 240.Fn fopen , 241.Fn fdopen 242and 243.Fn freopen 244return a 245.Tn FILE 246pointer. 247Otherwise, 248.Dv NULL 249is returned and the global variable 250.Va errno 251is set to indicate the error. 252.Sh ERRORS 253.Bl -tag -width Er 254.It Bq Er EINVAL 255The 256.Fa mode 257argument 258to 259.Fn fopen , 260.Fn fdopen , 261.Fn freopen , 262or 263.Fn fmemopen 264was invalid. 265.El 266.Pp 267The 268.Fn fopen , 269.Fn fdopen , 270.Fn freopen 271and 272.Fn fmemopen 273functions 274may also fail and set 275.Va errno 276for any of the errors specified for the routine 277.Xr malloc 3 . 278.Pp 279The 280.Fn fopen 281function 282may also fail and set 283.Va errno 284for any of the errors specified for the routine 285.Xr open 2 . 286.Pp 287The 288.Fn fdopen 289function 290may also fail and set 291.Va errno 292for any of the errors specified for the routine 293.Xr fcntl 2 . 294.Pp 295The 296.Fn freopen 297function 298may also fail and set 299.Va errno 300for any of the errors specified for the routines 301.Xr open 2 , 302.Xr fclose 3 303and 304.Xr fflush 3 . 305.Pp 306The 307.Fn fmemopen 308function 309may also fail and set 310.Va errno 311if the 312.Fa size 313argument is 0. 314.Sh SEE ALSO 315.Xr open 2 , 316.Xr fclose 3 , 317.Xr fileno 3 , 318.Xr fseek 3 , 319.Xr funopen 3 320.Sh STANDARDS 321The 322.Fn fopen 323and 324.Fn freopen 325functions 326conform to 327.St -isoC , 328with the exception of the 329.Dq Li x 330mode option which conforms to 331.St -isoC-2011 . 332The 333.Fn fdopen 334function 335conforms to 336.St -p1003.1-88 . 337The 338.Dq Li e 339mode option does not conform to any standard 340but is also supported by glibc. 341The 342.Fn fmemopen 343function 344conforms to 345.St -p1003.1-2008 . 346The ``b'' mode does not conform to any standard 347but is also supported by glibc. 348