Back to Chapter 6 --  Index --  Chapter 8

Chapter 7 - Input and Output

The ANSI standard defines these library functions precisely, so that they can exist in compatible form on any system where C exists. Programs that confine their system interactions to facilities provided by the standard library can be moved from one system to another without change.

The properties of library functions are specified in more than a dozen headers; we have already seen several of these, including <stdio.h>, <string.h>, and <ctype.h>. We will not present the entire library here, since we are more interested in writing C programs that use it. The library is described in detail in Appendix B.

7.1 Standard Input and Output

The simplest input mechanism is to read one character at a time from the standard input, normally the keyboard, with getchar:

   int getchar(void)

In many environments, a file may be substituted for the keyboard by using the < convention for input redirection: if a program prog uses getchar, then the command line

   prog <infile

   otherprog | prog

The function

   int putchar(int)

   prog >outfile

   prog | anotherprog

Output produced by printf also finds its way to the standard output. Calls to putchar and printf may be interleaved - output happens in the order in which the calls are made.

Each source file that refers to an input/output library function must contain the line

   #include <stdio.h>

Many programs read only one input stream and write only one output stream; for such programs, input and output with getchar, putchar, and printf may be entirely adequate, and is certainly enough to get started. This is particularly true if redirection is used to connect the output of one program to the input of the next. For example, consider the program lower, which converts its input to lower case:

   #include <stdio.h>
   #include <ctype.h>

   main() /* lower: convert input to lower case*/
   {
       int c

       while ((c = getchar()) != EOF)
           putchar(tolower(c));
       return 0;
   }

Exercise 7-1. Write a program that converts upper case to lower or lower case to upper, depending on the name it is invoked with, as found in argv[0].

7.2 Formatted Output - printf

   int printf(char *format, arg1, arg2, ...);

The format string contains two types of objects: ordinary characters, which are copied to the output stream, and conversion specifications, each of which causes conversion and printing of the next successive argument to printf. Each conversion specification begins with a % and ends with a conversion character. Between the % and the conversion character there may be, in order:

• A minus sign, which specifies left adjustment of the converted argument.
• A number that specifies the minimum field width. The converted argument will be printed in a field at least this wide. If necessary it will be padded on the left (or right, if left adjustment is called for) to make up the field width.
• A period, which separates the field width from the precision.
• A number, the precision, that specifies the maximum number of characters to be printed from a string, or the number of digits after the decimal point of a floating-point value, or the minimum number of digits for an integer.
• An h if the integer is to be printed as a short, or l (letter ell) if as a long.

Table 7.1 Basic Printf Conversions

Character	Argument type; Printed As
d,i	int; decimal number
o	int; unsigned octal number (without a leading zero)
x,X	int; unsigned hexadecimal number (without a leading 0x or 0X), using abcdef or ABCDEF for 10, ...,15.
u	int; unsigned decimal number
c	int; single character
s	char *; print characters from the string until a '\0' or the number of characters given by the precision.
f	double; [-]m.dddddd, where the number of d's is given by the precision (default 6).
e,E	double; [-]m.dddddde+/-xx or [-]m.ddddddE+/-xx, where the number of d's is given by the precision (default 6).
g,G	double; use %e or %E if the exponent is less than -4 or greater than or equal to the precision; otherwise use %f. Trailing zeros and a trailing decimal point are not printed.
p	void *; pointer (implementation-dependent representation).
%	no argument is converted; print a %

A width or precision may be specified as *, in which case the value is computed by converting the next argument (which must be an int). For example, to print at most max characters from a string s,

   printf("%.*s", max, s);

   :%s:          :hello, world:
   :%10s:        :hello, world:
   :%.10s:       :hello, wor:
   :%-10s:       :hello, world:
   :%.15s:       :hello, world:
   :%-15s:       :hello, world   :
   :%15.10s:     :     hello, wor:
   :%-15.10s:    :hello, wor     :

   printf(s);         /* FAILS if s contains % */
   printf("%s", s);   /* SAFE */

   int sprintf(char *string, char *format, arg1, arg2, ...);

Exercise 7-2. Write a program that will print arbitrary input in a sensible way. As a minimum, it should print non-graphic characters in octal or hexadecimal according to local custom, and break long text lines.

7.3 Variable-length Argument Lists

The proper declaration for printf is

   int printf(char *fmt, ...)

   void minprintf(char *fmt, ...)

The tricky bit is how minprintf walks along the argument list when the list doesn't even have a name. The standard header <stdarg.h> contains a set of macro definitions that define how to step through an argument list. The implementation of this header will vary from machine to machine, but the interface it presents is uniform.

The type va_list is used to declare a variable that will refer to each argument in turn; in minprintf, this variable is called ap, for ``argument pointer.'' The macro va_start initializes ap to point to the first unnamed argument. It must be called once before ap is used. There must be at least one named argument; the final named argument is used by va_start to get started.

Each call of va_arg returns one argument and steps ap to the next; va_arg uses a type name to determine what type to return and how big a step to take. Finally, va_end does whatever cleanup is necessary. It must be called before the program returns.

These properties form the basis of our simplified printf:

   #include <stdarg.h>

   /* minprintf: minimal printf with variable argument list */
   void minprintf(char *fmt, ...)
   {
       va_list ap; /* points to each unnamed arg in turn */
       char *p, *sval;
       int ival;
       double dval;

       va_start(ap, fmt); /* make ap point to 1st unnamed arg */
       for (p = fmt; *p; p++) {
           if (*p != '%') {
               putchar(*p);
               continue;
           }
           switch (*++p) {
           case 'd':
               ival = va_arg(ap, int);
               printf("%d", ival);
               break;
           case 'f':
               dval = va_arg(ap, double);
               printf("%f", dval);
               break;
           case 's':
               for (sval = va_arg(ap, char *); *sval; sval++)
                   putchar(*sval);
               break;
           default:
               putchar(*p);
               break;
           }
       }
       va_end(ap); /* clean up when done */
   }

7.4 Formatted Input - Scanf

   int scanf(char *format, ...)

scanf stops when it exhausts its format string, or when some input fails to match the control specification. It returns as its value the number of successfully matched and assigned input items. This can be used to decide how many items were found. On the end of file, EOF is returned; note that this is different from 0, which means that the next input character does not match the first specification in the format string. The next call to scanf resumes searching immediately after the last character already converted.

There is also a function sscanf that reads from a string instead of the standard input:

   int sscanf(char *string, char *format, arg1, arg2, ...)

The format string usually contains conversion specifications, which are used to control conversion of input. The format string may contain:

• Blanks or tabs, which are not ignored.
• Ordinary characters (not %), which are expected to match the next non-white space character of the input stream.
• Conversion specifications, consisting of the character %, an optional assignment suppression character *, an optional number specifying a maximum field width, an optional h, l or L indicating the width of the target, and a conversion character.

The conversion character indicates the interpretation of the input field. The corresponding argument must be a pointer, as required by the call-by-value semantics of C. Conversion characters are shown in Table 7.2.

Table 7.2: Basic Scanf Conversions

Character	Input Data; Argument type
d	decimal integer; int *
i	integer; int *. The integer may be in octal (leading 0) or hexadecimal (leading 0x or 0X).
o	octal integer (with or without leading zero); int *
u	unsigned decimal integer; unsigned int *
x	hexadecimal integer (with or without leading 0x or 0X); int *
c	characters; char *. The next input characters (default 1) are placed at the indicated spot. The normal skip-over white space is suppressed; to read the next non-white space character, use %1s
s	character string (not quoted); char *, pointing to an array of characters long enough for the string and a terminating '\0' that will be added.
e,f,g	floating-point number with optional sign, optional decimal point and optional exponent; float *
%	literal %; no assignment is made.

The conversion characters d, i, o, u, and x may be preceded by h to indicate that a pointer to short rather than int appears in the argument list, or by l (letter ell) to indicate that a pointer to long appears in the argument list.

As a first example, the rudimentary calculator of Chapter 4 can be written with scanf to do the input conversion:

   #include <stdio.h>

   main()  /* rudimentary calculator */
   {
       double sum, v;

       sum = 0;
       while (scanf("%lf", &v) == 1)
           printf("\t%.2f\n", sum += v);
       return 0;
   }

   25 Dec 1988

   int day, year;
   char monthname[20];

   scanf("%d %s %d", &day, monthname, &year);

Literal characters can appear in the scanf format string; they must match the same characters in the input. So we could read dates of the form mm/dd/yy with the scanf statement:

   int day, month, year;

   scanf("%d/%d/%d", &month, &day, &year);

   while (getline(line, sizeof(line)) > 0) {
       if (sscanf(line, "%d %s %d", &day, monthname, &year) == 3)
           printf("valid: %s\n", line); /* 25 Dec 1988 form */
       else if (sscanf(line, "%d/%d/%d", &month, &day, &year) == 3)
           printf("valid: %s\n", line); /* mm/dd/yy form */
       else
           printf("invalid: %s\n", line); /* invalid form */
   }

A final warning: the arguments to scanf and sscanf must be pointers. By far the most common error is writing

   scanf("%d", n);

   scanf("%d", &n);

Exercise 7-4. Write a private version of scanf analogous to minprintf from the previous section.

Exercise 5-5. Rewrite the postfix calculator of Chapter 4 to use scanf and/or sscanf to do the input and number conversion.

7.5 File Access

The next step is to write a program that accesses a file that is not already connected to the program. One program that illustrates the need for such operations is cat, which concatenates a set of named files into the standard output. cat is used for printing files on the screen, and as a general-purpose input collector for programs that do not have the capability of accessing files by name. For example, the command

   cat x.c y.c

The question is how to arrange for the named files to be read - that is, how to connect the external names that a user thinks of to the statements that read the data.

The rules are simple. Before it can be read or written, a file has to be opened by the library function fopen. fopen takes an external name like x.c or y.c, does some housekeeping and negotiation with the operating system (details of which needn't concern us), and returns a pointer to be used in subsequent reads or writes of the file.

This pointer, called the file pointer, points to a structure that contains information about the file, such as the location of a buffer, the current character position in the buffer, whether the file is being read or written, and whether errors or end of file have occurred. Users don't need to know the details, because the definitions obtained from <stdio.h> include a structure declaration called FILE. The only declaration needed for a file pointer is exemplified by

   FILE *fp;
   FILE *fopen(char *name, char *mode);

The call to fopen in a program is

   fp = fopen(name, mode);

If a file that does not exist is opened for writing or appending, it is created if possible. Opening an existing file for writing causes the old contents to be discarded, while opening for appending preserves them. Trying to read a file that does not exist is an error, and there may be other causes of error as well, like trying to read a file when you don't have permission. If there is any error, fopen will return NULL. (The error can be identified more precisely; see the discussion of error-handling functions at the end of Section 1 in Appendix B.)

The next thing needed is a way to read or write the file once it is open. getc returns the next character from a file; it needs the file pointer to tell it which file.

   int getc(FILE *fp)

putc is an output function:

   int putc(int c, FILE *fp)

When a C program is started, the operating system environment is responsible for opening three files and providing pointers for them. These files are the standard input, the standard output, and the standard error; the corresponding file pointers are called stdin, stdout, and stderr, and are declared in <stdio.h>. Normally stdin is connected to the keyboard and stdout and stderr are connected to the screen, but stdin and stdout may be redirected to files or pipes as described in Section 7.1.

getchar and putchar can be defined in terms of getc, putc, stdin, and stdout as follows:

   #define getchar()    getc(stdin)
   #define putchar(c)   putc((c), stdout)

   int fscanf(FILE *fp, char *format, ...)
   int fprintf(FILE *fp, char *format, ...)

   #include <stdio.h>

   /* cat:  concatenate files, version 1 */
   main(int argc, char *argv[])
   {
       FILE *fp;
       void filecopy(FILE *, FILE *)

       if (argc == 1) /* no args; copy standard input */
           filecopy(stdin, stdout);
       else
          while(--argc > 0)
              if ((fp = fopen(*++argv, "r")) == NULL) {
                  printf("cat: can't open %s\n, *argv);
                  return 1;
              } else {
                 filecopy(fp, stdout);
                 fclose(fp);
              }
          return 0;
   }

    /* filecopy:  copy file ifp to file ofp */
    void filecopy(FILE *ifp, FILE *ofp)
    {
        int c;

        while ((c = getc(ifp)) != EOF)
            putc(c, ofp);
    }

The function

   int fclose(FILE *fp)

7.6 Error Handling - Stderr and Exit

To handle this situation better, a second output stream, called stderr, is assigned to a program in the same way that stdin and stdout are. Output written on stderr normally appears on the screen even if the standard output is redirected.

Let us revise cat to write its error messages on the standard error.

   #include <stdio.h>

   /* cat:  concatenate files, version 2 */
   main(int argc, char *argv[])
   {
       FILE *fp;
       void filecopy(FILE *, FILE *);
       char *prog = argv[0];  /* program name for errors */

       if (argc == 1 ) /* no args; copy standard input */
           filecopy(stdin, stdout);
       else
           while (--argc > 0)
               if ((fp = fopen(*++argv, "r")) == NULL) {
                   fprintf(stderr, "%s: can't open %s\n",
                           prog, *argv);
                   exit(1);
               } else {
                   filecopy(fp, stdout);
                   fclose(fp);
               }
       if (ferror(stdout)) {
           fprintf(stderr, "%s: error writing stdout\n", prog);
           exit(2);
       }
       exit(0);
   }

Second, the program uses the standard library function exit, which terminates program execution when it is called. The argument of exit is available to whatever process called this one, so the success or failure of the program can be tested by another program that uses this one as a sub-process. Conventionally, a return value of 0 signals that all is well; non-zero values usually signal abnormal situations. exit calls fclose for each open output file, to flush out any buffered output.

Within main, return expr is equivalent to exit(expr). exit has the advantage that it can be called from other functions, and that calls to it can be found with a pattern-searching program like those in Chapter 5.

The function ferror returns non-zero if an error occurred on the stream fp.

   int ferror(FILE *fp)

The function feof(FILE *) is analogous to ferror; it returns non-zero if end of file has occurred on the specified file.

   int feof(FILE *fp)

7.7 Line Input and Output

   char *fgets(char *line, int maxline, FILE *fp)

For output, the function fputs writes a string (which need not contain a newline) to a file:

   int fputs(char *line, FILE *fp)

The library functions gets and puts are similar to fgets and fputs, but operate on stdin and stdout. Confusingly, gets deletes the terminating '\n', and puts adds it.

To show that there is nothing special about functions like fgets and fputs, here they are, copied from the standard library on our system:

   /* fgets:  get at most n chars from iop */
   char *fgets(char *s, int n, FILE *iop)
   {
       register int c;
       register char *cs;

       cs = s;
       while (--n > 0 && (c = getc(iop)) != EOF)
           if ((*cs++ = c) == '\n')
               break;
       *cs = '\0';
       return (c == EOF && cs == s) ? NULL : s;
   }

   /* fputs:  put string s on file iop */
   int fputs(char *s, FILE *iop)
   {
       int c;

       while (c = *s++)
           putc(c, iop);
       return ferror(iop) ? EOF : 0;
   }

It is easy to implement our getline from fgets:

   /* getline:  read a line, return length */
   int getline(char *line, int max)
   {
       if (fgets(line, max, stdin) == NULL)
           return 0;
       else
           return strlen(line);
   }

Exercise 7-7. Modify the pattern finding program of Chapter 5 to take its input from a set of named files or, if no files are named as arguments, from the standard input. Should the file name be printed when a matching line is found?

Exercise 7-8. Write a program to print a set of files, starting each new one on a new page, with a title and a running page count for each file.

7.8 Miscellaneous Functions

7.8.1 String Operations

strcat(s,t)	concatenate t to end of s
strncat(s,t,n)	concatenate n characters of t to end of s
strcmp(s,t)	return negative, zero, or positive for s < t, s == t, s > t
strncmp(s,t,n)	same as strcmp but only in first n characters
strcpy(s,t)	copy t to s
strncpy(s,t,n)	copy at most n characters of t to s
strlen(s)	return length of s
strchr(s,c)	return pointer to first c in s, or NULL if not present
strrchr(s,c)	return pointer to last c in s, or NULL if not present

7.8.2 Character Class Testing and Conversion

isalpha(c)	non-zero if c is alphabetic, 0 if not
isupper(c)	non-zero if c is upper case, 0 if not
islower(c)	non-zero if c is lower case, 0 if not
isdigit(c)	non-zero if c is digit, 0 if not
isalnum(c)	non-zero if isalpha(c) or isdigit(c), 0 if not
isspace(c)	non-zero if c is blank, tab, newline, return, formfeed, vertical tab
toupper(c)	return c converted to upper case
tolower(c)	return c converted to lower case

7.8.3 Ungetc

   int ungetc(int c, FILE *fp)

7.8.4 Command Execution

   system("date");

7.8.5 Storage Management

   void *malloc(size_t n)

   void *calloc(size_t n, size_t size)

The pointer returned by malloc or calloc has the proper alignment for the object in question, but it must be cast into the appropriate type, as in

   int *ip;

   ip = (int *) calloc(n, sizeof(int));

It is also an error to use something after it has been freed. A typical but incorrect piece of code is this loop that frees items from a list:

   for (p = head; p != NULL; p = p->next) /* WRONG */
       free(p);

   for (p = head; p != NULL; p = q) {
       q = p->next;
       free(p);
   }

7.8.6 Mathematical Functions

sin(x)	sine of x, x in radians
cos(x)	cosine of x, x in radians
atan2(y,x)	arctangent of y/x, in radians
exp(x)	exponential function ex
log(x)	natural (base e) logarithm of x (x>0)
log10(x)	common (base 10) logarithm of x (x>0)
pow(x,y)	xy
sqrt(x)	square root of x (x>0)
fabs(x)	absolute value of x

7.8.7 Random Number generation

   #define frand() ((double) rand() / (RAND_MAX+1.0))

The function srand(unsigned) sets the seed for rand. The portable implementation of rand and srand suggested by the standard appears in Section 2.7.

Exercise 7-9. Functions like isupper can be implemented to save space or to save time. Explore both possibilities.

Back to Chapter 6 --  Index --  Chapter 8