doc/html/ref/c-library-startup.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >C library startup</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="C and math library overview"
  23 HREF="c-and-math-library-overview.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Thread safety"
  26 HREF="libc-thread-safety.html"><LINK
  27 REL="NEXT"
  28 TITLE="I/O Package (Device Drivers)"
  29 HREF="io.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="libc-thread-safety.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 13. C and math library overview</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="io.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="C-LIBRARY-STARTUP">C library startup</H1
  86 ><P
  87 >The C library includes a function declared as:</P
  88 ><TABLE
  89 BORDER="5"
  90 BGCOLOR="#E0E0F0"
  91 WIDTH="70%"
  92 ><TR
  93 ><TD
  94 ><PRE
  95 CLASS="PROGRAMLISTING"
  96 >void <TT
  97 CLASS="FUNCTION"
  98 >cyg_iso_c_start</TT
  99 >( void )</PRE
 100 ></TD
 101 ></TR
 102 ></TABLE
 103 ><P
 104 >This function is used to start an environment in which an
 105 ISO C style program can run in the most compatible way.</P
 106 ><P
 107 >What this function does is to create a thread which will invoke <TT
 108 CLASS="FUNCTION"
 109 >main()</TT
 110 > &#8212; normally
 111 considered a program's entry point. In particular, it can
 112 supply arguments to <TT
 113 CLASS="FUNCTION"
 114 >main()</TT
 115 > using the CYGDAT_LIBC_ARGUMENTS
 116 configuration option, and when returning from <TT
 117 CLASS="FUNCTION"
 118 >main()</TT
 119 >,
 120 or calling <TT
 121 CLASS="FUNCTION"
 122 >exit()</TT
 123 >, pending stdio file output
 124 is flushed and any functions registered with <TT
 125 CLASS="FUNCTION"
 126 >atexit()</TT
 127 > are
 128 invoked. This is all compliant with the ISO C standard in this respect. </P
 129 ><P
 130 >This thread starts execution when the <SPAN
 131 CLASS="emphasis"
 132 ><I
 133 CLASS="EMPHASIS"
 134 >eCos</I
 135 ></SPAN
 136 > scheduler
 137 is started. If the <SPAN
 138 CLASS="emphasis"
 139 ><I
 140 CLASS="EMPHASIS"
 141 >eCos</I
 142 ></SPAN
 143 > kernel package is not
 144 available (and hence there is no scheduler), then <TT
 145 CLASS="FUNCTION"
 146 >cyg_iso_c_start()</TT
 147 > will
 148 invoke the <TT
 149 CLASS="FUNCTION"
 150 >main()</TT
 151 > function directly, i.e.
 152 it will not return until the <TT
 153 CLASS="FUNCTION"
 154 >main()</TT
 155 > function
 156 returns. </P
 157 ><P
 158 >The <TT
 159 CLASS="FUNCTION"
 160 >main()</TT
 161 > function should be defined
 162 as the following, and if defined in a C&#0043;&#0043; file,
 163 should have &#8220;C&#8221; linkage: </P
 164 ><TABLE
 165 BORDER="5"
 166 BGCOLOR="#E0E0F0"
 167 WIDTH="70%"
 168 ><TR
 169 ><TD
 170 ><PRE
 171 CLASS="PROGRAMLISTING"
 172 >extern int <TT
 173 CLASS="FUNCTION"
 174 >main</TT
 175 >(
 176   int <SPAN
 177 CLASS="emphasis"
 178 ><I
 179 CLASS="EMPHASIS"
 180 >argc,</I
 181 ></SPAN
 182 >
 183   char *<SPAN
 184 CLASS="emphasis"
 185 ><I
 186 CLASS="EMPHASIS"
 187 >argv[] </I
 188 ></SPAN
 189 >)</PRE
 190 ></TD
 191 ></TR
 192 ></TABLE
 193 ><P
 194 >The thread that is started by <TT
 195 CLASS="FUNCTION"
 196 >cyg_iso_c_start()</TT
 197 > can
 198 be manipulated directly, if you wish. For example you can suspend
 199 it. The kernel C API needs a handle to do this, which is available
 200 by including the following in your source code.</P
 201 ><TABLE
 202 BORDER="5"
 203 BGCOLOR="#E0E0F0"
 204 WIDTH="70%"
 205 ><TR
 206 ><TD
 207 ><PRE
 208 CLASS="PROGRAMLISTING"
 209 >extern cyg_handle_t cyg_libc_main_thread;</PRE
 210 ></TD
 211 ></TR
 212 ></TABLE
 213 ><P
 214 >Then for example, you can suspend the thread with the line:</P
 215 ><TABLE
 216 BORDER="5"
 217 BGCOLOR="#E0E0F0"
 218 WIDTH="70%"
 219 ><TR
 220 ><TD
 221 ><PRE
 222 CLASS="PROGRAMLISTING"
 223 >cyg_thread_suspend( cyg_libc_main_thread );</PRE
 224 ></TD
 225 ></TR
 226 ></TABLE
 227 ><P
 228 >If you call <TT
 229 CLASS="FUNCTION"
 230 >cyg_iso_c_start()</TT
 231 > and
 232 do not provide your own <TT
 233 CLASS="FUNCTION"
 234 >main()</TT
 235 > function,
 236 the system will provide a <TT
 237 CLASS="FUNCTION"
 238 >main()</TT
 239 > for you
 240 which will simply return immediately.</P
 241 ><P
 242 >In the default configuration, <TT
 243 CLASS="FUNCTION"
 244 >cyg_iso_c_start()</TT
 245 > is
 246 invoked automatically by the <TT
 247 CLASS="FUNCTION"
 248 >cyg_package_start()</TT
 249 > function
 250 in the infrastructure configuration. This means that in the simplest
 251 case, your program can indeed consist of simply:</P
 252 ><TABLE
 253 BORDER="5"
 254 BGCOLOR="#E0E0F0"
 255 WIDTH="70%"
 256 ><TR
 257 ><TD
 258 ><PRE
 259 CLASS="PROGRAMLISTING"
 260 >int main( int argc, char *argv[] )
 261 {
 262  printf("Hello eCos\n");
 263 }</PRE
 264 ></TD
 265 ></TR
 266 ></TABLE
 267 ><P
 268 >If you override <TT
 269 CLASS="FUNCTION"
 270 >cyg_package_start()</TT
 271 > or <TT
 272 CLASS="FUNCTION"
 273 >cyg_start()</TT
 274 >,
 275 or disable the infrastructure configuration option CYGSEM_START_ISO_C_COMPATIBILITY
 276 then you must ensure that you call <TT
 277 CLASS="FUNCTION"
 278 >cyg_iso_c_start()</TT
 279 > yourself
 280 if you want to be able to have your program start at the entry point
 281 of <TT
 282 CLASS="FUNCTION"
 283 >main()</TT
 284 > automatically.</P
 285 ></DIV
 286 ><DIV
 287 CLASS="NAVFOOTER"
 288 ><HR
 289 ALIGN="LEFT"
 290 WIDTH="100%"><TABLE
 291 SUMMARY="Footer navigation table"
 292 WIDTH="100%"
 293 BORDER="0"
 294 CELLPADDING="0"
 295 CELLSPACING="0"
 296 ><TR
 297 ><TD
 298 WIDTH="33%"
 299 ALIGN="left"
 300 VALIGN="top"
 301 ><A
 302 HREF="libc-thread-safety.html"
 303 ACCESSKEY="P"
 304 >Prev</A
 305 ></TD
 306 ><TD
 307 WIDTH="34%"
 308 ALIGN="center"
 309 VALIGN="top"
 310 ><A
 311 HREF="ecos-ref.html"
 312 ACCESSKEY="H"
 313 >Home</A
 314 ></TD
 315 ><TD
 316 WIDTH="33%"
 317 ALIGN="right"
 318 VALIGN="top"
 319 ><A
 320 HREF="io.html"
 321 ACCESSKEY="N"
 322 >Next</A
 323 ></TD
 324 ></TR
 325 ><TR
 326 ><TD
 327 WIDTH="33%"
 328 ALIGN="left"
 329 VALIGN="top"
 330 >Thread safety</TD
 331 ><TD
 332 WIDTH="34%"
 333 ALIGN="center"
 334 VALIGN="top"
 335 ><A
 336 HREF="c-and-math-library-overview.html"
 337 ACCESSKEY="U"
 338 >Up</A
 339 ></TD
 340 ><TD
 341 WIDTH="33%"
 342 ALIGN="right"
 343 VALIGN="top"
 344 >I/O Package (Device Drivers)</TD
 345 ></TR
 346 ></TABLE
 347 ></DIV
 348 ></BODY
 349 ></HTML
 350 >