(Last Mod: 27 November 2010 21:38:36 )
If necessary, you may want to familiarize yourself with the basic structure of a C function before continuing with this module.
In a "hosted environment" - such as you are dealing with when your program is running on a computer with an operating system - the function main() is required to return an integer value to the host when it has completed execution. While this has been the recommended practice for some time, it is now a requirement of the latest C Language Standard, C99. Failure to return an int to the host may invoke undefined behavior.
By convention, a program should return a value of zero to the host if it ended normally and some non-zero value if any type of error or warning was encountered. This value will probably not be used, but if your program were to be called by another program, then that program could get information back about how your program ended.
In addition to returning a value of type int, the main() function may be declared to either take no arguments or exactly two arguments.
If you do not wish access to any command line arguments, then your main() function header should appear as follows:
int main(void)
Neither the return type of int, nor the keyword void in the parameter list is optional any longer. Older compilers were allowed to assume defaults if these were not supplied, but this created occasional problems with code portability from one implementation to another.
If you wish to have access to the commands entered on the command line, these can be obtained by declaring two parameters for the main() function as follows:
int main(int argc, char *argv[])
Although the names can be any valid identifier name, argc and argv are the time-honored conventions. The parameter argc receives the total number of arguments passed to the function. Although implementation defined, a term in typically any group of characters not containing any white-space and separated from other groups by at least one white-space character. These terms are stored as null terminated strings and a pointer to each string is stored in the argv array.
The first term is the program name, generally including path information used to execute the program. Subsequent entries in the array correspond to the remaining terms passed to the program. The entry following the last term is a NULL pointer.
In summary:
As described previously, your program should return a value of zero if it exited normally and some non-zero value if it exited abnormally. Each abnormal condition should return a different value and these values should be documented in the source code.
Two pre-defined constants are available in the stdlib.h standard header file, namely EXIT_SUCCESS and EXIT_FAILURE. The value of both are implementation defined and, while EXIT_SUCCESS is generally zero, this is not guaranteed. Using programmer defined exit codes removes all doubt.
The expected means of doing this is through the use of symbolic constants chosen to make the code readable. For example, the meanings of the following exit conditions should be readily apparent:
#define EXIT_PASS (0)
#define EXIT_FAIL_FILE_DIDNT_OPEN (1)
#define EXIT_FAIL_DENOMINATOR_IS_ZERO (2)
#define EXIT_FAIL_STEPSIZE_TOO_SMALL (3)
#define EXIT_FAIL_MEMORY_DIDNT_ALLOCATE (4)
When a return statement is encountered in any function, the function ends and the value, if any, immediately following the return statement (i.e., between it and the ending semicolon) is returned to the calling function. If the function ending is main(), then the program terminates and the return value is returned to the host.
When the exit() function - accessed via the stdlib.h standard header file - is encountered, it terminates the program as a whole, regardless of which function is presently being executed, and returns the value passed to it on to the host.
If a return statement in main() returns a value of type int (which it is expected to) then the behavior is identical whether the return statement is used or the exit() function is called.