1<html lang="en"> 2<head> 3<title>fopen - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Stdio.html#Stdio" title="Stdio"> 9<link rel="prev" href="fmemopen.html#fmemopen" title="fmemopen"> 10<link rel="next" href="fopencookie.html#fopencookie" title="fopencookie"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<meta http-equiv="Content-Style-Type" content="text/css"> 13<style type="text/css"><!-- 14 pre.display { font-family:inherit } 15 pre.format { font-family:inherit } 16 pre.smalldisplay { font-family:inherit; font-size:smaller } 17 pre.smallformat { font-family:inherit; font-size:smaller } 18 pre.smallexample { font-size:smaller } 19 pre.smalllisp { font-size:smaller } 20 span.sc { font-variant:small-caps } 21 span.roman { font-family:serif; font-weight:normal; } 22 span.sansserif { font-family:sans-serif; font-weight:normal; } 23--></style> 24<link rel="stylesheet" type="text/css" href="../cs.css"> 25</head> 26<body> 27<div class="node"> 28<a name="fopen"></a> 29<p> 30Next: <a rel="next" accesskey="n" href="fopencookie.html#fopencookie">fopencookie</a>, 31Previous: <a rel="previous" accesskey="p" href="fmemopen.html#fmemopen">fmemopen</a>, 32Up: <a rel="up" accesskey="u" href="Stdio.html#Stdio">Stdio</a> 33<hr> 34</div> 35 36<h3 class="section">4.17 <code>fopen</code>—open a file</h3> 37 38<p><a name="index-fopen-178"></a><a name="index-g_t_005ffopen_005fr-179"></a><strong>Synopsis</strong> 39<pre class="example"> #include <stdio.h> 40 FILE *fopen(const char *<var>file</var>, const char *<var>mode</var>); 41 42 FILE *_fopen_r(struct _reent *<var>reent</var>, 43 const char *<var>file</var>, const char *<var>mode</var>); 44 45</pre> 46 <p><strong>Description</strong><br> 47<code>fopen</code> initializes the data structures needed to read or write a 48file. Specify the file's name as the string at <var>file</var>, and the kind 49of access you need to the file with the string at <var>mode</var>. 50 51 <p>The alternate function <code>_fopen_r</code> is a reentrant version. 52The extra argument <var>reent</var> is a pointer to a reentrancy structure. 53 54 <p>Three fundamental kinds of access are available: read, write, and append. 55<code>*</code><var>mode</var> must begin with one of the three characters `<code>r</code>', 56`<code>w</code>', or `<code>a</code>', to select one of these: 57 58 <dl> 59<dt><code>r</code><dd>Open the file for reading; the operation will fail if the file does 60not exist, or if the host system does not permit you to read it. 61 62 <br><dt><code>w</code><dd>Open the file for writing <em>from the beginning</em> of the file: 63effectively, this always creates a new file. If the file whose name you 64specified already existed, its old contents are discarded. 65 66 <br><dt><code>a</code><dd>Open the file for appending data, that is writing from the end of 67file. When you open a file this way, all data always goes to the 68current end of file; you cannot change this using <code>fseek</code>. 69</dl> 70 71 <p>Some host systems distinguish between “binary” and “text” files. 72Such systems may perform data transformations on data written to, or 73read from, files opened as “text”. 74If your system is one of these, then you can append a `<code>b</code>' to any 75of the three modes above, to specify that you are opening the file as 76a binary file (the default is to open the file as a text file). 77 78 <p>`<code>rb</code>', then, means “read binary”; `<code>wb</code>', “write binary”; and 79`<code>ab</code>', “append binary”. 80 81 <p>To make C programs more portable, the `<code>b</code>' is accepted on all 82systems, whether or not it makes a difference. 83 84 <p>Finally, you might need to both read and write from the same file. 85You can also append a `<code>+</code>' to any of the three modes, to permit 86this. (If you want to append both `<code>b</code>' and `<code>+</code>', you can do it 87in either order: for example, <code>"rb+"</code> means the same thing as 88<code>"r+b"</code> when used as a mode string.) 89 90 <p>Use <code>"r+"</code> (or <code>"rb+"</code>) to permit reading and writing anywhere in 91an existing file, without discarding any data; <code>"w+"</code> (or <code>"wb+"</code>) 92to create a new file (or begin by discarding all data from an old one) 93that permits reading and writing anywhere in it; and <code>"a+"</code> (or 94<code>"ab+"</code>) to permit reading anywhere in an existing file, but writing 95only at the end. 96 97 <p><br> 98<strong>Returns</strong><br> 99<code>fopen</code> returns a file pointer which you can use for other file 100operations, unless the file you requested could not be opened; in that 101situation, the result is <code>NULL</code>. If the reason for failure was an 102invalid string at <var>mode</var>, <code>errno</code> is set to <code>EINVAL</code>. 103 104 <p><br> 105<strong>Portability</strong><br> 106<code>fopen</code> is required by ANSI C. 107 108 <p>Supporting OS subroutines required: <code>close</code>, <code>fstat</code>, <code>isatty</code>, 109<code>lseek</code>, <code>open</code>, <code>read</code>, <code>sbrk</code>, <code>write</code>. 110 111 <p><br> 112 113 </body></html> 114 115