lang/C/the.ansi.c.programming.language/c.programming.notes.int/sx2b.html

   1 <!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
   2 <!-- This collection of hypertext pages is Copyright 1995-7 by Steve Summit. -->
   3 <!-- This material may be freely redistributed and used -->
   4 <!-- but may not be republished or sold without permission. -->
   5 <html>
   6 <head>
   7 <link rev="owner" href="mailto:scs@eskimo.com">
   8 <link rev="made" href="mailto:scs@eskimo.com">
   9 <title>16.2: Opening and Closing Files
  10 (<TT>fopen</TT>, <TT>fclose</TT>, etc.)</title>
  11 <link href="sx2a.html" rev=precedes>
  12 <link href="sx2c.html" rel=precedes>
  13 <link href="sx2.html" rev=subdocument>
  14 </head>
  15 <body>
  16 <H2>16.2: Opening and Closing Files
  17 (<TT>fopen</TT>, <TT>fclose</TT>, etc.)</H2>
  18
  19 <p>As mentioned,
  20 the <TT>fopen</TT> function opens a file
  21 (or perhaps some other I/O object,
  22 if the operating system permits devices to be treated as if they were files)
  23 and returns a stream (<TT>FILE *</TT>)
  24 to be used with later I/O calls.
  25 <TT>fopen</TT>'s <dfn>prototype</dfn>
  26 is
  27 <pre>
  28         FILE *fopen(char *filename, char *mode)
  29 </pre>
  30 For the rest of this chapter,
  31 we'll often use prototype notations like these to describe functions,
  32 since a prototype gives us just the information we need about a function:
  33 its name,
  34 its return type,
  35 and the
  36 types of its arguments
  37 (perhaps along with identifying names for the arguments).
  38 </p><p><TT>fopen</TT>'s prototype tells us
  39 that it returns a <TT>FILE *</TT>,
  40 as we expect,
  41 and that it takes two arguments,
  42 both of type <TT>char *</TT>
  43 (i.e. ``string'').
  44 The first string is the file name,
  45 which can be any string (simple filename or complicated pathname)
  46 which is acceptable to the underlying operating system.
  47 The second string
  48 is the <dfn>mode</dfn> in which the file should be opened.
  49 The simple mode arguments are
  50 </p><UL><li><cw>r</>
  51 open for reading
  52 <li><cw>w</>
  53 open for writing
  54 (truncate file before writing,
  55 if it exists already)
  56 <li><cw>a</>
  57 open for writing,
  58 appending to file if it exists already
  59 </UL>You can also tack two optional modifier characters onto the mode string:
  60 <UL><li><cw>+</>
  61 open for both reading and writing
  62 <li><cw>b</>
  63 open for ``binary'' I/O
  64 </UL>Modes <TT>"r+"</TT> and <TT>"w+"</TT> let you read <em>and</em>  write to the file.
  65 You can't read and write at the same time;
  66 between stints of reading and stints of writing
  67 you must explicitly reposition the read/write
  68 indicator
  69 (see
  70
  71 section 16.9 below).
  72 <p>``Binary'' or <TT>"b"</TT> mode
  73 means that no translations are done by the <TT>stdio</TT> library
  74 when reading or writing the file.
  75 Normally,
  76 the newline character <TT>\n</TT>
  77 is translated to and from
  78 some operating system dependent end-of-line representation
  79 (LF on Unix,
  80 CR on the Macintosh,
  81 CRLF on MS-DOS,
  82 or an end-of-record mark on record-oriented operating systems).
  83 On MS-DOS systems,
  84 without binary mode,
  85 a control-Z character in a file is treated as an end-of-file indication;
  86 neither the control-Z nor any characters following it will be
  87 seen by a program reading the file.
  88
  89 In binary mode,
  90 on the other hand,
  91 characters are read and written verbatim;
  92 newline characters
  93 (and, in MS-DOS, control-Z characters)
  94 are not treated specially.
  95 You need to use binary mode when what you're reading and writing
  96 is arbitrary byte values
  97 which are not to be interpreted as text characters.
  98 </p><p>Of course,
  99 it's possible to use both optional modes:
 100 <TT>"r+b"</TT>, <TT>"w+b"</TT>, etc.
 101 (For
 102 maximum
 103 portability,
 104 it's preferable to put <TT>+</TT> before <TT>b</TT>
 105 in these cases.)
 106
 107 </p><p>If, for any reason,
 108 <TT>fopen</TT> can't open the requested file in the requested mode,
 109 it returns a null pointer (<TT>NULL</TT>).
 110 Whenever you call <TT>fopen</TT>,
 111 you must check that the returned file pointer is not null
 112 <em>before</em> attempting to use
 113 the pointer
 114 for any I/O.
 115 </p><p>Most operating systems
 116 let you keep only a limited number of files open at a time.
 117 Also,
 118 many versions of the stdio library
 119 allocate only a limited number of <TT>FILE</TT> structures
 120 for <TT>fopen</TT> to return pointers to.
 121 Therefore,
 122 if a program opens many files in sequence,
 123 it's important for it to <dfn>close</dfn> them as it finishes with them.
 124 Closing a file <TT>fp</TT> simply requires calling <TT>fclose(fp)</TT>.
 125 (Any open streams are automatically closed when the program exits normally.)
 126
 127 </p><p>The standard I/O library normally <dfn>buffers</dfn>
 128 characters--that is,
 129 when you're writing, it saves up a chunk of characters and then
 130 writes them to the actual file all at once;
 131 and when you're reading,
 132 it reads a chunk of characters from the file
 133 all at once
 134 and them parcels
 135 them out to the program one at a time
 136 (or as many characters at a time as
 137 the program asks for).
 138 The reasons for buffering have to do with efficiency--the
 139 calls to the underlying operating system which request it to
 140 read and write files may be inefficient if called once for each
 141 character or each few characters,
 142 and may be much more efficient if they're always called for large
 143 blocks of characters.
 144 Normally, buffering is transparent to your program,
 145 but occasionally it's necessary to ensure that some characters
 146 have actually been written.
 147 (One example is when you've printed a prompt to the standard
 148 output, and you want to be sure that it's actually been written
 149 to the screen.)
 150 In these cases, you can call <TT>fflush(fp)</TT>,
 151 which flushes
 152 a stream's
 153 buffered output to the underlying file
 154 (or screen, or other device).
 155 Naturally, the library automatically flushes output when you
 156 call <TT>fclose</TT> on a stream,
 157 and also when your program exits.
 158 </p><p>(<TT>fflush</TT> is only defined for output streams.
 159 There is no standard way to discard unread, buffered input.)
 160 </p><hr>
 161 <p>
 162 Read sequentially:
 163 <a href="sx2a.html" rev=precedes>prev</a>
 164 <a href="sx2c.html" rel=precedes>next</a>
 165 <a href="sx2.html" rev=subdocument>up</a>
 166 <a href="top.html">top</a>
 167 </p>
 168 <p>
 169 This page by <a href="http://www.eskimo.com/~scs/">Steve Summit</a>
 170 // <a href="copyright.html">Copyright</a> 1996-1999
 171 // <a href="mailto:scs@eskimo.com">mail feedback</a>
 172 </p>
 173 </body>
 174 </html>