Main function

From cppreference.com
< cpp‎ | language
 
 
C++ language
General topics
Flow control
Conditional execution statements
if
Iteration statements (loops)
for
range-for (C++11)
Jump statements
Functions
Function declaration
Lambda function expression
inline specifier
Dynamic exception specifications (until C++20)
noexcept specifier (C++11)
Exceptions
Namespaces
Types
Specifiers
decltype (C++11)
auto (C++11)
alignas (C++11)
Storage duration specifiers
Initialization
Expressions
Alternative representations
Literals
Boolean - Integer - Floating-point
Character - String - nullptr (C++11)
User-defined (C++11)
Utilities
Attributes (C++11)
Types
typedef declaration
Type alias declaration (C++11)
Casts
Implicit conversions - Explicit conversions
static_cast - dynamic_cast
const_cast - reinterpret_cast
Memory allocation
Classes
Class-specific function properties
explicit (C++11)
static
Special member functions
Templates
Miscellaneous
 
 

A program shall contain a global function named main, which is the designated start of the program in hosted environment. It shall have one of the following forms:

int main () { body } (1)
int main (int argc, char *argv[]) { body } (2)
/* another implementation-defined form, with int as return type */ (3)
argc - Non-negative value representing the number of arguments passed to the program from the environment in which the program is run.
argv - Pointer to the first element of an array of argc + 1 pointers, of which the last one is null and the previous ones, if any, point to null-terminated multibyte strings that represent the arguments passed to the program from the execution environment. If argv[0] is not a null pointer (or, equivalently, if argc > 0), it points to a string that represents the name used to invoke the program, or to an empty string.
body - The body of the main function

The names of argc and argv are arbitrary, as well as the representation of the types of the parameters: int main(int ac, char** av) is equally valid.

A very common implementation-defined form of main() has a third argument (in addition to argc and argv), of type char**, pointing at an array of pointers to the execution environment variables.

Explanation

The main function is called at program startup after initialization of the non-local objects with static storage duration. It is the designated entry point to a program that is executed in hosted environment (that is, with an operating system). The entry points to freestanding programs (boot loaders, OS kernels, etc) are implementation-defined.

The parameters of the two-parameter form of the main function allow arbitrary multibyte character strings to be passed from the execution environment (these are typically known as command line arguments), the pointers argv[1] .. argv[argc - 1] point at the first characters in each of these strings. argv[0] (if non-null) is the pointer to the initial character of a null-terminated multibyte string that represents the name used to invoke the program itself (or an empty string "" if this is not supported by the execution environment). The strings are modifiable, although these modifications do not propagate back to the execution environment: they can be used, for example, with std::strtok. The size of the array pointed to by argv is at least argc + 1, and the last element, argv[argc], is guaranteed to be a null pointer.

The main function has several special properties:

1) It cannot be used anywhere in the program
a) in particular, it cannot be called recursively
b) its address cannot be taken
2) It cannot be predefined and cannot be overloaded: effectively, the name main in the global namespace is reserved for functions (although it can be used to name classes, namespaces, enumerations, and any entity in a non-global namespace, except that an entity named main cannot be declared with C language linkage in any namespace.
3) It cannot be defined as deleted or (since C++11) declared with any language linkage, , constexpr (since C++11), consteval (since C++20), inline, or static.
4) The body of the main function does not need to contain the return statement: if control reaches the end of main without encountering a return statement, the effect is that of executing return 0;.
5) Execution of the return (or the implicit return upon reaching the end of main) is equivalent to first leaving the function normally (which destroys the objects with automatic storage duration) and then calling std::exit with the same argument as the argument of the return. (std::exit then destroys static objects and terminates the program).
6) The return type of the main function cannot be deduced (auto main() {... is not allowed).
(since C++14)
7) The main function cannot be a coroutine.
(since C++20)

Notes

If the main function is defined with a function-try-block, the exceptions thrown by the destructors of static objects (which are destroyed by the implied std::exit) are not caught by it.

The manner in which the arguments given at the OS command line are converted into the multibyte character arrays referenced by argv may involve implementation-defined processing:

Example

Demonstrates how to inform a program about where to find its input and where to write its results.
A possible invocation: ./convert table_in.dat table_out.dat

#include <iostream>
#include <iomanip>
#include <cstdlib>
 
int main(int argc, char *argv[])
{
    std::cout << "argc == " << argc << '\n';
 
    for(int ndx{}; ndx != argc; ++ndx) {
        std::cout << "argv[" << ndx << "] == " << std::quoted(argv[ndx]) << '\n';
    }
    std::cout << "argv[" << argc << "] == "
              << static_cast<void*>(argv[argc]) << '\n';
    /*...*/
    return argc == 3 ? EXIT_SUCCESS : EXIT_FAILURE; // optional return value
}

Possible output:

argc == 3
argv[0] == "./convert"
argv[1] == "table_in.dat"
argv[2] == "table_out.dat"
argv[3] == 0

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
CWG 1003 C++98 for form (2), definitions whose parameter names
that are not argc (1st parameter) and argv
(2nd parameter) were not required to be supported
need to support all
valid parameter names
CWG 1886 C++98 the main function could be declared with a language linkage prohibited
CWG 2479 C++20 the main function could be declared consteval prohibited

See also