doc: Switch main return type from void to int.

As both C and C++ standards require applications running under an OS to
return 'int', adapt that for Zephyr to align with those standard. This also
eliminates errors when building with clang when not using -ffreestanding,
and reduces the need for compiler flags to silence warnings for both clang
and gcc.

Signed-off-by: Keith Packard <keithp@keithp.com>

doc/develop/languages/c/index.rst

@@ -12,6 +12,11 @@ available as part of the C header files under the :file:`include` directory, so
 writing Zephyr applications in C gives the developers access to the most
 features.
 
+The ``main()`` function must have the return type of ``int`` as Zephyr
+applications run in a "hosted" environment as defined by the C
+standard. Applications must return zero (0) from main. All non-zero return
+values are reserved.
+
 .. _c_standards:
 
 Language Standards

doc/develop/languages/cpp/index.rst

@@ -31,10 +31,9 @@ or a **cxx** suffix are compiled using the C++ compiler. For example,
 :file:`myCplusplusApp.cpp` is compiled using C++.
 
 The C++ standard requires the ``main()`` function to have the return type of
-``int`` while Zephyr uses ``void`` by default. If your ``main()`` is defined in
+``int``. Your ``main()`` must be defined as ``int main(void)``. Zephyr ignores
-a C++ source file, you must select :kconfig:option:`CONFIG_CPP_MAIN` in the
+the return value from main, so applications should not return status
-application configuration file so that Zephyr uses ``int main(void)`` instead
+information and should, instead, return zero.
-of ``void main(void)``.
 
 .. note::
     Do not use C++ for kernel, driver, or system initialization code.

doc/kernel/services/scheduling/index.rst

@@ -295,7 +295,7 @@ k_cpu_idle() unconditionally unmasks interrupts.
         k_sem_give(&my_sem);
     }
 
-    void main(void)
+    int main(void)
     {
         k_sem_init(&my_sem, 0, 1);
 
@@ -337,7 +337,7 @@ like in this example.
         k_sem_give(&my_sem);
     }
 
-    void main(void)
+    int main(void)
     {
         k_sem_init(&my_sem, 0, 1);
 
@@ -377,7 +377,7 @@ i.e. not doing any real work, like in this example below.
 
 .. code-block:: c
 
-    void main(void)
+    int main(void)
     {
         /* ... do some system/application initialization */
 

doc/kernel/services/synchronization/condvar.rst

@@ -77,7 +77,7 @@ The following code waits on the condition variable.
     K_MUTEX_DEFINE(mutex);
     K_CONDVAR_DEFINE(condvar)
 
-    void main(void)
+    int main(void)
     {
         k_mutex_lock(&mutex, K_FOREVER);
 

doc/kernel/services/threads/system_threads.rst

@@ -62,7 +62,7 @@ The function used by a real application can be as complex as needed.
 
 .. code-block:: c
 
-    void main(void)
+    int main(void)
     {
         /* initialize a semaphore */
 	...

doc/services/debugging/gdbstub.rst

@@ -217,7 +217,7 @@ how GDB stub works.
 
          (gdb) list
          27
-         28     void main(void)
+         28     int main(void)
          29     {
          30             int ret;
          31

doc/services/device_mgmt/mcumgr_callbacks.rst

@@ -54,7 +54,7 @@ application code as per:
         return MGMT_ERR_EOK;
     }
 
-    void main()
+    int main()
     {
         my_callback.callback = my_function;
         my_callback.event_id = MGMT_EVT_OP_CMD_DONE;
@@ -170,7 +170,7 @@ An example of selectively denying file access:
         return MGMT_ERR_EOK;
     }
 
-    void main()
+    int main()
     {
         my_callback.callback = my_function;
         my_callback.event_id = MGMT_EVT_OP_FS_MGMT_FILE_ACCESS;

doc/services/logging/index.rst

@@ -314,7 +314,7 @@ Following snippet shows how logging can be processed in simple forever loop.
 
    #include <zephyr/log_ctrl.h>
 
-   void main(void)
+   int main(void)
    {
    	LOG_INIT();
    	/* If multithreading is enabled provide thread id to the logging. */

doc/services/settings/index.rst

@@ -263,7 +263,7 @@ up from where it was before restart.
         .h_set = foo_settings_set
     };
 
-    void main(void)
+    int main(void)
     {
         settings_subsys_init();
         settings_register(&my_conf);

doc/services/shell/index.rst

@@ -271,7 +271,7 @@ and a function :c:func:`shell_execute_cmd`, as shown in this example:
 
 .. code-block:: c
 
-	void main(void)
+	int main(void)
 	{
 		/* Below code will execute "clear" command on a DUMMY backend */
 		shell_execute_cmd(NULL, "clear");
@@ -660,7 +660,7 @@ The following code shows a simple use case of this library:
 
 .. code-block:: c
 
-	void main(void)
+	int main(void)
 	{
 
 	}

doc/services/smf/index.rst

@@ -181,7 +181,7 @@ Code::
 		[S2] = SMF_CREATE_STATE(s2_entry, s2_run, NULL),
 	};
 
-	void main(void)
+	int main(void)
 	{
 		int32_t ret;
 
@@ -285,7 +285,7 @@ Code::
 		[S2] = SMF_CREATE_STATE(NULL, s2_run, NULL, NULL),
 	};
 
-	void main(void)
+	int main(void)
 	{
 		int32_t ret;
 
@@ -416,7 +416,7 @@ Code::
 		k_event_post(&s_obj.smf_event, EVENT_BTN_PRESS);
 	}
 
-	void main(void)
+	int main(void)
 	{
 		int ret;
 

doc/services/zbus/index.rst

@@ -331,7 +331,7 @@ Zbus subsystem also implements :ref:`Iterable Sections <iterable_sections_api>`
             ++count;
             return true;
     }
-    void main(void)
+    int main(void)
     {
             LOG_DBG("Channel list:");
             count = 0;