FAQ > Command line input


Match word(s).

If you have any questions or comments,
please visit us on the Forums.

FAQ > Prelude's Corner > Command line input

This item was added on: 2004/01/21

Command Line Input

Sometimes interactive input is impractical. Interactive input is when a program promts a user for data that it requires to perform its calculations. There are times however, when the program cannot prompt the user, a good example is when another program calls your program. In this situation, acquiring the data that you need from the calling program is difficult at best and impossible at worst, but there must be a way. Fortunately, the creators of C and C++ understood this need and gave us a way to deal with it. This solution is that of command line arguments. What are they? Let's find out.

The main function is declared by the Standard to take either zero or two parameters, these two parameters allow other programs to call main with a set of arguments that main can then use to perform operations. These arguments are commonly called argc, which stands for argument count, and argv, which stands for argument vector. argc is an integer that contains the number of arguments passed to main, this value will always be at least 1, the first argument is always the name of the program. argv is an array of char pointers (or an array of C strings) which contains each argument in string format. For example, if we called the program from the command line like so:

$prog arg1 arg2 arg3

Then argc would hold a value of 4 and argv would be an array of five elements, the first element holding the program's name, and each element after that holding the next consecutive string separated by a space. Note that there are four arguments, but five elements of the argv array. The last element holds a NULL value and is used to designate the end of the array. So argv would look something like this in memory:

argv:[0] = "prog", [1] = "arg1", [2] = "arg2", [3] = "arg3", [4] = NULL

Now that we have the background of the parameters to main and how they work, let's write a program to manipulate them. This is a simple program that merely takes a name and two numbers to add together. We will print out the name of the program, the second name argument (assumed to be a user's name), and the result of both numbers added together. This program details how to use the command line arguments quite well:


#include <stdio.h> 
#include <stdlib.h> /* For strtol, EXIT_SUCCESS, and EXIT_FAILURE */ 

/*
** main can take two arguments portably, these are the
** argument count and the argument vector from the command
** line. Argument count, argc, is an integer that designates
** how many arguments there are. There is always one argument,
** the name of the file. The argument vector is an array of
** strings pointed to by char pointers. There are an argc
** number of items in the array. argv[0] is always the file
** name, argv[argc] is always NULL, and marks the end of the array.
** The last argument is argv[argc - 1].
*/
int main ( int argc, char **argv )
{
  int a, b;
  /*
  ** Always test argc to make sure the user entered enough
  ** arguments to work with. If this number is not one of
  ** the amounts you can handle, print a usage and exit.
  */
  if ( argc != 4 ) {
    fputs ( "usage: $prog <name> <number1> <number2>", stderr );
    exit ( EXIT_FAILURE );
  }
  /* argv[0] is the program name, print it out. */
  printf ( "My name is %s\n", argv[0] );
  /* argv[1] for this program is a string containing the user's name. */
  printf ( "Your name is %s\n", argv[1] );
  /*
  ** argv[2] and argv[3] are supposed to be numbers, so we have
  ** to convert the strings to integers before we can work with
  ** them. strtol is used instead of atoi because atoi is unsafe,
  ** especially with something like command line arguments.
  */
  a = (int)strtol ( argv[2], NULL, 10 );
  b = (int)strtol ( argv[3], NULL, 10 );
  /* Print a + b to standard output. */
  printf ( "%d + %d = %d\n", a, b, (a + b) );
  /*
  ** Ensure that argv[argc] is indeed NULL by printing
  ** a message if (argv[argc] == NULL) evaluates to true.
  */
  if ( argv[argc] == NULL )
    puts ( "This is the end" );

  return EXIT_SUCCESS;
}


Now, there are a few points about this program that should be make more clearly than the code offers. argc is an int, argv is an array of char pointers. An array of char pointers can be represented as a function parameter one of two ways: char *name[] or char **name. I have chosen to use the latter, you can use either one, it is a matter of style, which I refuse to dictate. The test to see if argc is not equal to 4 is especially important if the user enters the arguments. You never know if the user will enter the correct amount and type of data that you want, so you must explicitly check for it in your code. This program assumes that if the number of arguments is correct, the type of the arguments is also correct, more on this in a bit. If the number is not what you want it to be, it is a good idea to print an error message describing what you expect and then terminating the program (there is no reason to continue if you do not have the correct data).

Once we know that we have the correct amount of arguments, we then print the name of the program (argv[0]), and the name of the user (argv[1]). We can use constants for the array indices because we know exactly what items are where in the array. The next part of the program is interesting, we know that argv[2] and argv[3] should be numbers, but they are in string format, so we cannot add them together as they are. The solution is to convert the strings to integers and save the converted value in two variables, this is a good idea regardless because argv may be in read-only memory so you would have to copy the strings to modify them in any way. Converting a string to an integer does not modify the original string, so we are safe using argv as the argument to the conversion routine.

The conversion routine may be of interest to some because most programmers are more familiar with atoi() for converting strings to integers. I chose not to use atoi because it is a buggy implementation and causes big problems if the value of the string overflows an int. The strtol() function is far more stable with errors, so it is highly recommended that you use the strto* functions instead of the ato* functions. Once the strings are converted to integers we merely print them out and then the result of an addition between them.

After all of this (it really is very simple, right?) we check good ol' Code Goddess's word and see if the last item in argv is really NULL. The last item in argv is always argv[argc], so we test it for NULL and if it is we print something. You will find that it always prints something, that will teach you to doubt my word. ;) After all of this we return successfully.

Running The Program

If you want to run this program, compile it to an executable somewhere on your hard disk drive, and open a command line shell, then run the program with arguments of your choice. Here are a few test runs on my system (Pentium 3 running WindowsXP and MSVC++6 Enterprise Edition:

c:\cTest>cl -Za -W4 cTest.c
Microsoft (R) 32-bit C/C++ Standard Compiler Version 13.00.9466 for 80x86
Copyright (C) Microsoft Corporation 1984-2001. All rights reserved.

/out:cTest.exe
cTest.obj

C:\cTest>cTest
usage: $prog <name> <number1> <number2>
C:\cTest>cTest Julienne 1 1
My name is cTest
Your name is Julienne
1 + 1 = 2
This is the end

C:\cTest>cTest Code Goddess 10
My name is cTest
Your name is Code
0 + 10 = 10
This is the end

Just a quick note on that last test run, if strtol cannot convert any of the characters passed to it into numbers then it will return 0. The test runs show that this program works for correct input and covers its butt quite nicely for incorrect input.

Have fun!

Script provided by SmartCGIs