path: root/devdocs/c/language%2Fmain_function.html

    <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> &gt; 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 &lt;stdio.h&gt;
 
int main(int argc, char *argv[])
{
    printf("argc = %d\n", argc);
    for (int ndx = 0; ndx != argc; ++ndx)
        printf("argv[%d] --&gt; %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] --&gt; ./a.out
argv[1] --&gt; indatafile
argv[2] --&gt; 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">
    &copy; 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>