Quick Navigation Bar
functions, preprocessor :: input/output and file i/o :: pointers
[ toc | forums ]

Note: If the document URL does not begin with http://randu.org/tutorials/c/ then you are viewing a copy. Please direct your browser to the correct location for the most recent version.

Input/Output and File I/O

With most of the basics of C under our belts, lets focus now on grabbing Input and directing Output. This is essential for many programs that might require command line parameters, or standard input.

I/O :: printf(3)

printf(3) is one of the most frequently used functions in C for output.
The prototype for printf(3) is:
```
  int printf(const char *format, ...);
```
printf takes in a formatting string and the actual variables to print. An example of printf is:
```
  int x = 5;
  char str[] = "abc";
  char c = 'z';
  float pi = 3.14;

  printf("\t%d %s %f %s %c\n", x, str, pi, "WOW", c);
```
The output of the above would be:
```
       5 abc 3.140000 WOW z
```
Let's see what's happening. The \t line signifies an escape sequence, specifically, a tab. Then the %d specifies a conversion specification as given by the variable x. The %s matches with the string and the %f matches with the float. The default precision for %f is 6 places after the decimal point. %f works for both floats and doubles. For long doubles, use %Lf. The %s matches with the "WOW", and the %c tells printf to output the char c. The \n signifies a newline.
For a listing of escape sequences, see Weiss pg. 183.
You can format the output through the formatting line.. By modifying the conversion specification, you can change how the particular variable is placed in output. For example:
```
   printf("%10.4d", x);
```
Would print this:
```
             0005
```
The . allows for precision. This can be applied to floats as well. The number 10 puts 0005 over 10 spaces so that the number 5 is on the tenth spacing. You can also add + and - right after % to make the number explicitly output as +0005. Note that this does not actually change the value of x. In other words, using %-10.4d will not output -0005.
%e is useful for outputting floats using scientific notation. %le for doubles and %Le for long doubles.

I/O :: scanf(3)

scanf(3) is useful for grabbing things from input. Beware though, scanf isn't the greatest function that C has to offer. Some people brush off scanf as a broken function that shouldn't be used often.
The prototype for scanf is:
```
  int scanf( const char *format, ...);
```
Looks similar to printf, but doesn't completely behave like printf does. Take for example:
```
  scanf("%d", x);
```
You'd expect scanf to read in an int into x. But scanf requires that you specify the address to where the int should be stored. Thus you specify the address-of operator (more on this when we get to pointers). Therefore,
```
  scanf("%d", &x);
```
will put an int into x correctly.
Simple enough, eh? Think again. scanf's major "flaw" is it's inability to digest incorrect input. If scanf is expecting an int and your standard in keeps giving it a string, scanf will keep trying at the same location. If you looped scanf, this would create an infinite loop. Take this example code:
```
  int x, args;

  for ( ; ; ) {
    printf("Enter an integer bub: ");
    if (( args = scanf("%d", &x)) == 0) {
      printf("Error: not an integer\n");
      continue;
    } else {
      if (args == 1)
        printf("Read in %d\n", x);
      else
        break;
    }
  }
```
The code above will fail. Why? It's because scanf isn't discarding bad input. So instead of using just continue;, we have to add a line before it to digest input. We can use a function called digestline().
```
  void digestline(void) {
    scanf("%*[^\n]");   /* Skip to the End of the Line */
    scanf("%*1[\n]");   /* Skip One Newline */
  }
```
This function is taken from Weiss pg. 341. Using assignment suppression, we can use * to suppress anything contained in the set [^\n]. This skips all characters until the newline. The next scanf allows one newline character read. Thus we can digest bad input!
The section on scanf by Weiss is excellent. Section 12.2, pgs. 336-342.

File I/O :: fgets(3)

One of the alternatives to scanf/fscanf is fgets. The prototype is:
```
  char *fgets(char *s, int size, FILE *stream);
```
fgets reads in size - 1 characters from the stream and stores it into *s pointer. The string is automatically null-terminated.
fgets stops reading in characters if it reaches an EOF or newline.
Now that you've read characters of interest from a stream, what do you do with the string? Simple! Use sscanf, see below.

File I/O :: sscanf(3)

To scan a string for a format, the sscanf library call is handy. It's prototype:
```
  int sscanf(const char *str, const char *format, ...);
```
sscanf works much like fscanf except it takes a character pointer instead of a file pointer.
Using the combination of fgets/sscanf instead of scanf/fscanf you can avoid the "digestion" problem (or bug, depending on who you talk to :)

File I/O :: fprintf(3)

It is sometimes useful also to output to different streams. fprintf(3) allows us to do exactly that.
The prototype for fprintf is:
```
  int fprintf(FILE *stream, const char *format, ...);
```
fprintf takes in a special pointer called a file pointer, signified by FILE *. It then accepts a formatting string and arguments. The only difference between fprintf and printf is that fprintf can redirect output to a particular stream. These streams can be stdout, stderr, or a file pointer. More on file pointers when we get to fopen.

An example:

  fprintf(stderr, "ERROR: Cannot malloc enough memory.\n");

This outputs the error message to standard error.

File I/O :: fscanf(3)

fscanf(3) is basically a streams version of fscanf. The prototype for fscanf is:
```
  int fscanf( FILE *stream, const char *format, ...);
```

File I/O :: fflush(3)

Sometimes it is necessary to forcefully flush a buffer to its stream. If a program crashes, sometimes the stream isn't written. You can do this by using the fflush(3) function. The prototype for fflush is:
```
  int fflush(FILE *stream);
```
Not very difficult to use, specify the stream to fflush.

File I/O :: fopen(3), fclose(3), and File Pointers

fopen(3) is used to open streams. This is most often used with opening files for input. fopen's prototype is:
```
  FILE *fopen (const char *path, const char *mode);
```
fopen returns a file pointer and takes in the path to the file as well as the mode to open the file with. Take for example:
```
  FILE *Fp;

  Fp = fopen("/home/johndoe/input.dat", "r");
```
This will open the file in /home/johndoe/input.dat for reading. Now you can use fscanf commands with Fp. For example:
```
  fscanf(Fp, "%d", &x);
```
This would read in an integer from the input.dat file. If we opened input.dat with the mode "w", then we could write to it using fprintf:
```
  fprintf(Fp, "%s\n", "File Streams are cool!");
```
To close the stream, you would use fclose(3). The prototype for fclose is:
```
  int fclose( FILE *stream );
```
You would just give fclose the stream to close the stream. Remember to do this for all file streams, especially when writing to files!

I/O and File I/O :: Return Values

We have been looking at I/O functions without any regard to their return values. This is bad. Very, very bad. So to make our lives easier and to make our programs behave well, let's write some macros!
Let's write some wrapper macros for these functions. First let's create a meta-wrapper function for all of our printf type functions:
```
#define ERR_MSG( fn ) { (void)fflush(stderr); \
                        (void)fprintf(stderr, __FILE__ ":%d:" #fn ": %s\n", \
			              __LINE__, strerror(errno)); }
#define METAPRINTF( fn, args, exp ) if( fn args exp ) ERR_MSG( fn )
```
This will create an ERR_MSG macro to handle error messages. The METAPRINTF is the meta-wrapper for our printf type functions. So let's define our printf type macros:
```
#define PRINTF(args)    METAPRINTF(printf, args, < 0)
#define FPRINTF(args)   METAPRINTF(fprintf, args, < 0)
#define SCANF(args)     METAPRINTF(scanf, args, < 0)
#define FSCANF(args)    METAPRINTF(fscanf, args, < 0)
#define FFLUSH(args)    METAPRINTF(fflush, args, < 0)
```
Now we have our wrapper functions. Because args is sent to METAPRINTF, we need two sets of parentheses when we use the PRINTF macro. Examples on using the wrapper function:
```
  PRINTF(("This is so cool!"));
  FPRINTF((stderr, "Error bub!"));
```
Now you can this code into a common header file and be able to use these convenient macros and still be able to check for return values! (Make sure you have included the string.h library)
Note: We did not write macros for fopen and fclose. You must manually check for return values on those functions.

Other I/O Functions

There are many other Input/Output functions, such as fputs, getchar, putchar, ungetc. Refer to the man pages on these functions or in the Weiss text.

Command Line Arguments and Parameters :: getopt(3)

I'm sure you've run the ls -l command before. ls -l *.c would display all c files with extended information. These parameters and arguments can be handled by your c program through getopt(3).

We have already seen getopt, but now lets actually make some code that makes this function useful. Let's see the prototype again:

  int getopt(int argc, char * const argv[], const char *optstring);
  extern char *optarg;
  extern int optind, opterr, optopt;

In order for us to utilize argc and argv, we must allow these as parameters on our main() function:

  int main(int argc, char **argv)

Now that we have everything set up, lets get this show on the road. Here's an example of using getopt:

  int ich;

  while ((ich = getopt (argc, argv, "ab:c")) != EOF) {
    switch (ich) {
      case 'a': /* Flags/Code when -a is specified */
        break;
      case 'b': /* Flags/Code when -b is specified */
                /* The argument passed in with b is specified */
		/* by optarg */
        break;
      case 'c': /* Flags/Code when -c is specified */
        break;
      default: /* Code when there are no parameters */
        break;
    }
  }

  if (optind < argc) {
    printf ("non-option ARGV-elements: ");
    while (optind < argc)
      printf ("%s ", argv[optind++]);
    printf ("\n");
  }

This code might be a bit confusing if taken in all at once.

The first step is to get getopt to pass an int into ich. The options allowed are specified by the "ab:c". The colon following b allows b to have arguments, e.g. -b gradient. Thus, optarg will contain the string "gradient".
ich is then switched to check for the parameters.
The ending conditional if (optind < argc) { checks for aguments passed in without an accompanying parameter. optind is the current index in the list of arguments passed in in the argv-list. argc is the total number of arguments passed in.

So if we had a program called "junk" and we called it from the command prompt as ./junk -b gradient yeehaw the variables would look like:

   Variable               Contains
   ------------------     ----------
   argc                   4
   argv[0]                "./junk"
   argv[1]                "-b"
   argv[2]                "gradient"
   argv[3]                "yeehaw"
   optarg at case 'b'     "gradient"
   optind after while     3
     getopt loop

Input/Output and File I/O Review

printf and scanf can be used for Input and Output, while the "f versions" of these can be used to modify streams. Make sure you check the return values!
You can grab command line arguments and parameters through getopt.