packages/language/c/libc/common/v2_0/doc/libc.sgml

   1 <!-- {{{ Banner                         -->
   2
   3 <!-- =============================================================== -->
   4 <!--                                                                 -->
   5 <!--     libc.sgml                                                   -->
   6 <!--                                                                 -->
   7 <!--     eCos C Library                                              -->
   8 <!--                                                                 -->
   9 <!-- =============================================================== -->
  10 <!-- ####COPYRIGHTBEGIN####                                          -->
  11 <!--                                                                 -->
  12 <!-- =============================================================== -->
  13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
  14 <!-- This material may be distributed only subject to the terms      -->
  15 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  16 <!-- or later (the latest version is presently available at          -->
  17 <!-- http://www.opencontent.org/openpub/)                            -->
  18 <!-- Distribution of the work or derivative of the work in any       -->
  19 <!-- standard (paper) book form is prohibited unless prior           -->
  20 <!-- permission obtained from the copyright holder                   -->
  21 <!-- =============================================================== -->
  22 <!--                                                                 -->
  23 <!-- ####COPYRIGHTEND####                                            -->
  24 <!-- =============================================================== -->
  25 <!-- #####DESCRIPTIONBEGIN####                                       -->
  26 <!--                                                                 -->
  27 <!-- ####DESCRIPTIONEND####                                          -->
  28 <!-- =============================================================== -->
  29
  30 <!-- }}} -->
  31
  32 <PART id="libc">
  33 <TITLE>The ISO Standard C and Math Libraries</TITLE>
  34 <CHAPTER id="c-and-math-library-overview">
  35 <TITLE><!-- <xref> -->C and math library overview</TITLE>
  36 <anchor id="iso-c-and-math-libraries">
  37 <PARA><EMPHASIS>eCos</EMPHASIS> provides compatibility with the
  38         ISO 9899:1990 specification for the standard C library, which
  39         is essentially the same as the better-known ANSI C3.159-1989
  40         specification (C-89).</PARA>
  41 <PARA>There are three aspects of this compatibility supplied by <EMPHASIS>eCos</EMPHASIS>.
  42 First there is a <!-- <index></index> --><firstterm>C library</firstterm> which
  43 implements the functions defined by the ISO standard, except for the
  44 mathematical functions. This is provided by the eCos C library
  45 packages. </PARA>
  46 <PARA>Then <EMPHASIS>eCos</EMPHASIS> provides a <!-- <index></index> -->math
  47 library, which implements the mathematical functions from the ISO
  48 C library. This distinction between C and math libraries is frequently
  49 drawn &mdash; most standard C library implementations provide
  50 separate linkable files for the two, and the math library contains
  51 all the functions from the <filename>math.h</filename> header
  52 file.</PARA>
  53 <PARA>There is a third element to the ISO C library, which is the
  54 environment in which applications run when they use the standard
  55 C library. This environment is set up by the C library startup procedure
  56 (<xref linkend="c-library-startup">)
  57 and it provides (among other things) a <FUNCTION>main()</FUNCTION> entry
  58 point function, an <FUNCTION>exit()</FUNCTION> function that
  59 does the cleanup required by the standard (including handlers registered
  60 using the <FUNCTION>atexit()</FUNCTION> function), and an environment
  61 that can be read with <FUNCTION>getenv()</FUNCTION>. </PARA>
  62 <PARA>The description in this manual focuses on the <EMPHASIS>eCos</EMPHASIS>-specific
  63 aspects of the C library (mostly related to <EMPHASIS>eCos</EMPHASIS>'s
  64 configurability) as well as mentioning the omissions from the standard
  65 in this release. We do not attempt to define the semantics of each
  66 function, since that information can be found in the ISO, ANSI,
  67 POSIX and IEEE standards, and the many good books that have been
  68 written about the standard C library, that cover usage of these
  69 functions in a more general and useful way.</PARA>
  70 <SECT1 id="include-non-iso-functions">
  71 <TITLE>Included non-ISO functions</TITLE>
  72 <PARA>The following functions from the <!-- <index></index> -->POSIX specification
  73 are included for convenience: </PARA>
  74 <PARA>  <literal>extern char **</literal><EMPHASIS>environ</EMPHASIS> variable
  75 (for setting up the environment for use with <FUNCTION>getenv()</FUNCTION>)</PARA>
  76 <PARA>  <FUNCTION>_exit()</FUNCTION> </PARA>
  77 <PARA>  <FUNCTION>strtok_r()</FUNCTION> </PARA>
  78 <PARA>  <FUNCTION>rand_r()</FUNCTION> </PARA>
  79 <PARA>  <FUNCTION>asctime_r()</FUNCTION> </PARA>
  80 <PARA>  <FUNCTION>ctime_r()</FUNCTION> </PARA>
  81 <PARA>  <FUNCTION>localtime_r()</FUNCTION> </PARA>
  82 <PARA>  <FUNCTION>gmtime_r()</FUNCTION> </PARA>
  83 <PARA><EMPHASIS>eCos</EMPHASIS> provides the following additional
  84 implementation-specific functions within the standard C library
  85 to adjust the date and time settings:</PARA>
  86 <PROGRAMLISTING>void <FUNCTION>cyg_libc_time_setdst</FUNCTION>(
  87   cyg_libc_time_dst state
  88 );</PROGRAMLISTING>
  89 <PARA>This function sets the state of Daylight Savings Time. The
  90 values for state are:</PARA>
  91 <PROGRAMLISTING>CYG_LIBC_TIME_DSTNA   unknown
  92 CYG_LIBC_TIME_DSTOFF  off
  93 CYG_LIBC_TIME_DSTON   on</PROGRAMLISTING>
  94
  95 <PROGRAMLISTING>void <FUNCTION>cyg_libc_time_setzoneoffsets</FUNCTION>(
  96   time_t stdoffset, time_t dstoffset
  97 );</PROGRAMLISTING>
  98 <PARA>This function sets the offsets from UTC used when Daylight
  99 Savings Time is enabled or disabled. The offsets are in time_t&rsquo;s,
 100 which are seconds in the current inplementation.</PARA>
 101 <PROGRAMLISTING><FUNCTION>Cyg_libc_time_dst cyg_libc_time_getzoneoffsets</FUNCTION>(
 102   time_t *stdoffset, time_t *dstoffset
 103 );</PROGRAMLISTING>
 104 <PARA>This function retrieves the current setting for Daylight Savings
 105 Time along with the offsets used for both STD and DST. The offsets
 106 are both in time_t&rsquo;s, which are seconds in the
 107 current implementation.</PARA>
 108 <PROGRAMLISTING><FUNCTION>cyg_bool cyg_libc_time_settime</FUNCTION>(
 109   time_t utctime
 110 );</PROGRAMLISTING>
 111 <PARA>This function sets the current time for the system The time
 112 is specified as a <type>time_t</type> in UTC.
 113 It returns non-zero on error.</PARA>
 114 </SECT1>
 115 <SECT1 id="math-library-compatibility-modes">
 116 <TITLE>Math library compatibility modes</TITLE>
 117 <PARA>This math library is capable of being operated in several
 118 different compatibility modes. These options deal solely with how
 119 errors are handled. </PARA>
 120 <PARA>There are 4 compatibility modes: ANSI/POSIX 1003.1;
 121 IEEE-754; X/Open Portability Guide issue 3 (XPG3); and
 122 System V Interface Definition Edition 3. </PARA>
 123 <PARA>In <!-- <index></index> -->IEEE mode, the <function>matherr()</function> function
 124 (see below) is never called, no warning messages are printed on
 125 the stderr output stream, and errno is never set. </PARA>
 126 <PARA>In <!-- <index></index> -->ANSI/POSIX mode, errno is set correctly,
 127 but <function>matherr()</function> is never called and no warning messages
 128 are printed on the stderr output stream. </PARA>
 129 <PARA>In <!-- <index></index> -->X/Open mode, errno is set correctly,
 130 <function>matherr()</function> is called, but no warning messages are printed
 131 on the stderr output stream. </PARA>
 132 <PARA>In <!-- <index></index> -->SVID mode, functions which overflow return
 133 a value HUGE (defined in <filename>math.h</filename>), which is the maximum
 134 single precision floating point value (as opposed to
 135 HUGE_VAL which is meant to stand for infinity). errno is
 136 set correctly and <function>matherr()</function> is called. If
 137 <function>matherr()</function> returns 0, warning messages are printed on
 138 the stderr output stream for some errors. </PARA>
 139 <PARA>The mode can be compiled-in as IEEE-only, or any one of the
 140 above methods settable at run-time. </PARA>
 141 <NOTE>
 142 <PARA>This math library assumes that the hardware (or software floating
 143 point emulation) supports IEEE-754 style arithmetic, 32-bit 2's
 144 complement integer arithmetic, doubles are in 64-bit IEEE-754 format.</PARA>
 145 </NOTE>
 146 <SECT2>
 147 <TITLE><!-- <index></index> -->     matherr()</TITLE>
 148 <PARA>As mentioned above, in X/Open or SVID modes, the user
 149             can supply a function <FUNCTION>matherr()</FUNCTION> of
 150             the form:</PARA>
 151 <PROGRAMLISTING>int <FUNCTION>matherr</FUNCTION>( struct exception *e )
 152 </PROGRAMLISTING>
 153 <PARA>where struct exception is defined as:</PARA>
 154 <PROGRAMLISTING>struct exception {
 155  int type;
 156  char *name;
 157  double arg1, arg2, retval;
 158 }; </PROGRAMLISTING>
 159 <PARA>type is the exception type and is one of:</PARA>
 160 <VARIABLELIST>
 161 <VARLISTENTRY>
 162 <TERM>DOMAIN    </TERM>
 163 <LISTITEM>
 164
 165 <PARA>argument domain exception</PARA>
 166 </LISTITEM>
 167 </VARLISTENTRY>
 168 <VARLISTENTRY>
 169 <TERM>SING      </TERM>
 170 <LISTITEM>
 171
 172 <PARA>argument singularity</PARA>
 173 </LISTITEM>
 174 </VARLISTENTRY>
 175 <VARLISTENTRY>
 176 <TERM>OVERFLOW  </TERM>
 177 <LISTITEM>
 178
 179 <PARA>overflow range exception</PARA>
 180 </LISTITEM>
 181 </VARLISTENTRY>
 182 <VARLISTENTRY>
 183 <TERM>UNDERFLOW         </TERM>
 184 <LISTITEM>
 185
 186 <PARA>underflow range exception</PARA>
 187 </LISTITEM>
 188 </VARLISTENTRY>
 189 <VARLISTENTRY>
 190 <TERM>TLOSS     </TERM>
 191 <LISTITEM>
 192
 193 <PARA>total loss of significance</PARA>
 194 </LISTITEM>
 195 </VARLISTENTRY>
 196 <VARLISTENTRY>
 197 <TERM>PLOSS     </TERM>
 198 <LISTITEM>
 199
 200 <PARA>partial loss of significance</PARA>
 201 </LISTITEM>
 202 </VARLISTENTRY>
 203 </VARIABLELIST>
 204 <PARA><parameter>name</parameter> is a string containing the name of the
 205 function</PARA>
 206 <PARA><parameter>arg1</parameter> and <parameter>arg2</parameter> are the
 207 arguments passed to the function</PARA>
 208 <PARA><parameter>retval</parameter> is the default value that will be returned
 209 by the function, and can be changed by <FUNCTION>matherr()</FUNCTION></PARA>
 210 <NOTE>
 211 <PARA>matherr must have &ldquo;C&rdquo; linkage, not &ldquo;C&plus;&plus;&rdquo; linkage.</PARA>
 212 </NOTE>
 213 <PARA>If matherr returns zero, or the user doesn't supply
 214 their own matherr, then the following <EMPHASIS>usually</EMPHASIS> happens
 215 in SVID mode:</PARA><!-- FIXME: must convert this table -->
 216           <table>
 217 <title>Behavior of math exception handling</title>
 218 <tgroup cols="2">
 219 <thead>
 220 <row>
 221   <entry>Type</entry>
 222   <entry>Behavior</entry
 223 </row>
 224 </thead>
 225 <tbody>
 226 <row>
 227 <entry>DOMAIN</entry><entry>0.0 returned,
 228 errno=EDOM, and a message printed on stderr</entry></row>
 229 <row>
 230 <entry>SING</entry><entry>HUGE of appropriate
 231 sign is returned, errno=EDOM, and a message is printed
 232 on stderr</entry></row>
 233 <row>
 234 <entry>OVERFLOW</entry><entry>HUGE of
 235 appropriate sign is returned, and errno=ERANGE</entry></row>
 236 <row>
 237 <entry>UNDERFLOW</entry><entry>0.0 is
 238 returned and errno=ERANGE</entry></row>
 239 <row>
 240 <entry>TLOSS</entry><entry>0.0 is returned,
 241 errno=ERANGE, and a message is printed on stderr</entry></row>
 242 <row>
 243 <entry>PLOSS</entry><entry>The current
 244 implementation doesn't return this type</entry></row>
 245 </tbody>
 246 </tgroup>
 247 </table>
 248 <!-- -->
 249 <PARA>X/Open mode is similar except that the message is
 250 not printed on stderr and HUGE_VAL is used in place of
 251 HUGE</PARA>
 252 </SECT2>
 253 <SECT2>
 254 <TITLE>Thread-safety and re-entrancy</TITLE>
 255 <PARA>With the appropriate configuration options set below, the
 256 math library is fully thread-safe if:</PARA>
 257 <ITEMIZEDLIST>
 258 <LISTITEM>
 259 <PARA>Depending on the compatibility mode, the
 260                 setting of the errno variable from the C library is
 261                 thread-safe</PARA>
 262 </LISTITEM>
 263 <LISTITEM>
 264 <PARA>Depending on the compatibility mode, sending error messages
 265 to the stderr output stream using the C library
 266 <FUNCTION>fputs()</FUNCTION>
 267  function is thread-safe </PARA>
 268 </LISTITEM>
 269 <LISTITEM>
 270 <PARA>Depending on the compatibility mode, the user-supplied
 271 <FUNCTION>matherr()</FUNCTION>
 272  function and anything it depends on are thread-safe </PARA>
 273 </LISTITEM>
 274 </ITEMIZEDLIST>
 275 <PARA>In addition, with the exception of the <FUNCTION>gamma*()</FUNCTION> and <FUNCTION>lgamma*()</FUNCTION> functions,
 276 the math library is reentrant (and thus safe to use from interrupt handlers)
 277 if the Math library is always in IEEE mode.</PARA>
 278 </SECT2>
 279 </SECT1>
 280 <SECT1 id="libc-implementation-details">
 281 <TITLE>Some implementation details</TITLE>
 282 <PARA>Here are some details about the <!-- <index></index> -->implementation
 283 which might be interesting, although they do not affect the ISO-defined
 284 semantics of the library. </PARA>
 285 <ITEMIZEDLIST>
 286 <LISTITEM>
 287 <PARA>It is possible to configure
 288 <EMPHASIS>eCos</EMPHASIS>
 289  to have the standard C library without the kernel. You might want
 290 to do this to use less memory. But if you disable the kernel, you
 291 will be unable to use memory allocation, thread-safety and certain
 292 stdio functions such as input. Other C library functionality is
 293 unaffected.</PARA>
 294 </LISTITEM>
 295 <LISTITEM>
 296 <PARA>The opaque type returned by
 297 <FUNCTION>clock()</FUNCTION>
 298  is called clock_t, and is implemented as a 64 bit integer.
 299 The value returned by
 300 <FUNCTION>clock()</FUNCTION>
 301  is only correct if the kernel is configured with real-time clock
 302 support, as determined by the CYGVAR_KERNEL_COUNTERS_CLOCK
 303 configuration option in
 304 <FILENAME>kernel.h</FILENAME>
 305 .</PARA>
 306 </LISTITEM>
 307 <LISTITEM>
 308 <PARA>The FILE type is not implemented as a structure, but rather
 309 as a CYG_ADDRESS. </PARA>
 310 </LISTITEM>
 311 <LISTITEM>
 312 <PARA>The GNU C compiler will place its own <EMPHASIS>built-in</EMPHASIS> implementations
 313 instead of some C library functions. This can be turned off with
 314 the <EMPHASIS>-fno-builtin</EMPHASIS> option. The functions affected
 315 by this are
 316 <FUNCTION>abs()</FUNCTION>
 317 ,
 318 <FUNCTION>cos()</FUNCTION>
 319 ,
 320 <FUNCTION>fabs()</FUNCTION>
 321 ,
 322 <FUNCTION>labs()</FUNCTION>
 323 ,
 324 <FUNCTION>memcmp()</FUNCTION>
 325 ,
 326 <FUNCTION>memcpy()</FUNCTION>
 327 ,
 328 <FUNCTION>sin()</FUNCTION>
 329 ,
 330 <FUNCTION>sqrt()</FUNCTION>
 331 ,
 332 <FUNCTION>strcmp()</FUNCTION>
 333 ,
 334 <FUNCTION>strcpy()</FUNCTION>
 335 , and
 336 <FUNCTION>strlen()</FUNCTION>
 337 .</PARA>
 338 </LISTITEM>
 339 <LISTITEM>
 340 <PARA>For faster execution speed you should avoid this option
 341 and let the compiler use its built-ins. This can be turned off by
 342 invoking
 343 <EMPHASIS>GCC</EMPHASIS>
 344  with the <EMPHASIS>-fno-builtin</EMPHASIS> option. </PARA>
 345 </LISTITEM>
 346 <LISTITEM>
 347 <PARA><FUNCTION>memcpy()</FUNCTION>
 348  and
 349 <FUNCTION>memset()</FUNCTION>
 350  are located in the infrastructure package, not in the C library
 351 package. This is because the compiler calls these functions, and
 352 the kernel needs to resolve them even if the C library is not configured. </PARA>
 353 </LISTITEM>
 354 <LISTITEM>
 355 <PARA>Error codes such as EDOM and ERANGE, as well as
 356 <FUNCTION>strerror()</FUNCTION>
 357 , are implemented in the <EMPHASIS>error</EMPHASIS> package. The
 358 error package is separate from the rest of the C and math libraries
 359 so that the rest of
 360 <EMPHASIS>eCos</EMPHASIS>
 361  can use these error handling facilities even if the C library is
 362 not configured. </PARA>
 363 </LISTITEM>
 364 <LISTITEM>
 365 <PARA>When
 366 <FUNCTION>free()</FUNCTION>
 367  is invoked, heap memory will normally be coalesced. If the CYGSEM_KERNEL_MEMORY_COALESCE
 368 configuration parameter is not set, memory will not be coalesced,
 369 which might cause programs to fail. </PARA>
 370 </LISTITEM>
 371 <LISTITEM>
 372 <PARA>Signals, as implemented by
 373 <filename>&lt;signal.h&gt;</filename>, are guaranteed to work
 374 correctly if raised using the
 375 <FUNCTION>raise()</FUNCTION>
 376  function from a normal working program context. Using signals from
 377 within an ISR or DSR context is not expected to work. Also, it is
 378 not guaranteed that if CYGSEM_LIBC_SIGNALS_HWEXCEPTIONS
 379 is set, that handling a signal using
 380 <FUNCTION>signal()</FUNCTION>
 381  will necessarily catch that form of exception. For example, it
 382 may be expected that a divide-by-zero error would be caught by handling
 383 <varname>SIGFPE</varname>. However it depends on the underlying HAL implementation to implement
 384 the required hardware exception. And indeed the hardware itself
 385 may not be capable of detecting these exceptions so it may not be
 386 possible for the HAL implementer to do this in any case. Despite
 387 this lack of guarantees in this respect, the signals implementation
 388 is still ISO C compliant since ISO C does not offer any such guarantees
 389 either. </PARA>
 390 </LISTITEM>
 391 <LISTITEM>
 392 <PARA>The
 393 <FUNCTION>getenv()</FUNCTION>
 394  function is implemented (unless the CYGPKG_LIBC_ENVIRONMENT configuration
 395 option is turned off), but there is no shell or
 396 <FUNCTION>putenv()</FUNCTION>
 397  function to set the environment dynamically. The environment is
 398 set in a global variable environ, declared as:</PARA>
 399 <PROGRAMLISTING>extern char **environ; // Standard environment definition</PROGRAMLISTING>
 400 <PARA>The environment can be statically initialized at startup time
 401 using the CYGDAT_LIBC_DEFAULT_ENVIRONMENT
 402 option. If so, remember that the final entry of the array initializer
 403 must be NULL. </PARA>
 404 </LISTITEM>
 405 </ITEMIZEDLIST>
 406 <PARA>Here is a minimal <EMPHASIS>eCos</EMPHASIS> program which
 407 demonstrates the use of environments (see also the test case in <filename>language/c/libc/current/tests/stdlib/getenv.c</filename>): </PARA>
 408 <PROGRAMLISTING>#include &lt;stdio.h&gt;
 409 #include &lt;stdlib.h&gt; // Main header for stdlib functions
 410
 411 extern char **environ; // Standard environment definition
 412
 413 int
 414 main( int argc, char *argv[] )
 415 {
 416  char *str;
 417  char *env[] = { "PATH=/usr/local/bin:/usr/bin",
 418  "HOME=/home/fred",
 419  "TEST=1234=5678",
 420  "home=hatstand",
 421  NULL };
 422
 423  printf("Display the current PATH environment variable\n");
 424
 425  environ = (char **)&amp;env;
 426
 427  str = getenv("PATH");
 428
 429  if (str==NULL) {
 430   printf("The current PATH is unset\n");
 431  } else {
 432   printf("The current PATH is \"%s\"\n", str);
 433  }
 434  return 0;
 435 } </PROGRAMLISTING>
 436 </SECT1>
 437 <SECT1 id="libc-thread-safety">
 438 <TITLE><!-- <index></index> -->Thread safety</TITLE>
 439 <PARA>The ISO C library has configuration options that control thread
 440 safety, i.e. working behavior if multiple threads call the same
 441 function at the same time.</PARA>
 442 <PARA>The following functionality has to be configured correctly,
 443 or used carefully in a multi-threaded environment:</PARA>
 444 <ITEMIZEDLIST>
 445 <LISTITEM>
 446 <PARA><function>mblen()</function></para>
 447 </listitem>
 448 <listitem>
 449 <para><function>mbtowc()</function></para>
 450 </listitem>
 451 <listitem>
 452 <para><function>wctomb()</function></para>
 453 </listitem>
 454 <listitem>
 455 <para>
 456 <FUNCTION>printf()</FUNCTION>
 457  (and all standard I/O functions except for
 458 <FUNCTION>sprintf()</FUNCTION>
 459  and
 460 <FUNCTION>sscanf()</FUNCTION></PARA>
 461 </LISTITEM>
 462 <LISTITEM>
 463 <PARA><FUNCTION>strtok()</FUNCTION></PARA>
 464 </LISTITEM>
 465 <LISTITEM>
 466 <PARA><FUNCTION>rand()</FUNCTION>
 467  and
 468 <FUNCTION>srand()</FUNCTION></PARA>
 469 </LISTITEM>
 470 <LISTITEM>
 471 <PARA><FUNCTION>signal()</FUNCTION>
 472  and
 473 <FUNCTION>raise()</FUNCTION></PARA>
 474 </LISTITEM>
 475 <LISTITEM>
 476 <PARA><FUNCTION>asctime()</FUNCTION>
 477 ,
 478 <FUNCTION>ctime()</FUNCTION>
 479 ,
 480 <FUNCTION>gmtime()</FUNCTION>
 481 , and
 482 <FUNCTION>localtime()</FUNCTION></PARA>
 483 </LISTITEM>
 484 <LISTITEM>
 485 <PARA>the
 486 <FUNCTION>errno</FUNCTION>
 487  variable</PARA>
 488 </LISTITEM>
 489 <LISTITEM>
 490 <PARA>the
 491 <FUNCTION>environ</FUNCTION>
 492  variable</PARA>
 493 </LISTITEM>
 494 <LISTITEM>
 495 <PARA>date and time settings</PARA>
 496 </LISTITEM>
 497 </ITEMIZEDLIST>
 498 <PARA>In some cases, to make <EMPHASIS>eCos</EMPHASIS> development
 499 easier, functions are provided (as specified by POSIX 1003.1) that define
 500 re-entrant alternatives, i.e. <FUNCTION>rand_r()</FUNCTION>, <FUNCTION>strtok_r()</FUNCTION>, <FUNCTION>asctime_r()</FUNCTION>, <FUNCTION>ctime_r()</FUNCTION>, <FUNCTION>gmtime_r()</FUNCTION>,
 501 and <FUNCTION>localtime_r()</FUNCTION>. In other cases,
 502 configuration options are provided that control either locking of functions
 503 or their shared data, such as with standard I/O streams,
 504 or by using per-thread data, such as with the <FUNCTION>errno</FUNCTION> variable.</PARA>
 505 <PARA>In some other cases, like the setting of date and time, no
 506 re-entrant or thread-safe alternative or configuration is provided
 507 as it is simply not a worthwhile addition (date and time should
 508 rarely need to be set.)</PARA>
 509 </SECT1>
 510 <SECT1 id="c-library-startup">
 511 <TITLE><!-- <index></index> --><!-- <xref> -->C library startup</TITLE>
 512 <PARA>The C library includes a function declared as:</PARA>
 513 <PROGRAMLISTING>void <FUNCTION>cyg_iso_c_start</FUNCTION>( void )</PROGRAMLISTING>
 514 <PARA>This function is used to start an environment in which an
 515 ISO C style program can run in the most compatible way.</PARA>
 516 <PARA>What this function does is to create a thread which will invoke <FUNCTION>main()</FUNCTION> &mdash; normally
 517 considered a program's entry point. In particular, it can
 518 supply arguments to <FUNCTION>main()</FUNCTION> using the CYGDAT_LIBC_ARGUMENTS
 519 configuration option, and when returning from <FUNCTION>main()</FUNCTION>,
 520 or calling <FUNCTION>exit()</FUNCTION>, pending stdio file output
 521 is flushed and any functions registered with <FUNCTION>atexit()</FUNCTION> are
 522 invoked. This is all compliant with the ISO C standard in this respect. </PARA>
 523 <PARA>This thread starts execution when the <EMPHASIS>eCos</EMPHASIS> scheduler
 524 is started. If the <EMPHASIS>eCos</EMPHASIS> kernel package is not
 525 available (and hence there is no scheduler), then <FUNCTION>cyg_iso_c_start()</FUNCTION> will
 526 invoke the <FUNCTION>main()</FUNCTION> function directly, i.e.
 527 it will not return until the <FUNCTION>main()</FUNCTION> function
 528 returns. </PARA>
 529 <PARA>The <FUNCTION>main()</FUNCTION> function should be defined
 530 as the following, and if defined in a C&plus;&plus; file,
 531 should have &ldquo;C&rdquo; linkage: </PARA>
 532 <PROGRAMLISTING>extern int <FUNCTION>main</FUNCTION>(
 533   int <EMPHASIS>argc,</EMPHASIS>
 534   char *<EMPHASIS>argv[] </EMPHASIS>)</PROGRAMLISTING>
 535 <PARA>The thread that is started by <FUNCTION>cyg_iso_c_start()</FUNCTION> can
 536 be manipulated directly, if you wish. For example you can suspend
 537 it. The kernel C API needs a handle to do this, which is available
 538 by including the following in your source code.</PARA>
 539 <PROGRAMLISTING>extern cyg_handle_t cyg_libc_main_thread;</PROGRAMLISTING>
 540 <PARA>Then for example, you can suspend the thread with the line:</PARA>
 541 <PROGRAMLISTING>cyg_thread_suspend( cyg_libc_main_thread );</PROGRAMLISTING>
 542 <PARA>If you call <FUNCTION>cyg_iso_c_start()</FUNCTION> and
 543 do not provide your own <FUNCTION>main()</FUNCTION> function,
 544 the system will provide a <FUNCTION>main()</FUNCTION> for you
 545 which will simply return immediately.</PARA>
 546 <PARA>In the default configuration, <FUNCTION>cyg_iso_c_start()</FUNCTION> is
 547 invoked automatically by the <FUNCTION>cyg_package_start()</FUNCTION> function
 548 in the infrastructure configuration. This means that in the simplest
 549 case, your program can indeed consist of simply:</PARA>
 550 <PROGRAMLISTING>int main( int argc, char *argv[] )
 551 {
 552  printf("Hello eCos\n");
 553 }</PROGRAMLISTING>
 554 <PARA>If you override <FUNCTION>cyg_package_start()</FUNCTION> or <FUNCTION>cyg_start()</FUNCTION>,
 555 or disable the infrastructure configuration option CYGSEM_START_ISO_C_COMPATIBILITY
 556 then you must ensure that you call <FUNCTION>cyg_iso_c_start()</FUNCTION> yourself
 557 if you want to be able to have your program start at the entry point
 558 of <FUNCTION>main()</FUNCTION> automatically.</PARA>
 559 </SECT1>
 560 </CHAPTER>
 561 </PART>