How C programs communicate with the shell

Information or control data can be passed to a C program as an argument on the command line, which is to say, by the shell. When you execute a C program, command line arguments are made available to the function main in two parameters, an argument count, conventionally called argc, and an argument vector, conventionally called argv. (Every C program is required to have an entry point named main.) argc is the number of arguments with which the program was invoked. argv is an array of pointers to character strings that contain the arguments, one per string. Since the command name itself is considered to be the first argument, or argv[0], the count is always at least one. Here is the declaration for main:

int
main(int argc, char *argv[])

The shell, which makes arguments available to your program, considers an argument to be any sequence of non-blank characters. Characters enclosed in single quotes ('abc def') or double quotes (``"abc def"'') are passed to the program as one argument even if blanks or tabs are among the characters. You are responsible for error checking and otherwise making sure that the argument received is what your program expects it to be.

In addition to argc and argv, you can use a third argument: envp is an array of pointers to environment variables. You can find more information on envp on the exec(2) and environ(5) manual pages.

C programs exit voluntarily, returning control to the operating system, by returning from main or by calling the exit function. That is, a return(n) from main is equivalent to the call exit(n). (Remember that main has type ``function returning int.'') Your program should return a value to say whether it completed successfully or not. The value gets passed to the shell, where it becomes the value of the $? shell variable if you executed your program in the foreground. By convention, a return value of zero denotes success, a non-zero return value means some sort of error occurred. You can use the macros EXIT_SUCCESS and EXIT_FAILURE, defined in the header file <stdlib.h>, as return values from main or argument values for exit.

Passing command line arguments

As described above, information or control data can be passed to a C program as an argument on the command line. When you execute the program, command line arguments are made available to the function main in two parameters, an argument count, conventionally called argc, and an argument vector, conventionally called argv. argc is the number of arguments with which the program was invoked. argv is an array of pointers to characters strings that contain the arguments, one per string. Since the command name itself is considered to be the first argument, or argv[0], the count is always at least one.

If you plan to accept run-time parameters in your program, you need to include code to deal with the information. ``Using argv[1] to pass a file name'' and ``Using command line arguments to set flags'' show program fragments that illustrate two common uses of run-time parameters:

• ``Using argv[1] to pass a file name'' shows how you provide a variable file name to a program, such that a command of the form

     $ prog filename
  

  will cause prog to attempt to open the specified file.

• ``Using command line arguments to set flags'' shows how you set internal flags that control the operation of a program, such that a command of the form

     $ prog -opr
  

  will cause prog to set the corresponding variables for each of the options specified. The getopt function used in the example is the most common way to process arguments in UnixWare programs. See getopt(3C).

   #include <stdio.h>
   

   int
   main(int argc, char *argv[])
   {
         FILE *fin;
         int ch;
   

         switch (argc)
         {
         case 2:
               if ((fin = fopen(argv[1], "r")) == NULL)
               {
                     /* First string (%s) is program name (argv[0]).  */
                     /* Second string (%s) is name of file that could */
                     /* not be opened (argv[1]). */
   

                     (void)fprintf(stderr, "%s: Cannot open input file %s\n",
                           argv[0], argv[1]);
                     return(2);
               }
               break;
         case 1:
               fin = stdin;
               break;
   

         default:
               (void)fprintf(stderr, "Usage: %s [file]\n", argv[0]);
               return(2);
         }
   

         while ((ch = getc(fin)) != EOF)
               (void)putchar(ch);
   

         return (0);
   

   }

Using argv[1] to pass a file name

   #include <stdio.h>
   #include <stdlib.h>
   

   int
   main(int argc, char *argv[])
   {
         int oflag = 0;
         int pflag = 0;	/* Function flags */
         int rflag = 0;
         int ch;
   

         while ((ch = getopt(argc, argv, "opr")) != -1)
         {
               /* For options present, set flag to 1.              */
               /* If unknown options present, print error message. */
   

               switch (ch)
               {
               case 'o':
                     oflag = 1;
                     break;
               case 'p':
                     pflag = 1;
                     break;
               case 'r':
                     rflag = 1;
                     break;
               default:
                     (void)fprintf(stderr, "Usage: %s [-opr]\n", argv[0]);
                     return(2);
               }
         }
         /* Do other processing controlled by oflag, pflag, rflag. */
         return(0);
   }

Using command line arguments to set flags