C/the.ansi.c.programming.language/c.programming.notes.int/sx2g.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.7: Arbitrary Input and Output
  10 (<TT>fread</TT>, <TT>fwrite</TT>)</title>
  11 <link href="sx2f.html" rev=precedes>
  12 <link href="sx2h.html" rel=precedes>
  13 <link href="sx2.html" rev=subdocument>
  14 </head>
  15 <body>
  16 <H2>16.7: Arbitrary Input and Output
  17 (<TT>fread</TT>, <TT>fwrite</TT>)</H2>
  18
  19 <p>Sometimes,
  20 you want to read a chunk of characters,
  21 without treating it as a ``line''
  22 (as <TT>gets</TT> and <TT>fgets</TT> do)
  23 and certainly without doing any <TT>scanf</TT>-like parsing.
  24 Similarly,
  25 you may want to write an arbitrary chunk of characters,
  26 not as a string or a line.
  27 (Furthermore, the chunk might contain
  28 one or more <TT>\0</TT> characters
  29 which would otherwise terminate a string.)
  30 In these situations,
  31 you want <TT>fread</TT> and <TT>fwrite</TT>.
  32 </p><p><TT>fread</TT>'s prototype is
  33 <pre>
  34         size_t fread(void *buf, size_t sz, size_t n, FILE *fp)
  35 </pre>
  36 Remember,
  37 <TT>void *</TT> is a ``generic'' pointer type
  38 (the type returned by <TT>malloc</TT>),
  39 which can point to anything.
  40 It may make it easier to think about <TT>fread</TT> at first
  41 if you imagine that its first argument were <TT>char *</TT>.
  42 <TT>size_t</TT> is a type we haven't met yet;
  43 it's a type that's guaranteed to be able to hold
  44 the size of any object
  45 (i.e. as returned by the <TT>sizeof</TT> operator);
  46 you can imagine for the moment that it's <TT>unsigned int</TT>.
  47 <TT>fread</TT> reads up to <TT>n</TT> objects,
  48 each of size <TT>sz</TT>,
  49 from the stream <TT>fp</TT>,
  50 and copies them to the buffer pointed to by <TT>buf</TT>.
  51 It reads them as a stream of bytes,
  52 without doing any particular formatting or other interpretation.
  53 (However, the default underlying stdio machinery
  54 may still translate
  55
  56 newline characters
  57 unless the stream is open in binary or <TT>"b"</TT> mode).
  58 <TT>fread</TT>
  59 returns the number of items read.
  60 It returns 0
  61 (not <TT>EOF</TT>)
  62
  63 at end-of-file.
  64 </p><p>Similarly,
  65 the prototype for <TT>fwrite</TT> is
  66 <pre>
  67         size_t fwrite(void *buf, size_t sz, size_t n, FILE *fp)
  68 </pre>
  69 <pre>
  70 </pre>
  71 </p><p><TT>fread</TT> and <TT>fwrite</TT> are intended to write chunks
  72 or ``arrays'' of items,
  73 with the interpretation that there are <TT>n</TT> items
  74 each of size <TT>sz</TT>.
  75 If what you want to do is read <I>n</I> characters,
  76 you can call <TT>fread</TT> with <TT>sz</TT> as 1,
  77 and <TT>buf</TT> pointing to an array of at least <I>n</I> characters.
  78
  79 The return value will be in units of characters.
  80 (Of course,
  81 you could write <I>n</I> characters
  82 by using similar arguments with <TT>fwrite</TT>.)
  83 </p><p>Besides reading and writing ``blocks'' of characters,
  84 you can use <TT>fread</TT> and <TT>fwrite</TT>
  85 to do ``binary'' I/O.
  86 For example,
  87 if you have an array of <TT>int</TT> values:
  88 <pre>
  89         int array[N];
  90 </pre>
  91 you could write them all out at once by calling
  92 <pre>
  93         fwrite(array, sizeof(int), N, fp);
  94 </pre>
  95 This
  96
  97 would write them all out in a byte-for-byte way,
  98 i.e. as a block copy of bytes from memory to the output stream,
  99 i.e. <em>not</em> as strings of digits
 100 as <TT>printf</TT> <TT>%d</TT> would.
 101 Since some of the bytes within the array of <TT>int</TT>
 102 might have the same value as the <TT>\n</TT> character,
 103 you would want to make sure that you had opened the stream
 104 in binary or <TT>"wb"</TT> mode when calling <TT>fopen</TT>.
 105 </p><p>Later,
 106 you could try to read the integers in by calling
 107 <pre>
 108         fread(array, sizeof(int), N, fp);
 109 </pre>
 110 </p><p>Similarly,
 111 if you had a variable of some structure type:
 112 <pre>
 113         struct somestruct x;
 114 </pre>
 115 you could write it out all at once by calling
 116 <pre>
 117         fwrite(&amp;x, sizeof(struct somestruct), 1, fp);
 118 </pre>
 119 and read it in by calling
 120 <pre>
 121         fread(&amp;x, sizeof(struct somestruct), 1, fp);
 122 </pre>
 123 </p><p>Although this ``binary'' I/O
 124 using <TT>fwrite</TT> and <TT>fread</TT>
 125 looks easy and convenient,
 126 it has a number of drawbacks,
 127 some of which we'll discuss in the next chapter.
 128 </p><hr>
 129 <p>
 130 Read sequentially:
 131 <a href="sx2f.html" rev=precedes>prev</a>
 132 <a href="sx2h.html" rel=precedes>next</a>
 133 <a href="sx2.html" rev=subdocument>up</a>
 134 <a href="top.html">top</a>
 135 </p>
 136 <p>
 137 This page by <a href="http://www.eskimo.com/~scs/">Steve Summit</a>
 138 // <a href="copyright.html">Copyright</a> 1996-1999
 139 // <a href="mailto:scs@eskimo.com">mail feedback</a>
 140 </p>
 141 </body>
 142 </html>