C/the.ansi.c.programming.language/c.programming.notes.int/sx2d.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.4: Line Input and Output
  10 (<TT>fgets</TT>, <TT>fputs</TT>, etc.)</title>
  11 <link href="sx2c.html" rev=precedes>
  12 <link href="sx2e.html" rel=precedes>
  13 <link href="sx2.html" rev=subdocument>
  14 </head>
  15 <body>
  16 <H2>16.4: Line Input and Output
  17 (<TT>fgets</TT>, <TT>fputs</TT>, etc.)</H2>
  18
  19 <p>The function
  20 <pre>
  21         char *gets(char *line)
  22 </pre>
  23 reads the next line of text
  24 (i.e. up to the next <TT>\n</TT>)
  25 from the standard input
  26 and places the characters
  27 (except for the <TT>\n</TT>)
  28 in the character array
  29
  30 pointed to by <TT>line</TT>.
  31 It returns a pointer to the line
  32 (that is,
  33 it returns the same pointer value you gave it),
  34 unless it reaches end-of-file,
  35 in which case it returns a null pointer.
  36 It is assumed that <TT>line</TT> points to enough memory
  37 to hold all of the characters read,
  38 plus a terminating <TT>\0</TT>
  39 (so that the line will be usable as a string).
  40 Since there's usually no way for anyone to guarantee
  41 that the array is big enough,
  42 and no way
  43 for <TT>gets</TT>
  44 to check it,
  45 <TT>gets</TT> is actually a useless function,
  46 and no serious program should call it.
  47 </p><p>The function
  48 <pre>
  49         char *fgets(char *line, int max, FILE *fp)
  50 </pre>
  51 is somewhat more useful.
  52 It reads the next line of input from the stream <TT>fp</TT>
  53 and places the characters,
  54 <em>including</em> the <TT>\n</TT>,
  55 in the character array pointed to by <TT>line</TT>.
  56 The second argument, <TT>max</TT>,
  57 gives the maximum number of characters to be written to the array,
  58 and is usually the size of the array.
  59 Like <TT>gets</TT>,
  60 <TT>fgets</TT> returns a pointer to the line it reads,
  61 or a null pointer if it reaches end-of-file.
  62
  63 Unlike <TT>gets</TT>,
  64 <TT>fgets</TT> does include the <TT>\n</TT>
  65 in the string it copies to the array.
  66 Therefore,
  67 the number of characters in the line,
  68 plus
  69 the <TT>\n</TT>,
  70 plus
  71 the <TT>\0</TT>,
  72 will always be less than or equal to <TT>max</TT>.
  73 (If <TT>fgets</TT> reads <TT>max-1</TT> characters
  74 without finding a <TT>\n</TT>,
  75 it stops reading there,
  76 copies a <TT>\0</TT> to the last element of the array,
  77 and leaves the rest of the line to be read next time.)
  78 Since <TT>fgets</TT> does let you guarantee
  79 that the line being read won't go off the end of the array,
  80 you should always use <TT>fgets</TT> instead of <TT>gets</TT>.
  81 (If you want to read a line from standard input,
  82 you can just pass the constant <TT>stdin</TT> as the third argument.)
  83 If you'd rather not have the <TT>\n</TT> retained in the input line,
  84 you can either remove it right after calling <TT>fgets</TT>
  85 (perhaps by calling <TT>strchr</TT>
  86 and overwriting the <TT>\n</TT> with a <TT>\0</TT>),
  87 or maybe call the <TT>getline</TT> or <TT>fgetline</TT>
  88
  89 function we've been using instead.
  90 (See chapters
  91
  92 6
  93 and
  94
  95 12;
  96 these functions are also handy
  97 in that they return the length of the line read.
  98 They differ from <TT>fgets</TT> in their treatment of overlong lines,
  99 though.)
 100 </p><p>The function
 101 <pre>
 102         int puts(char *line)
 103 </pre>
 104 writes the string pointed to by <TT>line</TT> to the standard output,
 105 and writes a <TT>\n</TT> to terminate it.
 106 It returns a nonnegative value
 107 (we don't really care what the value is)
 108 unless there's some kind of a write error,
 109 in which case it returns <TT>EOF</TT>.
 110 </p><p>Finally,
 111 the function
 112 <pre>
 113         int fputs(char *line, FILE *fp)
 114 </pre>
 115 writes the string pointed to by <TT>line</TT>
 116 to the stream <TT>fp</TT>.
 117 Like <TT>puts</TT>,
 118 <TT>fputs</TT> returns a nonnegative value
 119 or <TT>EOF</TT> on error.
 120 Unlike <TT>puts</TT>,
 121 <TT>fputs</TT> does <em>not</em> automatically append a <TT>\n</TT>.
 122 </p><hr>
 123 <p>
 124 Read sequentially:
 125 <a href="sx2c.html" rev=precedes>prev</a>
 126 <a href="sx2e.html" rel=precedes>next</a>
 127 <a href="sx2.html" rev=subdocument>up</a>
 128 <a href="top.html">top</a>
 129 </p>
 130 <p>
 131 This page by <a href="http://www.eskimo.com/~scs/">Steve Summit</a>
 132 // <a href="copyright.html">Copyright</a> 1996-1999
 133 // <a href="mailto:scs@eskimo.com">mail feedback</a>
 134 </p>
 135 </body>
 136 </html>