C library startup

The C library includes a function declared as:

This function is used to start an environment in which an ISO C style program can run in the most compatible way.

What this function does is to create a thread which will invoke main() — normally considered a program's entry point. In particular, it can supply arguments to main() using the CYGDAT_LIBC_ARGUMENTS configuration option (see the section called Option: Arguments to main() in Chapter 16), and when returning from main(), or calling exit(), pending stdio file output is flushed and any functions registered with atexit() are invoked. This is all compliant with the ISO C standard in this respect.

This thread starts execution when the eCos scheduler is started. If the eCos kernel package is not available (and hence there is no scheduler), then cyg_iso_c_start() will invoke the main() function directly, i.e. it will not return until the main() function returns.

The main() function should be defined as the following, and if defined in a C++ file, should have "C" linkage:

The thread that is started by cyg_iso_c_start() can be manipulated directly, if you wish. For example you can suspend it. The kernel C API needs a handle to do this, which is available by including the following in your source code.

extern cyg_handle_t cyg_libc_main_thread;

Then for example, you can suspend the thread with the line:

cyg_thread_suspend( cyg_libc_main_thread );

If you call cyg_iso_c_start() and do not provide your own main() function, the system will provide a main() for you which will simply return immediately.

In the default configuration, cyg_iso_c_start() is invoked automatically by the cyg_package_start() function in the infrastructure configuration. This means that in the simplest case, your program can indeed consist of simply:

int main( int argc, char *argv[] )
{
  printf("Hello eCos\n");
}

If you override cyg_package_start() or cyg_start(), or disable the infrastructure configuration option CYGSEM_START_ISO_C_COMPATIBILITY then you must ensure that you call cyg_iso_c_start() yourself if you want to be able to have your program start at the entry point of main() automatically.