AVR Libc Home Page AVR Libc Development Pages Main Page User Manual Library Reference FAQ Alphabetical Index Example Projects

# stdlib.h

Go to the documentation of this file.
00001 /* Copyright (c) 2002, Marek Michalkiewicz
00002    Copyright (c) 2004,2007 Joerg Wunsch
00003
00004    Portions of documentation Copyright (c) 1990, 1991, 1993, 1994
00005    The Regents of the University of California.
00006
00008
00009    Redistribution and use in source and binary forms, with or without
00010    modification, are permitted provided that the following conditions are met:
00011
00012    * Redistributions of source code must retain the above copyright
00013      notice, this list of conditions and the following disclaimer.
00014
00015    * Redistributions in binary form must reproduce the above copyright
00016      notice, this list of conditions and the following disclaimer in
00017      the documentation and/or other materials provided with the
00018      distribution.
00019
00020    * Neither the name of the copyright holders nor the names of
00021      contributors may be used to endorse or promote products derived
00022      from this software without specific prior written permission.
00023
00024   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00025   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00026   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00027   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00028   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00029   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00030   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00031   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00032   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00033   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00034   POSSIBILITY OF SUCH DAMAGE.
00035
00036   $Id: stdlib.h 1623 2008-03-16 13:44:45Z dmix$
00037 */
00038
00039 #ifndef _STDLIB_H_
00040 #define _STDLIB_H_ 1
00041
00042 #ifndef __ASSEMBLER__
00043
00044 #define __need_NULL
00045 #define __need_size_t
00046 #define __need_wchar_t
00047 #include <stddef.h>
00048
00049 #ifndef __ptr_t
00050 #define __ptr_t void *
00051 #endif
00052
00053 #ifdef __cplusplus
00054 extern "C" {
00055 #endif
00056
00057 /** \file */
00058
00059 /** \defgroup avr_stdlib <stdlib.h>: General utilities
00060     \code #include <stdlib.h> \endcode
00061
00062     This file declares some basic C macros and functions as
00063     defined by the ISO standard, plus some AVR-specific extensions.
00064 */
00065
00066 /*@{*/
00067 /** Result type for function div(). */
00068 typedef struct {
00069         int quot;                   /**< The Quotient. */
00070         int rem;                    /**< The Remainder. */
00071 } div_t;
00072
00073 /** Result type for function ldiv(). */
00074 typedef struct {
00075         long quot;                  /**< The Quotient. */
00076         long rem;                   /**< The Remainder. */
00077 } ldiv_t;
00078
00079 /** Comparision function type for qsort(), just for convenience. */
00080 typedef int (*__compar_fn_t)(const void *, const void *);
00081
00082 #ifndef __DOXYGEN__
00083
00084 #ifndef __ATTR_CONST__
00085 #define __ATTR_CONST__ __attribute__((__const__))
00086 #endif
00087
00088 #ifndef __ATTR_MALLOC__
00089 #define __ATTR_MALLOC__ __attribute__((__malloc__))
00090 #endif
00091
00092 #ifndef __ATTR_NORETURN__
00093 #define __ATTR_NORETURN__ __attribute__((__noreturn__))
00094 #endif
00095
00096 #ifndef __ATTR_PURE__
00097 #define __ATTR_PURE__ __attribute__((__pure__))
00098 #endif
00099
00100 #endif
00101
00102 /** The abort() function causes abnormal program termination to occur.
00103     This realization disables interrupts and jumps to _exit() function
00104     with argument equal to 1. In the limited AVR environment, execution is
00105     effectively halted by entering an infinite loop. */
00106 extern void abort(void) __ATTR_NORETURN__;
00107
00108 /** The abs() function computes the absolute value of the integer \c i.
00109    \note The abs() and labs() functions are builtins of gcc.
00110 */
00111 extern int abs(int __i) __ATTR_CONST__;
00112 #ifndef __DOXYGEN__
00113 #define abs(__i) __builtin_abs(__i)
00114 #endif
00115
00116 /** The labs() function computes the absolute value of the long integer
00117     \c i.
00118    \note The abs() and labs() functions are builtins of gcc.
00119 */
00120 extern long labs(long __i) __ATTR_CONST__;
00121 #ifndef __DOXYGEN__
00122 #define labs(__i) __builtin_labs(__i)
00123 #endif
00124
00125 /**
00126      The bsearch() function searches an array of \c nmemb objects, the
00127      initial member of which is pointed to by \c base, for a member
00128      that matches the object pointed to by \c key.  The size of each
00129      member of the array is specified by \c size.
00130
00131      The contents of the array should be in ascending sorted order
00132      according to the comparison function referenced by \c compar.
00133      The \c compar routine is expected to have two arguments which
00134      point to the key object and to an array member, in that order,
00135      and should return an integer less than, equal to, or greater than
00136      zero if the key object is found, respectively, to be less than,
00137      to match, or be greater than the array member.
00138
00139      The bsearch() function returns a pointer to a matching member of
00140      the array, or a null pointer if no match is found.  If two
00141      members compare as equal, which member is matched is unspecified.
00142 */
00143 extern void *bsearch(const void *__key, const void *__base, size_t __nmemb,
00144                      size_t __size, int (*__compar)(const void *, const void *));
00145
00146 /* __divmodhi4 and __divmodsi4 from libgcc.a */
00147 /**
00148      The div() function computes the value \c num/denom and returns
00149      the quotient and remainder in a structure named \c div_t that
00150      contains two int members named \c quot and \c rem.
00151 */
00152 extern div_t div(int __num, int __denom) __asm__("__divmodhi4") __ATTR_CONST__;
00153 /**
00154      The ldiv() function computes the value \c num/denom and returns
00155      the quotient and remainder in a structure named \c ldiv_t that
00156      contains two long integer members named \c quot and \c rem.
00157 */
00158 extern ldiv_t ldiv(long __num, long __denom) __asm__("__divmodsi4") __ATTR_CONST__;
00159
00160 /**
00161      The qsort() function is a modified partition-exchange sort, or
00162      quicksort.
00163
00164      The qsort() function sorts an array of \c nmemb objects, the
00165      initial member of which is pointed to by \c base.  The size of
00166      each object is specified by \c size.  The contents of the array
00167      base are sorted in ascending order according to a comparison
00168      function pointed to by \c compar, which requires two arguments
00169      pointing to the objects being compared.
00170
00171      The comparison function must return an integer less than, equal
00172      to, or greater than zero if the first argument is considered to
00173      be respectively less than, equal to, or greater than the second.
00174 */
00175 extern void qsort(void *__base, size_t __nmemb, size_t __size,
00176                   __compar_fn_t __compar);
00177
00178 /**
00179     The strtol() function converts the string in \c nptr to a long
00180     value.  The conversion is done according to the given base, which
00181     must be between 2 and 36 inclusive, or be the special value 0.
00182
00183     The string may begin with an arbitrary amount of white space (as
00184     determined by isspace()) followed by a single optional \c '+' or \c '-'
00185     sign.  If \c base is zero or 16, the string may then include a
00186     \c "0x" prefix, and the number will be read in base 16; otherwise,
00187     a zero base is taken as 10 (decimal) unless the next character is
00188     \c '0', in which case it is taken as 8 (octal).
00189
00190     The remainder of the string is converted to a long value in the
00191     obvious manner, stopping at the first character which is not a
00192     valid digit in the given base.  (In bases above 10, the letter \c 'A'
00193     in either upper or lower case represents 10, \c 'B' represents 11,
00194     and so forth, with \c 'Z' representing 35.)
00195
00196     If \c endptr is not NULL, strtol() stores the address of the first
00197     invalid character in \c *endptr.  If there were no digits at all,
00198     however, strtol() stores the original value of \c nptr in \c
00199     *endptr.  (Thus, if \c *nptr is not \c '\\0' but \c **endptr is \c '\\0'
00200     on return, the entire string was valid.)
00201
00202     The strtol() function returns the result of the conversion, unless
00203     the value would underflow or overflow.  If no conversion could be
00204     performed, 0 is returned.  If an overflow or underflow occurs, \c
00205     errno is set to \ref avr_errno "ERANGE" and the function return value
00206     is clamped to \c LONG_MIN or \c LONG_MAX, respectively.
00207 */
00208 extern long strtol(const char *__nptr, char **__endptr, int __base);
00209
00210 /**
00211     The strtoul() function converts the string in \c nptr to an
00212     unsigned long value.  The conversion is done according to the
00213     given base, which must be between 2 and 36 inclusive, or be the
00214     special value 0.
00215
00216     The string may begin with an arbitrary amount of white space (as
00217     determined by isspace()) followed by a single optional \c '+' or \c '-'
00218     sign.  If \c base is zero or 16, the string may then include a
00219     \c "0x" prefix, and the number will be read in base 16; otherwise,
00220     a zero base is taken as 10 (decimal) unless the next character is
00221     \c '0', in which case it is taken as 8 (octal).
00222
00223     The remainder of the string is converted to an unsigned long value
00224     in the obvious manner, stopping at the first character which is
00225     not a valid digit in the given base.  (In bases above 10, the
00226     letter \c 'A' in either upper or lower case represents 10, \c 'B'
00227     represents 11, and so forth, with \c 'Z' representing 35.)
00228
00229     If \c endptr is not NULL, strtoul() stores the address of the first
00230     invalid character in \c *endptr.  If there were no digits at all,
00231     however, strtoul() stores the original value of \c nptr in \c
00232     *endptr.  (Thus, if \c *nptr is not \c '\\0' but \c **endptr is \c '\\0'
00233     on return, the entire string was valid.)
00234
00235     The strtoul() function return either the result of the conversion
00236     or, if there was a leading minus sign, the negation of the result
00237     of the conversion, unless the original (non-negated) value would
00238     overflow; in the latter case, strtoul() returns ULONG_MAX, and \c
00239     errno is set to \ref avr_errno "ERANGE".  If no conversion could
00240     be performed, 0 is returned.
00241 */
00242 extern unsigned long strtoul(const char *__nptr, char **__endptr, int __base);
00243
00244 /**
00245     The atol() function converts the initial portion of the string
00246     pointed to by \p s to long integer representation. In contrast to
00247
00248         \code strtol(s, (char **)NULL, 10); \endcode
00249
00250     this function does not detect overflow (\c errno is not changed and
00251     the result value is not predictable), uses smaller memory (flash and
00252     stack) and works more quickly.
00253 */
00254 extern long atol(const char *__s) __ATTR_PURE__;
00255
00256 /**
00257     The atoi() function converts the initial portion of the string
00258     pointed to by \p s to integer representation. In contrast to
00259
00260         \code (int)strtol(s, (char **)NULL, 10); \endcode
00261
00262     this function does not detect overflow (\c errno is not changed and
00263     the result value is not predictable), uses smaller memory (flash and
00264     stack) and works more quickly.
00265 */
00266 extern int atoi(const char *__s) __ATTR_PURE__;
00267
00268 /**
00269    The exit() function terminates the application.  Since there is no
00270    environment to return to, \c status is ignored, and code execution
00271    will eventually reach an infinite loop, thereby effectively halting
00272    all code processing.  Before entering the infinite loop, interrupts
00273    are globally disabled.
00274
00275    In a C++ context, global destructors will be called before halting
00276    execution.
00277 */
00278 extern void exit(int __status) __ATTR_NORETURN__;
00279
00280 /**
00281    The malloc() function allocates \c size bytes of memory.
00282    If malloc() fails, a NULL pointer is returned.
00283
00284    Note that malloc() does \e not initialize the returned memory to
00285    zero bytes.
00286
00287    See the chapter about \ref malloc "malloc() usage" for implementation
00288    details.
00289 */
00290 extern void *malloc(size_t __size) __ATTR_MALLOC__;
00291
00292 /**
00293    The free() function causes the allocated memory referenced by \c
00294    ptr to be made available for future allocations.  If \c ptr is
00295    NULL, no action occurs.
00296 */
00297 extern void free(void *__ptr);
00298
00299 /**
00300    \c malloc() \ref malloc_tunables "tunable".
00301 */
00302 extern size_t __malloc_margin;
00303
00304 /**
00305    \c malloc() \ref malloc_tunables "tunable".
00306 */
00307 extern char *__malloc_heap_start;
00308
00309 /**
00310    \c malloc() \ref malloc_tunables "tunable".
00311 */
00312 extern char *__malloc_heap_end;
00313
00314 /**
00315    Allocate \c nele elements of \c size each.  Identical to calling
00316    \c malloc() using <tt>nele * size</tt> as argument, except the
00317    allocated memory will be cleared to zero.
00318 */
00319 extern void *calloc(size_t __nele, size_t __size) __ATTR_MALLOC__;
00320
00321 /**
00322    The realloc() function tries to change the size of the region
00323    allocated at \c ptr to the new \c size value.  It returns a
00324    pointer to the new region.  The returned pointer might be the
00325    same as the old pointer, or a pointer to a completely different
00326    region.
00327
00328    The contents of the returned region up to either the old or the new
00329    size value (whatever is less) will be identical to the contents of
00330    the old region, even in case a new region had to be allocated.
00331
00332    It is acceptable to pass \c ptr as NULL, in which case realloc()
00333    will behave identical to malloc().
00334
00335    If the new memory cannot be allocated, realloc() returns NULL, and
00336    the region at \c ptr will not be changed.
00337 */
00338 extern void *realloc(void *__ptr, size_t __size) __ATTR_MALLOC__;
00339
00340 extern double strtod(const char *__nptr, char **__endptr);
00341
00342 extern double atof(const char *__nptr);
00343
00344 /** Highest number that can be generated by rand(). */
00345 #define RAND_MAX 0x7FFF
00346
00347 /**
00348      The rand() function computes a sequence of pseudo-random integers in the
00349      range of 0 to \c RAND_MAX (as defined by the header file <stdlib.h>).
00350
00351      The srand() function sets its argument \c seed as the seed for a new
00352      sequence of pseudo-random numbers to be returned by rand().  These
00353      sequences are repeatable by calling srand() with the same seed value.
00354
00355      If no seed value is provided, the functions are automatically seeded with
00356      a value of 1.
00357
00358      In compliance with the C standard, these functions operate on
00359      \c int arguments.  Since the underlying algorithm already uses
00360      32-bit calculations, this causes a loss of precision.  See
00361      \c random() for an alternate set of functions that retains full
00362      32-bit precision.
00363 */
00364 extern int rand(void);
00365 /**
00366    Pseudo-random number generator seeding; see rand().
00367 */
00368 extern void srand(unsigned int __seed);
00369
00370 /**
00371    Variant of rand() that stores the context in the user-supplied
00372    variable located at \c ctx instead of a static library variable
00373    so the function becomes re-entrant.
00374 */
00375 extern int rand_r(unsigned long *__ctx);
00376 /*@}*/
00377
00378 /*@{*/
00379 /** \name Non-standard (i.e. non-ISO C) functions.
00380  \ingroup avr_stdlib
00381 */
00382 /**
00383    \brief Convert an integer to a string.
00384
00385    The function itoa() converts the integer value from \c val into an
00386    ASCII representation that will be stored under \c s.  The caller
00387    is responsible for providing sufficient storage in \c s.
00388
00389    \note The minimal size of the buffer \c s depends on the choice of
00390    radix. For example, if the radix is 2 (binary), you need to supply a buffer
00391    with a minimal length of 8 * sizeof (int) + 1 characters, i.e. one
00392    character for each bit plus one for the string terminator. Using a larger
00393    radix will require a smaller minimal buffer size.
00394
00395    \warning If the buffer is too small, you risk a buffer overflow.
00396
00397    Conversion is done using the \c radix as base, which may be a
00398    number between 2 (binary conversion) and up to 36.  If \c radix
00399    is greater than 10, the next digit after \c '9' will be the letter
00400    \c 'a'.
00401
00402     If radix is 10 and val is negative, a minus sign will be prepended.
00403
00404    The itoa() function returns the pointer passed as \c s.
00405 */
00406 extern char *itoa(int __val, char *__s, int __radix);
00407
00408 /**
00409  \ingroup avr_stdlib
00410
00411    \brief Convert a long integer to a string.
00412
00413    The function ltoa() converts the long integer value from \c val into an
00414    ASCII representation that will be stored under \c s.  The caller
00415    is responsible for providing sufficient storage in \c s.
00416
00417    \note The minimal size of the buffer \c s depends on the choice of
00418    radix. For example, if the radix is 2 (binary), you need to supply a buffer
00419    with a minimal length of 8 * sizeof (long int) + 1 characters, i.e. one
00420    character for each bit plus one for the string terminator. Using a larger
00421    radix will require a smaller minimal buffer size.
00422
00423    \warning If the buffer is too small, you risk a buffer overflow.
00424
00425    Conversion is done using the \c radix as base, which may be a
00426    number between 2 (binary conversion) and up to 36.  If \c radix
00427    is greater than 10, the next digit after \c '9' will be the letter
00428    \c 'a'.
00429
00430    If radix is 10 and val is negative, a minus sign will be prepended.
00431
00432    The ltoa() function returns the pointer passed as \c s.
00433 */
00434 extern char *ltoa(long int __val, char *__s, int __radix);
00435
00436 /**
00437  \ingroup avr_stdlib
00438
00439    \brief Convert an unsigned integer to a string.
00440
00441    The function utoa() converts the unsigned integer value from \c val into an
00442    ASCII representation that will be stored under \c s.  The caller
00443    is responsible for providing sufficient storage in \c s.
00444
00445    \note The minimal size of the buffer \c s depends on the choice of
00446    radix. For example, if the radix is 2 (binary), you need to supply a buffer
00447    with a minimal length of 8 * sizeof (unsigned int) + 1 characters, i.e. one
00448    character for each bit plus one for the string terminator. Using a larger
00449    radix will require a smaller minimal buffer size.
00450
00451    \warning If the buffer is too small, you risk a buffer overflow.
00452
00453    Conversion is done using the \c radix as base, which may be a
00454    number between 2 (binary conversion) and up to 36.  If \c radix
00455    is greater than 10, the next digit after \c '9' will be the letter
00456    \c 'a'.
00457
00458    The utoa() function returns the pointer passed as \c s.
00459 */
00460 extern char *utoa(unsigned int __val, char *__s, int __radix);
00461
00462 /**
00463  \ingroup avr_stdlib
00464    \brief Convert an unsigned long integer to a string.
00465
00466    The function ultoa() converts the unsigned long integer value from
00467    \c val into an
00468    ASCII representation that will be stored under \c s.  The caller
00469    is responsible for providing sufficient storage in \c s.
00470
00471    \note The minimal size of the buffer \c s depends on the choice of
00472    radix. For example, if the radix is 2 (binary), you need to supply a buffer
00473    with a minimal length of 8 * sizeof (unsigned long int) + 1 characters,
00474    i.e. one character for each bit plus one for the string terminator. Using a
00475    larger radix will require a smaller minimal buffer size.
00476
00477    \warning If the buffer is too small, you risk a buffer overflow.
00478
00479    Conversion is done using the \c radix as base, which may be a
00480    number between 2 (binary conversion) and up to 36.  If \c radix
00481    is greater than 10, the next digit after \c '9' will be the letter
00482    \c 'a'.
00483
00484    The ultoa() function returns the pointer passed as \c s.
00485 */
00486 extern char *ultoa(unsigned long int __val, char *__s, int __radix);
00487
00488 /**  \ingroup avr_stdlib
00489 Highest number that can be generated by random(). */
00490 #define RANDOM_MAX 0x7FFFFFFF
00491
00492 /**
00493  \ingroup avr_stdlib
00494      The random() function computes a sequence of pseudo-random integers in the
00495      range of 0 to \c RANDOM_MAX (as defined by the header file <stdlib.h>).
00496
00497      The srandom() function sets its argument \c seed as the seed for a new
00498      sequence of pseudo-random numbers to be returned by rand().  These
00499      sequences are repeatable by calling srandom() with the same seed value.
00500
00501      If no seed value is provided, the functions are automatically seeded with
00502      a value of 1.
00503 */
00504 extern long random(void);
00505 /**
00506  \ingroup avr_stdlib
00507    Pseudo-random number generator seeding; see random().
00508 */
00509 extern void srandom(unsigned long __seed);
00510
00511 /**
00512  \ingroup avr_stdlib
00513    Variant of random() that stores the context in the user-supplied
00514    variable located at \c ctx instead of a static library variable
00515    so the function becomes re-entrant.
00516 */
00517 extern long random_r(unsigned long *__ctx);
00518 #endif /* __ASSEMBLER */
00519 /*@}*/
00520
00521 /*@{*/
00522 /** \name Conversion functions for double arguments.
00523  \ingroup avr_stdlib
00524  Note that these functions are not located in the default library,
00525  <tt>libc.a</tt>, but in the mathematical library, <tt>libm.a</tt>.
00526  So when linking the application, the \c -lm option needs to be
00527  specified.
00528 */
00529 /** \ingroup avr_stdlib
00530     Bit value that can be passed in \c flags to dtostre(). */
00531 #define DTOSTR_ALWAYS_SIGN 0x01        /* put '+' or ' ' for positives */
00532 /** \ingroup avr_stdlib
00533     Bit value that can be passed in \c flags to dtostre(). */
00534 #define DTOSTR_PLUS_SIGN   0x02        /* put '+' rather than ' ' */
00535 /** \ingroup avr_stdlib
00536     Bit value that can be passed in \c flags to dtostre(). */
00537 #define DTOSTR_UPPERCASE   0x04        /* put 'E' rather 'e' */
00538
00539 #ifndef __ASSEMBLER__
00540
00541 /**
00542    \ingroup avr_stdlib
00543    The dtostre() function converts the double value passed in \c val into
00544    an ASCII representation that will be stored under \c s.  The caller
00545    is responsible for providing sufficient storage in \c s.
00546
00547    Conversion is done in the format \c "[-]d.ddde±dd" where there is
00548    one digit before the decimal-point character and the number of
00549    digits after it is equal to the precision \c prec; if the precision
00550    is zero, no decimal-point character appears.  If \c flags has the
00551    DTOSTRE_UPPERCASE bit set, the letter \c 'E' (rather than \c 'e' ) will be
00552    used to introduce the exponent.  The exponent always contains two
00553    digits; if the value is zero, the exponent is \c "00".
00554
00555    If \c flags has the DTOSTRE_ALWAYS_SIGN bit set, a space character
00556    will be placed into the leading position for positive numbers.
00557
00558    If \c flags has the DTOSTRE_PLUS_SIGN bit set, a plus sign will be
00559    used instead of a space character in this case.
00560
00561    The dtostre() function returns the pointer to the converted string \c s.
00562 */
00563 extern char *dtostre(double __val, char *__s, unsigned char __prec,
00564                      unsigned char __flags);
00565
00566 /**
00567    \ingroup avr_stdlib
00568    The dtostrf() function converts the double value passed in \c val into
00569    an ASCII representationthat will be stored under \c s.  The caller
00570    is responsible for providing sufficient storage in \c s.
00571
00572    Conversion is done in the format \c "[-]d.ddd".  The minimum field
00573    width of the output string (including the \c '.' and the possible
00574    sign for negative values) is given in \c width, and \c prec determines
00575    the number of digits after the decimal sign. \c width is signed value,
00577
00578    The dtostrf() function returns the pointer to the converted string \c s.
00579 */
00580 extern char *dtostrf(double __val, signed char __width,
00581                      unsigned char __prec, char *__s);
00582
00583 /*@}*/
00584
00585 #if 0  /* not yet implemented */
00586 extern int atexit(void (*)(void));
00587 #endif
00588
00589 #ifdef __cplusplus
00590 }
00591 #endif
00592
00593 #endif /* __ASSEMBLER */
00594
00595 #endif /* _STDLIB_H_ */

Automatically generated by Doxygen 1.7.3 on Thu May 19 2011.