Difference between revisions of "cpp/language/main function"

Latest revision as of 22:14, 6 June 2024

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)

int `main(`/* implementation-defined */`) {` body `}`	(3)

1) A main function running independently of environment-provided arguments.

2) A main function accepting environment-provided arguments.

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.

3) A main function of implement-defined type, returning int.

The C++ standard recommends implementation-defined main functions to place the extra (optional) parameters after argv.

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 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 the following several special properties:

1) 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;.

2) 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).

The main function has several restrictions (violation of which renders the program ill-formed):

1) It cannot be named anywhere in the program

a) in particular, it cannot be called recursively

b) its address cannot be taken

c) it cannot be used in a typeid expression or a decltype-specifier(since C++11)

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 return type of the main function cannot be deduced (auto main() {...} is not allowed).

(since C++14)

5) The main function cannot be a coroutine.

(since C++20)

6) The main function cannot attach to a named module.

(since C++20)

[edit] 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:

Parsing C++ Command-Line Arguments MSDN
Shell Introduction POSIX

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.

[edit] 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

Run this code

#include <cstdlib>
#include <iomanip>
#include <iostream>
 
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

[edit] References

Extended content
C++23 standard (ISO/IEC 14882:2024): 6.9.3.1 main function [basic.start.main]

[edit] 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	supported parameter names of `main` were overly restricted	all valid parameter names are supported
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
CWG 2811	C++98	whether the `main` function is used after N3214 was unclear	it is considered used when named

[edit] See also

C documentation for main function

@@ Line 2: / Line 2: @@
 {{cpp/language/basics/navbar}}
-A program shall contain a global function named {{ttb|main}}, which is the designated start of the program.
+A program shall contain a global function named {{c|main}}, which is the designated start of the program in hosted environment. It shall have one of the following forms:
 {{sdsc begin}}
 {{sdsc|num=1|1=
-{{c|int}} {{ttb|main}} {{ttb|()}} {{ttb|{}} {{spar|body}} {{ttb|} }}
+{{c/core|int}}{{ttb| main() {}} {{spar|body}} {{ttb|}<!---->}}
 }}
 {{sdsc|num=2|1=
-{{c|int}} {{ttb|main}} {{ttb|(}}{{c|int}} {{spar|argc}}{{ttb|,}} {{c|char}} {{c|*}}{{spar|argv}}{{c|[]}}{{ttb|)}} {{ttb|{}} {{spar|body}} {{ttb|} }}
+{{c/core|int}}{{ttb| main(}}{{c/core|int}} {{spar|argc}}{{ttb|,}} {{c/core|char*}} {{spar|argv}}{{tt|[]}}{{ttb|) {}} {{spar|body}} {{ttb|}<!---->}}
 }}
 {{sdsc|num=3|1=
-{{c|int}} {{ttb|main}} {{ttb|(}}{{c|int}} {{spar|argc}}{{ttb|,}} {{c|char}} {{c|*}}{{spar|argv}}{{c|[]}}  {{ttb|,}} {{spar|other_parameters}} {{ttb|)}}  {{ttb|{}} {{spar|body}} {{ttb|} }}
+{{c/core|int}}{{ttb| main(}}{{c/core|/* implementation-defined */}}{{ttb|) {}} {{spar|body}} {{ttb|}<!---->}}
 }}
 {{sdsc end}}
+@1@ A {{tt|main}} function running independently of environment-provided arguments.
+@2@ A {{tt|main}} function accepting environment-provided arguments.
+@@ The names of {{spar|argc}} and {{spar|argv}} are arbitrary, as well as the representation of the types of the parameters: {{c/core|int main(int ac, char** av)}} is equally valid.
+@3@ A {{tt|main}} function of implement-defined type, returning {{c/core|int}}.
+@@ The C++ standard recommends implementation-defined {{tt|main}} functions to place the extra (optional) parameters after {{spar|argv}}.
 {{par begin}}
-{{par | argc | Non-negative value representing the number of arguments passed to the program from the environment in which the program is run.}}
+{{par|{{spar|argc}}|Non-negative value representing the number of arguments passed to the program from the environment in which the program is run.}}
-{{par | argv | Pointer to the first element of an array of pointers to [[cpp/string/multibyte|null-terminated multibyte strings]] that represent the arguments passed to the program from the execution environment ({{c|argv[0]}} through {{c|argv[argc-1]}}). The value of {{c|argv[argc]}} is guaranteed to be {{c|0}}.}}
+{{par|{{spar|argv}}|Pointer to the first element of an array of {{c|argc + 1}} pointers, of which the last one is null and the previous ones, if any, point to [[cpp/string/multibyte|null-terminated multibyte strings]] that represent the arguments passed to the program from the execution environment. If {{c|argv[0]}} is not a null pointer (or, equivalently, if {{c|argc > 0}}), it points to a string that represents the name used to invoke the program, or to an empty string.}}
-{{par | body | The body of the main function}}
+{{par|{{spar|body}}|The body of the {{tt|main}} function.}}
-{{par | {{spar|other_parameters}} | Implementations may allow additional forms of the main function as long as the return type remains {{tt|int}}. A very common extension is passing a third argument of type {{tt|char*[]}} pointing at [http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html an array of pointers to the execution environment variables].}}
 {{par end}}
-The names {{tt|argc}} and {{tt|argv}} are arbitrary, as well as the representation of the types of the parameters: {{c|int main(int ac, char** av)}} is equally valid.
 ===Explanation===
 The {{tt|main}} function is called at program startup after {{rlp|initialization}} of the non-local objects with static {{rlp|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 {{tt|argv[1] .. argv[argc-1]}} point at the first characters in each of these strings. {{tt|argv[0]}} is the pointer to the initial character of a null-terminated multibyte strings that represents the name used to invoke the program itself (or an empty string {{c|""}} 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 {{lc|std::strtok}}. The size of the array pointed to by {{tt|argv}} is at least {{tt|argc+1}}, and the last element, {{tt|argv[argc]}}, is guaranteed to be a null pointer.
+The parameters of the two-parameter form of the {{tt|main}} function allow arbitrary multibyte character strings to be passed from the execution environment (these are typically known as ''command line arguments''), the pointers {{c|argv[1]}} .. {{c|argv[argc - 1]}} point at the first characters in each of these strings. {{c|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 {{c|""}} 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 {{lc|std::strtok}}. The size of the array pointed to by {{c|argv}} is at least {{c|argc + 1}}, and the last element, {{c|argv[argc]}}, is guaranteed to be a null pointer.
-The {{tt|main}} function has several special properties:
+The {{tt|main}} function has the following several special properties:
-@1@ It cannot be used anywhere in the program
+@1@ The body of the {{tt|main}} function does not need to contain the {{rlp|return|{{c/core|return}} statement}}: if control reaches the end of {{tt|main}} without encountering a return statement, the effect is that of executing {{c|return 0;}}.
+@2@ Execution of the return (or the implicit return upon reaching the end of {{tt|main}}) is equivalent to first leaving the function normally (which destroys the objects with automatic storage duration) and then calling {{lc|std::exit}} with the same argument as the argument of the {{rlp|return}} ({{lc|std::exit}} then destroys static objects and terminates the program).
+The {{tt|main}} function has several restrictions (violation of which renders the program ill-formed):
+@1@ It cannot be {{rlp|definition#Naming a function|named}} 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 {{tt|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{{rev inl|since=c++17|, except that a function called "main" cannot be declared with C {{rlp|language linkage}} in any namespace}})
+:@c@ it cannot be used in a {{rlpt|typeid}} expression {{rev inl|since=c++11|or a {{rlpt|decltype}}-specifier}}
-@3@ It cannot be defined as deleted or declared {{rev inl|since=c++17|with C {{rlp|language linkage}}}}, {{rlp|inline}}, {{rlp|static}}, or {{rlp|constexpr}}
+@2@ It cannot be predefined and cannot be overloaded: effectively, the name {{tt|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 {{tt|main}} cannot be declared with C {{rlp|language linkage}} in any namespace.
-@4@ The body of the main function does not need to contain the {{rlp|return|return statement}}: if control reaches the end of {{tt|main}} without encountering a return statement, the effect is that of executing {{c|return 0;}}.
+@3@ It cannot be {{rev inl|since=c++11|defined as deleted or}} declared with any language linkage{{rev inl|since=c++11|, {{rlpt|constexpr}}}}{{rev inl|since=c++20|, {{rlpt|consteval}}}}, {{rlpt|inline}}, or {{rlpt|static}}.
-@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 {{c|std::exit}} with the same argument as the argument of the {{rlp|return}}. ({{c|std::exit}} then destroys static objects and terminates the program)
-@6@ If the main function is defined with a {{rlp|function-try-block}}, the exceptions thrown by the destructors of static objects (which are destroyed by the implied {{lc|std::exit}}) are not caught by it.
+{{rrev|since=c++14|
-@7@ {{mark since c++14}} The return type of the main function cannot be deduced ({{c|auto main() {...}} is not allowed)
+@4@ The return type of the {{tt|main}} function cannot be deduced ({{c/core|auto main() {...}<!---->}} is not allowed).
+}}
+{{rrev|since=c++20|
+@5@ The {{tt|main}} function cannot be a {{rlp|coroutines|coroutine}}.
+}}
+{{rrev|since=c++20|
+@6@ The {{tt|main}} function cannot attach to a named {{rlp|modules|module}}.
+}}
 ===Notes===
-The manner in which the arguments given at the OS command line are converted into the multibyte arrays referenced by {{tt|argv}} may involve implementation-defined processing:
+If the {{tt|main}} function is defined with a {{rlp|try#Function try block|function {{c/core|try}} block}}, the exceptions thrown by the destructors of static objects (which are destroyed by the implied {{lc|std::exit}}) are not {{rlp|catch|caught}} by it.
-* [https://msdn.microsoft.com/en-us/library/17w5ykft.aspx Parsing C++ Command-Line Arguments] MSDN
-* [http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_01 Shell Introduction] POSIX
+The manner in which the arguments given at the OS command line are converted into the multibyte character arrays referenced by {{c|argv}} may involve implementation-defined processing:
+* [https://docs.microsoft.com/en-us/cpp/cpp/main-function-command-line-args Parsing C++ Command-Line Arguments] MSDN
+* [https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_01 Shell Introduction] POSIX
+A very common implementation-defined form of {{c/core|main()}} has a third argument (in addition to {{tt|argc}} and {{tt|argv}}), of type {{c/core|char**}}, pointing at [https://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html an array of pointers to the execution environment variables].
+===Example===
+{{example
+|Demonstrates how to inform a program about where to find its input and where to write its results.<br>
+A possible invocation: {{c|1=./convert table_in.dat table_out.dat}}
+|code=
+#include <cstdlib>
+#include <iomanip>
+#include <iostream>
+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
+}
+|p=true
+|output=
+argc == 3
+argv[0] == "./convert"
+argv[1] == "table_in.dat"
+argv[2] == "table_out.dat"
+argv[3] == 0
+}}
+===References===
+{{cot}}
+{{ref std c++23}}
+{{ref std|section=6.9.3.1|title=main function|id=basic.start.main}}
+{{ref std end}}
+{{cob}}
+===Defect reports===
+{{dr list begin}}
+{{dr list item|wg=cwg|dr=1003|std=C++98|before=supported parameter names of {{tt|main}} were overly restricted|after=all valid parameter<br>names are supported}}
+{{dr list item|wg=cwg|dr=1886|std=C++98|before=the {{tt|main}} function could be declared with a language linkage|after=prohibited}}
+{{dr list item|wg=cwg|dr=2479|std=C++20|before=the {{tt|main}} function could be declared {{c/core|consteval}}|after=prohibited}}
+{{dr list item|wg=cwg|dr=2811|std=C++98|before=whether the {{tt|main}} function is used after {{wg21|N3214}} was unclear|after=it is considered used when named}}
+{{dr list end}}
 ===See also===
 {{dsc begin}}
-{{dsc see c | c/language/main function}}
+{{dsc see c|c/language/main function|{{tt|main}} function|nomono=true}}
 {{dsc end}}
+{{langlinks|es|ja|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Comments
ASCII
Punctuation
Names and identifiers
Types
Fundamental types
Objects
Scope
Object lifetime
Storage duration and linkage
Definitions and ODR
Name lookup
Qualified name lookup
Unqualified name lookup
The as-if rule
Undefined behavior
Memory model
Multi-threaded executions and data races (C++11)
Character sets and encodings
Phases of translation
The `main` function
Modules (C++20)

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/language/main function"

Latest revision as of 22:14, 6 June 2024

Contents

[edit] Explanation

[edit] Notes

[edit] Example

[edit] References

[edit] Defect reports

[edit] See also

Navigation

Toolbox