1*0a6a1f1dSLionel Sambuc.\" $NetBSD: fopen.3,v 1.31 2015/07/15 19:08:43 christos Exp $ 22fe8fb19SBen Gras.\" 32fe8fb19SBen Gras.\" Copyright (c) 1990, 1991, 1993 42fe8fb19SBen Gras.\" The Regents of the University of California. All rights reserved. 52fe8fb19SBen Gras.\" 62fe8fb19SBen Gras.\" This code is derived from software contributed to Berkeley by 72fe8fb19SBen Gras.\" Chris Torek and the American National Standards Committee X3, 82fe8fb19SBen Gras.\" on Information Processing Systems. 92fe8fb19SBen Gras.\" 102fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without 112fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions 122fe8fb19SBen Gras.\" are met: 132fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright 142fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer. 152fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright 162fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer in the 172fe8fb19SBen Gras.\" documentation and/or other materials provided with the distribution. 182fe8fb19SBen Gras.\" 3. Neither the name of the University nor the names of its contributors 192fe8fb19SBen Gras.\" may be used to endorse or promote products derived from this software 202fe8fb19SBen Gras.\" without specific prior written permission. 212fe8fb19SBen Gras.\" 222fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 232fe8fb19SBen Gras.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 242fe8fb19SBen Gras.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 252fe8fb19SBen Gras.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 262fe8fb19SBen Gras.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 272fe8fb19SBen Gras.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 282fe8fb19SBen Gras.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 292fe8fb19SBen Gras.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 302fe8fb19SBen Gras.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 312fe8fb19SBen Gras.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 322fe8fb19SBen Gras.\" SUCH DAMAGE. 332fe8fb19SBen Gras.\" 342fe8fb19SBen Gras.\" @(#)fopen.3 8.1 (Berkeley) 6/4/93 352fe8fb19SBen Gras.\" 3684d9c625SLionel Sambuc.Dd November 14, 2012 372fe8fb19SBen Gras.Dt FOPEN 3 382fe8fb19SBen Gras.Os 392fe8fb19SBen Gras.Sh NAME 402fe8fb19SBen Gras.Nm fopen , 412fe8fb19SBen Gras.Nm fdopen , 422fe8fb19SBen Gras.Nm freopen 432fe8fb19SBen Gras.Nd stream open functions 442fe8fb19SBen Gras.Sh LIBRARY 452fe8fb19SBen Gras.Lb libc 462fe8fb19SBen Gras.Sh SYNOPSIS 472fe8fb19SBen Gras.In stdio.h 482fe8fb19SBen Gras.Ft FILE * 492fe8fb19SBen Gras.Fn fopen "const char * restrict path" "const char * restrict mode" 502fe8fb19SBen Gras.Ft FILE * 512fe8fb19SBen Gras.Fn fdopen "int fildes" "const char *mode" 522fe8fb19SBen Gras.Ft FILE * 532fe8fb19SBen Gras.Fn freopen "const char * restrict path" "const char * restrict mode" "FILE * restrict stream" 542fe8fb19SBen Gras.Sh DESCRIPTION 552fe8fb19SBen GrasThe 562fe8fb19SBen Gras.Fn fopen 572fe8fb19SBen Grasfunction 582fe8fb19SBen Grasopens the file whose name is the string pointed to by 592fe8fb19SBen Gras.Fa path 602fe8fb19SBen Grasand associates a stream with it. 612fe8fb19SBen Gras.Pp 622fe8fb19SBen GrasThe argument 632fe8fb19SBen Gras.Fa mode 642fe8fb19SBen Graspoints to a string beginning with one of the following 652fe8fb19SBen Grassequences (Additional characters may follow these sequences.): 66f14fb602SLionel Sambuc.Bl -tag -width 4n 67f14fb602SLionel Sambuc.It Dq Li a 68f14fb602SLionel SambucAppend; open for writing. 69f14fb602SLionel SambucThe file is created if it does not exist. 70f14fb602SLionel Sambuc.It Dq Li a+ 71f14fb602SLionel SambucAppend; open for reading and writing. 72f14fb602SLionel SambucThe file is created if it does not exist. 732fe8fb19SBen Gras.It Dq Li r 742fe8fb19SBen GrasOpen for reading. 752fe8fb19SBen Gras.It Dq Li r+ 762fe8fb19SBen GrasOpen for reading and writing. 772fe8fb19SBen Gras.It Dq Li w 782fe8fb19SBen GrasOpen for writing. 792fe8fb19SBen GrasTruncate file to zero length or create file. 802fe8fb19SBen Gras.It Dq Li w+ 812fe8fb19SBen GrasOpen for reading and writing. 822fe8fb19SBen GrasTruncate file to zero length or create file. 832fe8fb19SBen Gras.El 842fe8fb19SBen Gras.Pp 85f14fb602SLionel SambucAdditionally, the 862fe8fb19SBen Gras.Fa mode 87f14fb602SLionel Sambucstring can also include one of the following letters: 88f14fb602SLionel Sambuc.Bl -tag -width 4n 89f14fb602SLionel Sambuc.It Sq b 90f14fb602SLionel SambucThe letter 91f14fb602SLionel Sambuc.Sq b 92f14fb602SLionel Sambucmay appear either as a last character or as a character between the 93f14fb602SLionel Sambuccharacters in any of the two-character strings described above. 942fe8fb19SBen GrasThis is strictly for compatibility with 952fe8fb19SBen Gras.St -ansiC 96f14fb602SLionel Sambucand has no effect; the 97f14fb602SLionel Sambuc.Sq b 98f14fb602SLionel Sambucis ignored. 99f14fb602SLionel Sambuc.It Sq e 100f14fb602SLionel SambucThe letter 101f14fb602SLionel Sambuc.Sq e 102f14fb602SLionel Sambucin the mode string sets the close-on-exec flag in the file descriptors of 103f14fb602SLionel Sambucthe newly opened file files; if the operation fails, 1042fe8fb19SBen Gras.Fn fopen 1052fe8fb19SBen Graswill fail. 1062fe8fb19SBen GrasThis is a non 1072fe8fb19SBen Gras.St -ansiC 1082fe8fb19SBen Grasextension. 109f14fb602SLionel Sambuc.It Sq f 110f14fb602SLionel SambucThe letter 111f14fb602SLionel Sambuc.Sq f 112f14fb602SLionel Sambucin the mode string restricts 113f14fb602SLionel Sambuc.Fn fopen 114f14fb602SLionel Sambucto regular files; if the file opened is not a regular file, 115f14fb602SLionel Sambuc.Fn fopen 116f14fb602SLionel Sambucwill fail. 117f14fb602SLionel SambucThis is a non 118f14fb602SLionel Sambuc.St -ansiC 119f14fb602SLionel Sambucextension. 12084d9c625SLionel Sambuc.It Sq x 12184d9c625SLionel SambucThe letter 12284d9c625SLionel Sambuc.Sq x 123*0a6a1f1dSLionel Sambucin the mode turns on exclusive open mode to the file 124*0a6a1f1dSLionel Sambuc.Pq Dv O_EXCL 12584d9c625SLionel Sambucwhich means that the file will not be created if it already exists. 126f14fb602SLionel Sambuc.El 1272fe8fb19SBen Gras.Pp 1282fe8fb19SBen GrasAny created files will have mode 1292fe8fb19SBen Gras.Pf \*q Dv S_IRUSR 1302fe8fb19SBen Gras\&| 1312fe8fb19SBen Gras.Dv S_IWUSR 1322fe8fb19SBen Gras\&| 1332fe8fb19SBen Gras.Dv S_IRGRP 1342fe8fb19SBen Gras\&| 1352fe8fb19SBen Gras.Dv S_IWGRP 1362fe8fb19SBen Gras\&| 1372fe8fb19SBen Gras.Dv S_IROTH 1382fe8fb19SBen Gras\&| 1392fe8fb19SBen Gras.Dv S_IWOTH Ns \*q 1402fe8fb19SBen Gras.Pq Li 0666 , 1412fe8fb19SBen Grasas modified by the process' 142f14fb602SLionel Sambuc.Xr umask 2 143f14fb602SLionel Sambucvalue. 1442fe8fb19SBen Gras.Pp 1452fe8fb19SBen GrasOpening a file with append mode causes all subsequent writes to it 1462fe8fb19SBen Grasto be forced to the then current end of file, regardless of intervening 1472fe8fb19SBen Grasrepositioning of the stream. 1482fe8fb19SBen Gras.Pp 1492fe8fb19SBen GrasThe 1502fe8fb19SBen Gras.Fn fopen 1512fe8fb19SBen Grasand 1522fe8fb19SBen Gras.Fn freopen 1532fe8fb19SBen Grasfunctions initially position the stream at the start of the file 1542fe8fb19SBen Grasunless the file is opened with append mode, 1552fe8fb19SBen Grasin which case the stream is initially positioned at the end of the file. 1562fe8fb19SBen Gras.\" PR 6072 claims this paragraph is not correct. 1572fe8fb19SBen Gras.\" .Pp 1582fe8fb19SBen Gras.\" Reads and writes may be intermixed on read/write streams in any order, 1592fe8fb19SBen Gras.\" and do not require an intermediate seek as in previous versions of 1602fe8fb19SBen Gras.\" .Em stdio . 1612fe8fb19SBen Gras.\" This is not portable to other systems, however; 1622fe8fb19SBen Gras.\" .Tn ANSI C 1632fe8fb19SBen Gras.\" requires that 1642fe8fb19SBen Gras.\" a file positioning function intervene between output and input, unless 1652fe8fb19SBen Gras.\" an input operation encounters end-of-file. 1662fe8fb19SBen Gras.Pp 1672fe8fb19SBen GrasThe 1682fe8fb19SBen Gras.Fn fdopen 1692fe8fb19SBen Grasfunction associates a stream with the existing file descriptor, 1702fe8fb19SBen Gras.Fa fildes . 1712fe8fb19SBen GrasThe 1722fe8fb19SBen Gras.Fa mode 1732fe8fb19SBen Grasof the stream must be compatible with the mode of the file descriptor. 1742fe8fb19SBen GrasThe stream is positioned at the file offset of the file descriptor. 1752fe8fb19SBen Gras.Pp 1762fe8fb19SBen GrasThe 1772fe8fb19SBen Gras.Fn freopen 1782fe8fb19SBen Grasfunction 1792fe8fb19SBen Grasopens the file whose name is the string pointed to by 1802fe8fb19SBen Gras.Fa path 1812fe8fb19SBen Grasand associates the stream pointed to by 1822fe8fb19SBen Gras.Fa stream 1832fe8fb19SBen Graswith it. 1842fe8fb19SBen GrasThe original stream (if it exists) is closed. 1852fe8fb19SBen GrasThe 1862fe8fb19SBen Gras.Fa mode 1872fe8fb19SBen Grasargument is used just as in the 1882fe8fb19SBen Gras.Fn fopen 1892fe8fb19SBen Grasfunction. 1902fe8fb19SBen GrasThe primary use of the 1912fe8fb19SBen Gras.Fn freopen 1922fe8fb19SBen Grasfunction 1932fe8fb19SBen Grasis to change the file associated with a 1942fe8fb19SBen Grasstandard text stream 1952fe8fb19SBen Gras.Pf ( Em stderr , 1962fe8fb19SBen Gras.Em stdin , 1972fe8fb19SBen Grasor 1982fe8fb19SBen Gras.Em stdout ) . 199*0a6a1f1dSLionel Sambuc.Pp 200*0a6a1f1dSLionel SambucInput and output against the opened stream will be fully buffered, unless 201*0a6a1f1dSLionel Sambucit refers to an interactive terminal device, or a different kind of buffering 202*0a6a1f1dSLionel Sambucis specified in the environment. 203*0a6a1f1dSLionel SambucSee 204*0a6a1f1dSLionel Sambuc.Xr setvbuf 3 205*0a6a1f1dSLionel Sambucfor additional details. 2062fe8fb19SBen Gras.Sh RETURN VALUES 2072fe8fb19SBen GrasUpon successful completion 2082fe8fb19SBen Gras.Fn fopen , 2092fe8fb19SBen Gras.Fn fdopen 2102fe8fb19SBen Grasand 2112fe8fb19SBen Gras.Fn freopen 2122fe8fb19SBen Grasreturn a 2132fe8fb19SBen Gras.Tn FILE 2142fe8fb19SBen Graspointer. 2152fe8fb19SBen GrasOtherwise, 2162fe8fb19SBen Gras.Dv NULL 2172fe8fb19SBen Grasis returned and the global variable 2182fe8fb19SBen Gras.Va errno 2192fe8fb19SBen Grasis set to indicate the error. 2202fe8fb19SBen Gras.Sh ERRORS 221f14fb602SLionel SambucThe functions may fail if: 2222fe8fb19SBen Gras.Bl -tag -width Er 2232fe8fb19SBen Gras.It Bq Er EFTYPE 2242fe8fb19SBen GrasThe file is not a regular file and the character ``f'' is specified 2252fe8fb19SBen Grasin the mode. 226f14fb602SLionel Sambuc.It Bq Er EINVAL 227f14fb602SLionel SambucThe specified 228f14fb602SLionel Sambuc.Fa mode 229f14fb602SLionel Sambucwas invalid. 2302fe8fb19SBen Gras.El 2312fe8fb19SBen Gras.Pp 2322fe8fb19SBen GrasThe 2332fe8fb19SBen Gras.Fn fopen , 2342fe8fb19SBen Gras.Fn fdopen 2352fe8fb19SBen Grasand 2362fe8fb19SBen Gras.Fn freopen 2372fe8fb19SBen Grasfunctions 2382fe8fb19SBen Grasmay also fail and set 2392fe8fb19SBen Gras.Va errno 2402fe8fb19SBen Grasfor any of the errors specified for the routine 2412fe8fb19SBen Gras.Xr malloc 3 . 2422fe8fb19SBen Gras.Pp 2432fe8fb19SBen GrasThe 2442fe8fb19SBen Gras.Fn fopen 2452fe8fb19SBen Grasfunction 2462fe8fb19SBen Grasmay also fail and set 2472fe8fb19SBen Gras.Va errno 2482fe8fb19SBen Grasfor any of the errors specified for the routine 2492fe8fb19SBen Gras.Xr open 2 . 2502fe8fb19SBen Gras.Pp 2512fe8fb19SBen GrasThe 2522fe8fb19SBen Gras.Fn fdopen 2532fe8fb19SBen Grasfunction 2542fe8fb19SBen Grasmay also fail and set 2552fe8fb19SBen Gras.Va errno 2562fe8fb19SBen Grasfor any of the errors specified for the routine 2572fe8fb19SBen Gras.Xr fcntl 2 . 2582fe8fb19SBen Gras.Pp 2592fe8fb19SBen GrasThe 2602fe8fb19SBen Gras.Fn freopen 2612fe8fb19SBen Grasfunction 2622fe8fb19SBen Grasmay also fail and set 2632fe8fb19SBen Gras.Va errno 2642fe8fb19SBen Grasfor any of the errors specified for the routines 2652fe8fb19SBen Gras.Xr open 2 , 2662fe8fb19SBen Gras.Xr fclose 3 2672fe8fb19SBen Grasand 2682fe8fb19SBen Gras.Xr fflush 3 . 2692fe8fb19SBen Gras.Sh SEE ALSO 2702fe8fb19SBen Gras.Xr open 2 , 2712fe8fb19SBen Gras.Xr fclose 3 , 2722fe8fb19SBen Gras.Xr fileno 3 , 2732fe8fb19SBen Gras.Xr fseek 3 , 2742fe8fb19SBen Gras.Xr funopen 3 2752fe8fb19SBen Gras.Sh STANDARDS 2762fe8fb19SBen GrasThe 2772fe8fb19SBen Gras.Fn fopen 2782fe8fb19SBen Grasand 2792fe8fb19SBen Gras.Fn freopen 280f14fb602SLionel Sambucfunctions conform to 2812fe8fb19SBen Gras.St -ansiC . 282f14fb602SLionel SambucAll three functions are specified in 283f14fb602SLionel Sambuc.St -p1003.1-2008 . 2842fe8fb19SBen Gras.Sh CAVEATS 2852fe8fb19SBen GrasProper code using 2862fe8fb19SBen Gras.Fn fdopen 2872fe8fb19SBen Graswith error checking should 2882fe8fb19SBen Gras.Xr close 2 2892fe8fb19SBen Gras.Fa fildes 2902fe8fb19SBen Grasin case of failure, and 2912fe8fb19SBen Gras.Xr fclose 3 2922fe8fb19SBen Grasthe resulting FILE * in case of success. 2932fe8fb19SBen Gras.Bd -literal 2942fe8fb19SBen Gras FILE *file; 2952fe8fb19SBen Gras int fd; 2962fe8fb19SBen Gras 2972fe8fb19SBen Gras if ((file = fdopen(fd, "r")) != NULL) { 2982fe8fb19SBen Gras /* perform operations on the FILE * */ 2992fe8fb19SBen Gras fclose(file); 3002fe8fb19SBen Gras } else { 3012fe8fb19SBen Gras /* failure, report the error */ 3022fe8fb19SBen Gras close(fd); 3032fe8fb19SBen Gras } 3042fe8fb19SBen Gras.Ed 305