diff options
Diffstat (limited to 'devdocs/c/language%2Fmain_function.html')
| -rw-r--r-- | devdocs/c/language%2Fmain_function.html | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/devdocs/c/language%2Fmain_function.html b/devdocs/c/language%2Fmain_function.html new file mode 100644 index 00000000..a0cfbc3e --- /dev/null +++ b/devdocs/c/language%2Fmain_function.html @@ -0,0 +1,60 @@ + <h1 id="firstHeading" class="firstHeading">Main function</h1> <p>Every C program coded to run in a hosted execution environment contains the definition (not the prototype) of a function named <code>main</code>, which is the designated start of the program.</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="kw4">int</span> <code>main</code> <code>(void)</code> <code>{</code> <span class="t-spar">body</span> <code>}</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="kw4">int</span> <code>main</code> <code>(</code><span class="kw4">int</span> <span class="t-spar">argc</span><code>,</code> <span class="kw4">char</span> <span class="sy2">*</span><span class="t-spar">argv</span><span class="br0">[</span><span class="br0">]</span><code>)</code> <code>{</code> <span class="t-spar">body</span> <code>}</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="coMULTI">/* another implementation-defined signature */</span> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> argc </td> <td> - </td> <td> Non-negative value representing the number of arguments passed to the program from the environment in which the program is run. </td> +</tr> <tr class="t-par"> <td> argv </td> <td> - </td> <td> Pointer to the first element of an array of <code>argc + 1</code> pointers, of which the last one is null and the previous ones, if any, point to strings that represent the arguments passed to the program from the host environment. If <code>argv[0]</code> is not a null pointer (or, equivalently, if <code>argc</code> > 0), it points to a string that represents the program name, which is empty if the program name is not available from the host environment. </td> +</tr> +</table> <p>The names <code>argc</code> and <code>argv</code> stand for "argument count" and "argument vector", and are traditionally used, but other names may be chosen for the parameters, as well as different but equivalent declarations of their type: <span class="kw4">int</span> main<span class="br0">(</span><span class="kw4">int</span> ac, <span class="kw4">char</span><span class="sy2">**</span> av<span class="br0">)</span> is equally valid.</p> +<p>A common implementation-defined form of main is <span class="kw4">int</span> main<span class="br0">(</span><span class="kw4">int</span> argc, <span class="kw4">char</span> <span class="sy2">*</span>argv<span class="br0">[</span><span class="br0">]</span>, <span class="kw4">char</span> <span class="sy2">*</span>envp<span class="br0">[</span><span class="br0">]</span><span class="br0">)</span>, where a third argument, of type <code>char**</code>, pointing at <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html">an array of pointers to the <i>execution environment variables</i></a>, is added.</p> +<h3 id="Return_value"> Return value</h3> <p>If the return statement is used, the return value is used as the argument to the implicit call to <code><a href="../program/exit" title="c/program/exit">exit()</a></code> (see below for details). The values zero and <code><a href="../program/exit_status" title="c/program/EXIT status">EXIT_SUCCESS</a></code> indicate successful termination, the value <code><a href="../program/exit_status" title="c/program/EXIT status">EXIT_FAILURE</a></code> indicates unsuccessful termination.</p> +<h3 id="Explanation"> Explanation</h3> <p>The <code>main</code> function is called at program startup, after all objects with static storage duration are initialized. It is the designated entry point to a program that is executed in a <i>hosted</i> environment (that is, with an operating system). The name and type of the entry point to any <i>freestanding</i> program (boot loaders, OS kernels, etc) are implementation-defined.</p> +<p>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 <i>command line arguments</i>). The pointers argv<span class="br0">[</span><span class="nu0">1</span><span class="br0">]</span> .. <span class="me1">argv</span><span class="br0">[</span>argc<span class="sy2">-</span><span class="nu0">1</span><span class="br0">]</span> point at the first characters in each of these strings. argv<span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span> (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, if this is not supported by the host environment, argv<span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span><span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span> is guaranteed to be zero).</p> +<p>If the host environment cannot supply both lowercase and uppercase letters, the command line arguments are converted to lowercase.</p> +<p>The strings are modifiable, and any modifications made persist until program termination, although these modifications do not propagate back to the host environment: they can be used, for example, with <code><a href="../string/byte/strtok" title="c/string/byte/strtok">strtok</a></code>.</p> +<p>The size of the array pointed to by <code>argv</code> is at least <code>argc+1</code>, and the last element, <code>argv[argc]</code>, is guaranteed to be a null pointer.</p> +<p>The <code>main</code> function has several special properties:</p> +<div class="t-li1"> +<span class="t-li">1)</span> A prototype for this function cannot be supplied by the program.</div> <div class="t-li1"> +<span class="t-li">2)</span> If the return type of the main function is <a href="type#Compatible_types" title="c/language/type">compatible</a> with <code>int</code>, then the return from the initial call to main (but not the return from any subsequent, recursive, call) is equivalent to executing the <code><a href="../program/exit" title="c/program/exit">exit</a></code> function, with the value that the main function is returning passed as the argument (which then calls the functions registered with <code><a href="../program/atexit" title="c/program/atexit">atexit</a></code>, flushes and closes all streams, and deletes the files created with <code><a href="../io/tmpfile" title="c/io/tmpfile">tmpfile</a></code>, and returns control to the execution environment).</div> <div class="t-li1"> +<span class="t-li">3)</span> <table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>If the main function executes a <code>return</code> that specifies no value or, which is the same, reaches the terminating <code>}</code> without executing a <code>return</code>, the termination status returned to the host environment is undefined.</p> +</td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <p>If the return type of the main function is not <a href="type#Compatible_types" title="c/language/type">compatible</a> with <code>int</code> (e.g. <code>void main(void)</code>), the value returned to the host environment is unspecified. If the return type is compatible with <code>int</code> and control reaches the terminating <code>}</code>, the value returned to the environment is the same as if executing <code>return 0;</code>.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> +</div> <h3 id="Example"> Example</h3> <div class="t-example"> +<p>Demonstrates how to inform a program about where to find its input and where to write its results. Invocation: ./a.out indatafile outdatafile</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(int argc, char *argv[]) +{ + printf("argc = %d\n", argc); + for (int ndx = 0; ndx != argc; ++ndx) + printf("argv[%d] --> %s\n", ndx, argv[ndx]); + printf("argv[argc] = %p\n", (void*)argv[argc]); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">argc = 3 +argv[0] --> ./a.out +argv[1] --> indatafile +argv[2] --> outdatafile +argv[argc] = (nil)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 5.1.2.2.1 Program startup (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 5.1.2.2.1 Program startup (p: 10-11) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 5.1.2.2.1 Program startup (p: 13) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 5.1.2.2.1 Program startup (p: 12) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 5.1.2.2 Hosted environment </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/main_function" title="cpp/language/main function">C++ documentation</a></span> for <span class=""><span><code>main</code> function</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/main_function" class="_attribution-link">https://en.cppreference.com/w/c/language/main_function</a> + </p> +</div> |