doc/html/ref/c-and-math-library-overview.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 and math library overview</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="The ISO Standard C and Math Libraries"
  23 HREF="libc.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="The ISO Standard C and Math Libraries"
  26 HREF="libc.html"><LINK
  27 REL="NEXT"
  28 TITLE="Math library compatibility modes"
  29 HREF="math-library-compatibility-modes.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  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.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="math-library-compatibility-modes.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="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="C-AND-MATH-LIBRARY-OVERVIEW">Chapter 13. C and math library overview</H1
  85 ><DIV
  86 CLASS="TOC"
  87 ><DL
  88 ><DT
  89 ><B
  90 >Table of Contents</B
  91 ></DT
  92 ><DT
  93 ><A
  94 HREF="c-and-math-library-overview.html#INCLUDE-NON-ISO-FUNCTIONS"
  95 >Included non-ISO functions</A
  96 ></DT
  97 ><DT
  98 ><A
  99 HREF="math-library-compatibility-modes.html"
 100 >Math library compatibility modes</A
 101 ></DT
 102 ><DT
 103 ><A
 104 HREF="libc-implementation-details.html"
 105 >Some implementation details</A
 106 ></DT
 107 ><DT
 108 ><A
 109 HREF="libc-thread-safety.html"
 110 >Thread safety</A
 111 ></DT
 112 ><DT
 113 ><A
 114 HREF="c-library-startup.html"
 115 >C library startup</A
 116 ></DT
 117 ></DL
 118 ></DIV
 119 ><A
 120 NAME="ISO-C-AND-MATH-LIBRARIES"
 121 ></A
 122 ><P
 123 ><SPAN
 124 CLASS="emphasis"
 125 ><I
 126 CLASS="EMPHASIS"
 127 >eCos</I
 128 ></SPAN
 129 > provides compatibility with the
 130         ISO 9899:1990 specification for the standard C library, which
 131         is essentially the same as the better-known ANSI C3.159-1989
 132         specification (C-89).</P
 133 ><P
 134 >There are three aspects of this compatibility supplied by <SPAN
 135 CLASS="emphasis"
 136 ><I
 137 CLASS="EMPHASIS"
 138 >eCos</I
 139 ></SPAN
 140 >.
 141 First there is a <I
 142 CLASS="FIRSTTERM"
 143 >C library</I
 144 > which
 145 implements the functions defined by the ISO standard, except for the
 146 mathematical functions. This is provided by the eCos C library
 147 packages. </P
 148 ><P
 149 >Then <SPAN
 150 CLASS="emphasis"
 151 ><I
 152 CLASS="EMPHASIS"
 153 >eCos</I
 154 ></SPAN
 155 > provides a math
 156 library, which implements the mathematical functions from the ISO
 157 C library. This distinction between C and math libraries is frequently
 158 drawn &#8212; most standard C library implementations provide
 159 separate linkable files for the two, and the math library contains
 160 all the functions from the <TT
 161 CLASS="FILENAME"
 162 >math.h</TT
 163 > header
 164 file.</P
 165 ><P
 166 >There is a third element to the ISO C library, which is the
 167 environment in which applications run when they use the standard
 168 C library. This environment is set up by the C library startup procedure
 169 (<A
 170 HREF="c-library-startup.html"
 171 >the Section called <I
 172 >C library startup</I
 173 ></A
 174 >)
 175 and it provides (among other things) a <TT
 176 CLASS="FUNCTION"
 177 >main()</TT
 178 > entry
 179 point function, an <TT
 180 CLASS="FUNCTION"
 181 >exit()</TT
 182 > function that
 183 does the cleanup required by the standard (including handlers registered
 184 using the <TT
 185 CLASS="FUNCTION"
 186 >atexit()</TT
 187 > function), and an environment
 188 that can be read with <TT
 189 CLASS="FUNCTION"
 190 >getenv()</TT
 191 >. </P
 192 ><P
 193 >The description in this manual focuses on the <SPAN
 194 CLASS="emphasis"
 195 ><I
 196 CLASS="EMPHASIS"
 197 >eCos</I
 198 ></SPAN
 199 >-specific
 200 aspects of the C library (mostly related to <SPAN
 201 CLASS="emphasis"
 202 ><I
 203 CLASS="EMPHASIS"
 204 >eCos</I
 205 ></SPAN
 206 >'s
 207 configurability) as well as mentioning the omissions from the standard
 208 in this release. We do not attempt to define the semantics of each
 209 function, since that information can be found in the ISO, ANSI,
 210 POSIX and IEEE standards, and the many good books that have been
 211 written about the standard C library, that cover usage of these
 212 functions in a more general and useful way.</P
 213 ><DIV
 214 CLASS="SECT1"
 215 ><H1
 216 CLASS="SECT1"
 217 ><A
 218 NAME="INCLUDE-NON-ISO-FUNCTIONS">Included non-ISO functions</H1
 219 ><P
 220 >The following functions from the POSIX specification
 221 are included for convenience: </P
 222 ><P
 223 >       <TT
 224 CLASS="LITERAL"
 225 >extern char **</TT
 226 ><SPAN
 227 CLASS="emphasis"
 228 ><I
 229 CLASS="EMPHASIS"
 230 >environ</I
 231 ></SPAN
 232 > variable
 233 (for setting up the environment for use with <TT
 234 CLASS="FUNCTION"
 235 >getenv()</TT
 236 >)</P
 237 ><P
 238 >       <TT
 239 CLASS="FUNCTION"
 240 >_exit()</TT
 241 > </P
 242 ><P
 243 >       <TT
 244 CLASS="FUNCTION"
 245 >strtok_r()</TT
 246 > </P
 247 ><P
 248 >       <TT
 249 CLASS="FUNCTION"
 250 >rand_r()</TT
 251 > </P
 252 ><P
 253 >       <TT
 254 CLASS="FUNCTION"
 255 >asctime_r()</TT
 256 > </P
 257 ><P
 258 >       <TT
 259 CLASS="FUNCTION"
 260 >ctime_r()</TT
 261 > </P
 262 ><P
 263 >       <TT
 264 CLASS="FUNCTION"
 265 >localtime_r()</TT
 266 > </P
 267 ><P
 268 >       <TT
 269 CLASS="FUNCTION"
 270 >gmtime_r()</TT
 271 > </P
 272 ><P
 273 ><SPAN
 274 CLASS="emphasis"
 275 ><I
 276 CLASS="EMPHASIS"
 277 >eCos</I
 278 ></SPAN
 279 > provides the following additional
 280 implementation-specific functions within the standard C library
 281 to adjust the date and time settings:</P
 282 ><TABLE
 283 BORDER="5"
 284 BGCOLOR="#E0E0F0"
 285 WIDTH="70%"
 286 ><TR
 287 ><TD
 288 ><PRE
 289 CLASS="PROGRAMLISTING"
 290 >void <TT
 291 CLASS="FUNCTION"
 292 >cyg_libc_time_setdst</TT
 293 >(
 294   cyg_libc_time_dst state
 295 );</PRE
 296 ></TD
 297 ></TR
 298 ></TABLE
 299 ><P
 300 >This function sets the state of Daylight Savings Time. The
 301 values for state are:</P
 302 ><TABLE
 303 BORDER="5"
 304 BGCOLOR="#E0E0F0"
 305 WIDTH="70%"
 306 ><TR
 307 ><TD
 308 ><PRE
 309 CLASS="PROGRAMLISTING"
 310 >CYG_LIBC_TIME_DSTNA   unknown
 311 CYG_LIBC_TIME_DSTOFF  off
 312 CYG_LIBC_TIME_DSTON   on</PRE
 313 ></TD
 314 ></TR
 315 ></TABLE
 316 ><TABLE
 317 BORDER="5"
 318 BGCOLOR="#E0E0F0"
 319 WIDTH="70%"
 320 ><TR
 321 ><TD
 322 ><PRE
 323 CLASS="PROGRAMLISTING"
 324 >void <TT
 325 CLASS="FUNCTION"
 326 >cyg_libc_time_setzoneoffsets</TT
 327 >(
 328   time_t stdoffset, time_t dstoffset
 329 );</PRE
 330 ></TD
 331 ></TR
 332 ></TABLE
 333 ><P
 334 >This function sets the offsets from UTC used when Daylight
 335 Savings Time is enabled or disabled. The offsets are in time_t&#8217;s,
 336 which are seconds in the current inplementation.</P
 337 ><TABLE
 338 BORDER="5"
 339 BGCOLOR="#E0E0F0"
 340 WIDTH="70%"
 341 ><TR
 342 ><TD
 343 ><PRE
 344 CLASS="PROGRAMLISTING"
 345 ><TT
 346 CLASS="FUNCTION"
 347 >Cyg_libc_time_dst cyg_libc_time_getzoneoffsets</TT
 348 >(
 349   time_t *stdoffset, time_t *dstoffset
 350 );</PRE
 351 ></TD
 352 ></TR
 353 ></TABLE
 354 ><P
 355 >This function retrieves the current setting for Daylight Savings
 356 Time along with the offsets used for both STD and DST. The offsets
 357 are both in time_t&#8217;s, which are seconds in the
 358 current implementation.</P
 359 ><TABLE
 360 BORDER="5"
 361 BGCOLOR="#E0E0F0"
 362 WIDTH="70%"
 363 ><TR
 364 ><TD
 365 ><PRE
 366 CLASS="PROGRAMLISTING"
 367 ><TT
 368 CLASS="FUNCTION"
 369 >cyg_bool cyg_libc_time_settime</TT
 370 >(
 371   time_t utctime
 372 );</PRE
 373 ></TD
 374 ></TR
 375 ></TABLE
 376 ><P
 377 >This function sets the current time for the system The time
 378 is specified as a <SPAN
 379 CLASS="TYPE"
 380 >time_t</SPAN
 381 > in UTC.
 382 It returns non-zero on error.</P
 383 ></DIV
 384 ></DIV
 385 ><DIV
 386 CLASS="NAVFOOTER"
 387 ><HR
 388 ALIGN="LEFT"
 389 WIDTH="100%"><TABLE
 390 SUMMARY="Footer navigation table"
 391 WIDTH="100%"
 392 BORDER="0"
 393 CELLPADDING="0"
 394 CELLSPACING="0"
 395 ><TR
 396 ><TD
 397 WIDTH="33%"
 398 ALIGN="left"
 399 VALIGN="top"
 400 ><A
 401 HREF="libc.html"
 402 ACCESSKEY="P"
 403 >Prev</A
 404 ></TD
 405 ><TD
 406 WIDTH="34%"
 407 ALIGN="center"
 408 VALIGN="top"
 409 ><A
 410 HREF="ecos-ref.html"
 411 ACCESSKEY="H"
 412 >Home</A
 413 ></TD
 414 ><TD
 415 WIDTH="33%"
 416 ALIGN="right"
 417 VALIGN="top"
 418 ><A
 419 HREF="math-library-compatibility-modes.html"
 420 ACCESSKEY="N"
 421 >Next</A
 422 ></TD
 423 ></TR
 424 ><TR
 425 ><TD
 426 WIDTH="33%"
 427 ALIGN="left"
 428 VALIGN="top"
 429 >The ISO Standard C and Math Libraries</TD
 430 ><TD
 431 WIDTH="34%"
 432 ALIGN="center"
 433 VALIGN="top"
 434 ><A
 435 HREF="libc.html"
 436 ACCESSKEY="U"
 437 >Up</A
 438 ></TD
 439 ><TD
 440 WIDTH="33%"
 441 ALIGN="right"
 442 VALIGN="top"
 443 >Math library compatibility modes</TD
 444 ></TR
 445 ></TABLE
 446 ></DIV
 447 ></BODY
 448 ></HTML
 449 >