doc/html/ref/libc-implementation-details.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 >Some implementation details</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="Math library compatibility modes"
  26 HREF="math-library-compatibility-modes.html"><LINK
  27 REL="NEXT"
  28 TITLE="Thread safety"
  29 HREF="libc-thread-safety.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="math-library-compatibility-modes.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="libc-thread-safety.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="LIBC-IMPLEMENTATION-DETAILS">Some implementation details</H1
  86 ><P
  87 >Here are some details about the implementation
  88 which might be interesting, although they do not affect the ISO-defined
  89 semantics of the library. </P
  90 ><P
  91 ></P
  92 ><UL
  93 ><LI
  94 ><P
  95 >It is possible to configure
  96 <SPAN
  97 CLASS="emphasis"
  98 ><I
  99 CLASS="EMPHASIS"
 100 >eCos</I
 101 ></SPAN
 102 >
 103  to have the standard C library without the kernel. You might want
 104 to do this to use less memory. But if you disable the kernel, you
 105 will be unable to use memory allocation, thread-safety and certain
 106 stdio functions such as input. Other C library functionality is
 107 unaffected.</P
 108 ></LI
 109 ><LI
 110 ><P
 111 >The opaque type returned by
 112 <TT
 113 CLASS="FUNCTION"
 114 >clock()</TT
 115 >
 116  is called clock_t, and is implemented as a 64 bit integer.
 117 The value returned by
 118 <TT
 119 CLASS="FUNCTION"
 120 >clock()</TT
 121 >
 122  is only correct if the kernel is configured with real-time clock
 123 support, as determined by the CYGVAR_KERNEL_COUNTERS_CLOCK
 124 configuration option in
 125 <TT
 126 CLASS="FILENAME"
 127 >kernel.h</TT
 128 >
 129 .</P
 130 ></LI
 131 ><LI
 132 ><P
 133 >The FILE type is not implemented as a structure, but rather
 134 as a CYG_ADDRESS. </P
 135 ></LI
 136 ><LI
 137 ><P
 138 >The GNU C compiler will place its own <SPAN
 139 CLASS="emphasis"
 140 ><I
 141 CLASS="EMPHASIS"
 142 >built-in</I
 143 ></SPAN
 144 > implementations
 145 instead of some C library functions. This can be turned off with
 146 the <SPAN
 147 CLASS="emphasis"
 148 ><I
 149 CLASS="EMPHASIS"
 150 >-fno-builtin</I
 151 ></SPAN
 152 > option. The functions affected
 153 by this are
 154 <TT
 155 CLASS="FUNCTION"
 156 >abs()</TT
 157 >
 158 ,
 159 <TT
 160 CLASS="FUNCTION"
 161 >cos()</TT
 162 >
 163 ,
 164 <TT
 165 CLASS="FUNCTION"
 166 >fabs()</TT
 167 >
 168 ,
 169 <TT
 170 CLASS="FUNCTION"
 171 >labs()</TT
 172 >
 173 ,
 174 <TT
 175 CLASS="FUNCTION"
 176 >memcmp()</TT
 177 >
 178 ,
 179 <TT
 180 CLASS="FUNCTION"
 181 >memcpy()</TT
 182 >
 183 ,
 184 <TT
 185 CLASS="FUNCTION"
 186 >sin()</TT
 187 >
 188 ,
 189 <TT
 190 CLASS="FUNCTION"
 191 >sqrt()</TT
 192 >
 193 ,
 194 <TT
 195 CLASS="FUNCTION"
 196 >strcmp()</TT
 197 >
 198 ,
 199 <TT
 200 CLASS="FUNCTION"
 201 >strcpy()</TT
 202 >
 203 , and
 204 <TT
 205 CLASS="FUNCTION"
 206 >strlen()</TT
 207 >
 208 .</P
 209 ></LI
 210 ><LI
 211 ><P
 212 >For faster execution speed you should avoid this option
 213 and let the compiler use its built-ins. This can be turned off by
 214 invoking
 215 <SPAN
 216 CLASS="emphasis"
 217 ><I
 218 CLASS="EMPHASIS"
 219 >GCC</I
 220 ></SPAN
 221 >
 222  with the <SPAN
 223 CLASS="emphasis"
 224 ><I
 225 CLASS="EMPHASIS"
 226 >-fno-builtin</I
 227 ></SPAN
 228 > option. </P
 229 ></LI
 230 ><LI
 231 ><P
 232 ><TT
 233 CLASS="FUNCTION"
 234 >memcpy()</TT
 235 >
 236  and
 237 <TT
 238 CLASS="FUNCTION"
 239 >memset()</TT
 240 >
 241  are located in the infrastructure package, not in the C library
 242 package. This is because the compiler calls these functions, and
 243 the kernel needs to resolve them even if the C library is not configured. </P
 244 ></LI
 245 ><LI
 246 ><P
 247 >Error codes such as EDOM and ERANGE, as well as
 248 <TT
 249 CLASS="FUNCTION"
 250 >strerror()</TT
 251 >
 252 , are implemented in the <SPAN
 253 CLASS="emphasis"
 254 ><I
 255 CLASS="EMPHASIS"
 256 >error</I
 257 ></SPAN
 258 > package. The
 259 error package is separate from the rest of the C and math libraries
 260 so that the rest of
 261 <SPAN
 262 CLASS="emphasis"
 263 ><I
 264 CLASS="EMPHASIS"
 265 >eCos</I
 266 ></SPAN
 267 >
 268  can use these error handling facilities even if the C library is
 269 not configured. </P
 270 ></LI
 271 ><LI
 272 ><P
 273 >When
 274 <TT
 275 CLASS="FUNCTION"
 276 >free()</TT
 277 >
 278  is invoked, heap memory will normally be coalesced. If the CYGSEM_KERNEL_MEMORY_COALESCE
 279 configuration parameter is not set, memory will not be coalesced,
 280 which might cause programs to fail. </P
 281 ></LI
 282 ><LI
 283 ><P
 284 >Signals, as implemented by
 285 <TT
 286 CLASS="FILENAME"
 287 >&lt;signal.h&gt;</TT
 288 >, are guaranteed to work
 289 correctly if raised using the
 290 <TT
 291 CLASS="FUNCTION"
 292 >raise()</TT
 293 >
 294  function from a normal working program context. Using signals from
 295 within an ISR or DSR context is not expected to work. Also, it is
 296 not guaranteed that if CYGSEM_LIBC_SIGNALS_HWEXCEPTIONS
 297 is set, that handling a signal using
 298 <TT
 299 CLASS="FUNCTION"
 300 >signal()</TT
 301 >
 302  will necessarily catch that form of exception. For example, it
 303 may be expected that a divide-by-zero error would be caught by handling
 304 <TT
 305 CLASS="VARNAME"
 306 >SIGFPE</TT
 307 >. However it depends on the underlying HAL implementation to implement
 308 the required hardware exception. And indeed the hardware itself
 309 may not be capable of detecting these exceptions so it may not be
 310 possible for the HAL implementer to do this in any case. Despite
 311 this lack of guarantees in this respect, the signals implementation
 312 is still ISO C compliant since ISO C does not offer any such guarantees
 313 either. </P
 314 ></LI
 315 ><LI
 316 ><P
 317 >The
 318 <TT
 319 CLASS="FUNCTION"
 320 >getenv()</TT
 321 >
 322  function is implemented (unless the CYGPKG_LIBC_ENVIRONMENT configuration
 323 option is turned off), but there is no shell or
 324 <TT
 325 CLASS="FUNCTION"
 326 >putenv()</TT
 327 >
 328  function to set the environment dynamically. The environment is
 329 set in a global variable environ, declared as:</P
 330 ><TABLE
 331 BORDER="5"
 332 BGCOLOR="#E0E0F0"
 333 WIDTH="70%"
 334 ><TR
 335 ><TD
 336 ><PRE
 337 CLASS="PROGRAMLISTING"
 338 >extern char **environ; // Standard environment definition</PRE
 339 ></TD
 340 ></TR
 341 ></TABLE
 342 ><P
 343 >The environment can be statically initialized at startup time
 344 using the CYGDAT_LIBC_DEFAULT_ENVIRONMENT
 345 option. If so, remember that the final entry of the array initializer
 346 must be NULL. </P
 347 ></LI
 348 ></UL
 349 ><P
 350 >Here is a minimal <SPAN
 351 CLASS="emphasis"
 352 ><I
 353 CLASS="EMPHASIS"
 354 >eCos</I
 355 ></SPAN
 356 > program which
 357 demonstrates the use of environments (see also the test case in <TT
 358 CLASS="FILENAME"
 359 >language/c/libc/current/tests/stdlib/getenv.c</TT
 360 >): </P
 361 ><TABLE
 362 BORDER="5"
 363 BGCOLOR="#E0E0F0"
 364 WIDTH="70%"
 365 ><TR
 366 ><TD
 367 ><PRE
 368 CLASS="PROGRAMLISTING"
 369 >#include &lt;stdio.h&gt;
 370 #include &lt;stdlib.h&gt; // Main header for stdlib functions
 371
 372 extern char **environ; // Standard environment definition
 373
 374 int
 375 main( int argc, char *argv[] )
 376 {
 377  char *str;
 378  char *env[] = { "PATH=/usr/local/bin:/usr/bin",
 379  "HOME=/home/fred",
 380  "TEST=1234=5678",
 381  "home=hatstand",
 382  NULL };
 383
 384  printf("Display the current PATH environment variable\n");
 385
 386  environ = (char **)&amp;env;
 387
 388  str = getenv("PATH");
 389
 390  if (str==NULL) {
 391   printf("The current PATH is unset\n");
 392  } else {
 393   printf("The current PATH is \"%s\"\n", str);
 394  }
 395  return 0;
 396 } </PRE
 397 ></TD
 398 ></TR
 399 ></TABLE
 400 ></DIV
 401 ><DIV
 402 CLASS="NAVFOOTER"
 403 ><HR
 404 ALIGN="LEFT"
 405 WIDTH="100%"><TABLE
 406 SUMMARY="Footer navigation table"
 407 WIDTH="100%"
 408 BORDER="0"
 409 CELLPADDING="0"
 410 CELLSPACING="0"
 411 ><TR
 412 ><TD
 413 WIDTH="33%"
 414 ALIGN="left"
 415 VALIGN="top"
 416 ><A
 417 HREF="math-library-compatibility-modes.html"
 418 ACCESSKEY="P"
 419 >Prev</A
 420 ></TD
 421 ><TD
 422 WIDTH="34%"
 423 ALIGN="center"
 424 VALIGN="top"
 425 ><A
 426 HREF="ecos-ref.html"
 427 ACCESSKEY="H"
 428 >Home</A
 429 ></TD
 430 ><TD
 431 WIDTH="33%"
 432 ALIGN="right"
 433 VALIGN="top"
 434 ><A
 435 HREF="libc-thread-safety.html"
 436 ACCESSKEY="N"
 437 >Next</A
 438 ></TD
 439 ></TR
 440 ><TR
 441 ><TD
 442 WIDTH="33%"
 443 ALIGN="left"
 444 VALIGN="top"
 445 >Math library compatibility modes</TD
 446 ><TD
 447 WIDTH="34%"
 448 ALIGN="center"
 449 VALIGN="top"
 450 ><A
 451 HREF="c-and-math-library-overview.html"
 452 ACCESSKEY="U"
 453 >Up</A
 454 ></TD
 455 ><TD
 456 WIDTH="33%"
 457 ALIGN="right"
 458 VALIGN="top"
 459 >Thread safety</TD
 460 ></TR
 461 ></TABLE
 462 ></DIV
 463 ></BODY
 464 ></HTML
 465 >