| <html lang="en"> |
| <head> |
| <title>Opening Streams - The GNU C Library</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="The GNU C Library"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="I_002fO-on-Streams.html#I_002fO-on-Streams" title="I/O on Streams"> |
| <link rel="prev" href="Standard-Streams.html#Standard-Streams" title="Standard Streams"> |
| <link rel="next" href="Closing-Streams.html#Closing-Streams" title="Closing Streams"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| This file documents the GNU C library. |
| |
| This is Edition 0.12, last updated 2007-10-27, |
| of `The GNU C Library Reference Manual', for version |
| 2.8 (Sourcery G++ Lite 2011.03-41). |
| |
| Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, |
| 2003, 2007, 2008, 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software Needs Free Documentation'' |
| and ``GNU Lesser General Public License'', the Front-Cover texts being |
| ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A |
| copy of the license is included in the section entitled "GNU Free |
| Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: ``You have the freedom to |
| copy and modify this GNU manual. Buying copies from the FSF |
| supports it in developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Opening-Streams"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Closing-Streams.html#Closing-Streams">Closing Streams</a>, |
| Previous: <a rel="previous" accesskey="p" href="Standard-Streams.html#Standard-Streams">Standard Streams</a>, |
| Up: <a rel="up" accesskey="u" href="I_002fO-on-Streams.html#I_002fO-on-Streams">I/O on Streams</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">12.3 Opening Streams</h3> |
| |
| <p><a name="index-opening-a-stream-927"></a>Opening a file with the <code>fopen</code> function creates a new stream and |
| establishes a connection between the stream and a file. This may |
| involve creating a new file. |
| |
| <p><a name="index-stdio_002eh-928"></a>Everything described in this section is declared in the header file |
| <samp><span class="file">stdio.h</span></samp>. |
| |
| <!-- stdio.h --> |
| <!-- ISO --> |
| <div class="defun"> |
| — Function: FILE * <b>fopen</b> (<var>const char *filename, const char *opentype</var>)<var><a name="index-fopen-929"></a></var><br> |
| <blockquote><p>The <code>fopen</code> function opens a stream for I/O to the file |
| <var>filename</var>, and returns a pointer to the stream. |
| |
| <p>The <var>opentype</var> argument is a string that controls how the file is |
| opened and specifies attributes of the resulting stream. It must begin |
| with one of the following sequences of characters: |
| |
| <dl> |
| <dt>‘<samp><span class="samp">r</span></samp>’<dd>Open an existing file for reading only. |
| |
| <br><dt>‘<samp><span class="samp">w</span></samp>’<dd>Open the file for writing only. If the file already exists, it is |
| truncated to zero length. Otherwise a new file is created. |
| |
| <br><dt>‘<samp><span class="samp">a</span></samp>’<dd>Open a file for append access; that is, writing at the end of file only. |
| If the file already exists, its initial contents are unchanged and |
| output to the stream is appended to the end of the file. |
| Otherwise, a new, empty file is created. |
| |
| <br><dt>‘<samp><span class="samp">r+</span></samp>’<dd>Open an existing file for both reading and writing. The initial contents |
| of the file are unchanged and the initial file position is at the |
| beginning of the file. |
| |
| <br><dt>‘<samp><span class="samp">w+</span></samp>’<dd>Open a file for both reading and writing. If the file already exists, it |
| is truncated to zero length. Otherwise, a new file is created. |
| |
| <br><dt>‘<samp><span class="samp">a+</span></samp>’<dd>Open or create file for both reading and appending. If the file exists, |
| its initial contents are unchanged. Otherwise, a new file is created. |
| The initial file position for reading is at the beginning of the file, |
| but output is always appended to the end of the file. |
| </dl> |
| |
| <p>As you can see, ‘<samp><span class="samp">+</span></samp>’ requests a stream that can do both input and |
| output. The ISO standard says that when using such a stream, you must |
| call <code>fflush</code> (see <a href="Stream-Buffering.html#Stream-Buffering">Stream Buffering</a>) or a file positioning |
| function such as <code>fseek</code> (see <a href="File-Positioning.html#File-Positioning">File Positioning</a>) when switching |
| from reading to writing or vice versa. Otherwise, internal buffers |
| might not be emptied properly. The GNU C library does not have this |
| limitation; you can do arbitrary reading and writing operations on a |
| stream in whatever order. |
| |
| <p>Additional characters may appear after these to specify flags for the |
| call. Always put the mode (‘<samp><span class="samp">r</span></samp>’, ‘<samp><span class="samp">w+</span></samp>’, etc.) first; that is |
| the only part you are guaranteed will be understood by all systems. |
| |
| <p>The GNU C library defines one additional character for use in |
| <var>opentype</var>: the character ‘<samp><span class="samp">x</span></samp>’ insists on creating a new |
| file—if a file <var>filename</var> already exists, <code>fopen</code> fails |
| rather than opening it. If you use ‘<samp><span class="samp">x</span></samp>’ you are guaranteed that |
| you will not clobber an existing file. This is equivalent to the |
| <code>O_EXCL</code> option to the <code>open</code> function (see <a href="Opening-and-Closing-Files.html#Opening-and-Closing-Files">Opening and Closing Files</a>). |
| |
| <p>The character ‘<samp><span class="samp">b</span></samp>’ in <var>opentype</var> has a standard meaning; it |
| requests a binary stream rather than a text stream. But this makes no |
| difference in POSIX systems (including the GNU system). If both |
| ‘<samp><span class="samp">+</span></samp>’ and ‘<samp><span class="samp">b</span></samp>’ are specified, they can appear in either order. |
| See <a href="Binary-Streams.html#Binary-Streams">Binary Streams</a>. |
| |
| <p><a name="index-stream-orientation-930"></a><a name="index-orientation_002c-stream-931"></a>If the <var>opentype</var> string contains the sequence |
| <code>,ccs=</code><var>STRING</var> then <var>STRING</var> is taken as the name of a |
| coded character set and <code>fopen</code> will mark the stream as |
| wide-oriented which appropriate conversion functions in place to convert |
| from and to the character set <var>STRING</var> is place. Any other stream |
| is opened initially unoriented and the orientation is decided with the |
| first file operation. If the first operation is a wide character |
| operation, the stream is not only marked as wide-oriented, also the |
| conversion functions to convert to the coded character set used for the |
| current locale are loaded. This will not change anymore from this point |
| on even if the locale selected for the <code>LC_CTYPE</code> category is |
| changed. |
| |
| <p>Any other characters in <var>opentype</var> are simply ignored. They may be |
| meaningful in other systems. |
| |
| <p>If the open fails, <code>fopen</code> returns a null pointer. |
| |
| <p>When the sources are compiling with <code>_FILE_OFFSET_BITS == 64</code> on a |
| 32 bit machine this function is in fact <code>fopen64</code> since the LFS |
| interface replaces transparently the old interface. |
| </p></blockquote></div> |
| |
| <p>You can have multiple streams (or file descriptors) pointing to the same |
| file open at the same time. If you do only input, this works |
| straightforwardly, but you must be careful if any output streams are |
| included. See <a href="Stream_002fDescriptor-Precautions.html#Stream_002fDescriptor-Precautions">Stream/Descriptor Precautions</a>. This is equally true |
| whether the streams are in one program (not usual) or in several |
| programs (which can easily happen). It may be advantageous to use the |
| file locking facilities to avoid simultaneous access. See <a href="File-Locks.html#File-Locks">File Locks</a>. |
| |
| <!-- stdio.h --> |
| <!-- Unix98 --> |
| <div class="defun"> |
| — Function: FILE * <b>fopen64</b> (<var>const char *filename, const char *opentype</var>)<var><a name="index-fopen64-932"></a></var><br> |
| <blockquote><p>This function is similar to <code>fopen</code> but the stream it returns a |
| pointer for is opened using <code>open64</code>. Therefore this stream can be |
| used even on files larger then 2^31 bytes on 32 bit machines. |
| |
| <p>Please note that the return type is still <code>FILE *</code>. There is no |
| special <code>FILE</code> type for the LFS interface. |
| |
| <p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a 32 |
| bits machine this function is available under the name <code>fopen</code> |
| and so transparently replaces the old interface. |
| </p></blockquote></div> |
| |
| <!-- stdio.h --> |
| <!-- ISO --> |
| <div class="defun"> |
| — Macro: int <b>FOPEN_MAX</b><var><a name="index-FOPEN_005fMAX-933"></a></var><br> |
| <blockquote><p>The value of this macro is an integer constant expression that |
| represents the minimum number of streams that the implementation |
| guarantees can be open simultaneously. You might be able to open more |
| than this many streams, but that is not guaranteed. The value of this |
| constant is at least eight, which includes the three standard streams |
| <code>stdin</code>, <code>stdout</code>, and <code>stderr</code>. In POSIX.1 systems this |
| value is determined by the <code>OPEN_MAX</code> parameter; see <a href="General-Limits.html#General-Limits">General Limits</a>. In BSD and GNU, it is controlled by the <code>RLIMIT_NOFILE</code> |
| resource limit; see <a href="Limits-on-Resources.html#Limits-on-Resources">Limits on Resources</a>. |
| </p></blockquote></div> |
| |
| <!-- stdio.h --> |
| <!-- ISO --> |
| <div class="defun"> |
| — Function: FILE * <b>freopen</b> (<var>const char *filename, const char *opentype, FILE *stream</var>)<var><a name="index-freopen-934"></a></var><br> |
| <blockquote><p>This function is like a combination of <code>fclose</code> and <code>fopen</code>. |
| It first closes the stream referred to by <var>stream</var>, ignoring any |
| errors that are detected in the process. (Because errors are ignored, |
| you should not use <code>freopen</code> on an output stream if you have |
| actually done any output using the stream.) Then the file named by |
| <var>filename</var> is opened with mode <var>opentype</var> as for <code>fopen</code>, |
| and associated with the same stream object <var>stream</var>. |
| |
| <p>If the operation fails, a null pointer is returned; otherwise, |
| <code>freopen</code> returns <var>stream</var>. |
| |
| <p><code>freopen</code> has traditionally been used to connect a standard stream |
| such as <code>stdin</code> with a file of your own choice. This is useful in |
| programs in which use of a standard stream for certain purposes is |
| hard-coded. In the GNU C library, you can simply close the standard |
| streams and open new ones with <code>fopen</code>. But other systems lack |
| this ability, so using <code>freopen</code> is more portable. |
| |
| <p>When the sources are compiling with <code>_FILE_OFFSET_BITS == 64</code> on a |
| 32 bit machine this function is in fact <code>freopen64</code> since the LFS |
| interface replaces transparently the old interface. |
| </p></blockquote></div> |
| |
| <!-- stdio.h --> |
| <!-- Unix98 --> |
| <div class="defun"> |
| — Function: FILE * <b>freopen64</b> (<var>const char *filename, const char *opentype, FILE *stream</var>)<var><a name="index-freopen64-935"></a></var><br> |
| <blockquote><p>This function is similar to <code>freopen</code>. The only difference is that |
| on 32 bit machine the stream returned is able to read beyond the |
| 2^31 bytes limits imposed by the normal interface. It should be |
| noted that the stream pointed to by <var>stream</var> need not be opened |
| using <code>fopen64</code> or <code>freopen64</code> since its mode is not important |
| for this function. |
| |
| <p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a 32 |
| bits machine this function is available under the name <code>freopen</code> |
| and so transparently replaces the old interface. |
| </p></blockquote></div> |
| |
| <p>In some situations it is useful to know whether a given stream is |
| available for reading or writing. This information is normally not |
| available and would have to be remembered separately. Solaris |
| introduced a few functions to get this information from the stream |
| descriptor and these functions are also available in the GNU C library. |
| |
| <!-- stdio_ext.h --> |
| <!-- GNU --> |
| <div class="defun"> |
| — Function: int <b>__freadable</b> (<var>FILE *stream</var>)<var><a name="index-g_t_005f_005ffreadable-936"></a></var><br> |
| <blockquote><p>The <code>__freadable</code> function determines whether the stream |
| <var>stream</var> was opened to allow reading. In this case the return value |
| is nonzero. For write-only streams the function returns zero. |
| |
| <p>This function is declared in <samp><span class="file">stdio_ext.h</span></samp>. |
| </p></blockquote></div> |
| |
| <!-- stdio_ext.h --> |
| <!-- GNU --> |
| <div class="defun"> |
| — Function: int <b>__fwritable</b> (<var>FILE *stream</var>)<var><a name="index-g_t_005f_005ffwritable-937"></a></var><br> |
| <blockquote><p>The <code>__fwritable</code> function determines whether the stream |
| <var>stream</var> was opened to allow writing. In this case the return value |
| is nonzero. For read-only streams the function returns zero. |
| |
| <p>This function is declared in <samp><span class="file">stdio_ext.h</span></samp>. |
| </p></blockquote></div> |
| |
| <p>For slightly different kind of problems there are two more functions. |
| They provide even finer-grained information. |
| |
| <!-- stdio_ext.h --> |
| <!-- GNU --> |
| <div class="defun"> |
| — Function: int <b>__freading</b> (<var>FILE *stream</var>)<var><a name="index-g_t_005f_005ffreading-938"></a></var><br> |
| <blockquote><p>The <code>__freading</code> function determines whether the stream |
| <var>stream</var> was last read from or whether it is opened read-only. In |
| this case the return value is nonzero, otherwise it is zero. |
| Determining whether a stream opened for reading and writing was last |
| used for writing allows to draw conclusions about the content about the |
| buffer, among other things. |
| |
| <p>This function is declared in <samp><span class="file">stdio_ext.h</span></samp>. |
| </p></blockquote></div> |
| |
| <!-- stdio_ext.h --> |
| <!-- GNU --> |
| <div class="defun"> |
| — Function: int <b>__fwriting</b> (<var>FILE *stream</var>)<var><a name="index-g_t_005f_005ffwriting-939"></a></var><br> |
| <blockquote><p>The <code>__fwriting</code> function determines whether the stream |
| <var>stream</var> was last written to or whether it is opened write-only. In |
| this case the return value is nonzero, otherwise it is zero. |
| |
| <p>This function is declared in <samp><span class="file">stdio_ext.h</span></samp>. |
| </p></blockquote></div> |
| |
| </body></html> |
| |
