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.
1 /* Copyright (c) 2002, Marek Michalkiewicz
2 Copyright (c) 2004,2007 Joerg Wunsch
3
4 Portions of documentation Copyright (c) 1990, 1991, 1993, 1994
5 The Regents of the University of California.
6
7 All rights reserved.
8
9 Redistribution and use in source and binary forms, with or without
10 modification, are permitted provided that the following conditions are met:
11
12 * Redistributions of source code must retain the above copyright
13 notice, this list of conditions and the following disclaimer.
14
15 * Redistributions in binary form must reproduce the above copyright
16 notice, this list of conditions and the following disclaimer in
17 the documentation and/or other materials provided with the
18 distribution.
19
20 * Neither the name of the copyright holders nor the names of
21 contributors may be used to endorse or promote products derived
22 from this software without specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 POSSIBILITY OF SUCH DAMAGE.
35
36 $Id: stdlib.h 1623 2008-03-16 13:44:45Z dmix $
37 */
38
39 #ifndef _STDLIB_H_
40 #define _STDLIB_H_ 1
41
42 #ifndef __ASSEMBLER__
43
44 #define __need_NULL
45 #define __need_size_t
46 #define __need_wchar_t
47 #include <stddef.h>
48
49 #ifndef __ptr_t
50 #define __ptr_t void *
51 #endif
52
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56
57 /** \file */
58
59 /** \defgroup avr_stdlib <stdlib.h>: General utilities
60 \code #include <stdlib.h> \endcode
61
62 This file declares some basic C macros and functions as
63 defined by the ISO standard, plus some AVR-specific extensions.
64 */
65
66 /*@{*/
67 /** Result type for function div(). */
68 typedef struct {
69 int quot; /**< The Quotient. */
70 int rem; /**< The Remainder. */
71 } div_t;
72
73 /** Result type for function ldiv(). */
74 typedef struct {
75 long quot; /**< The Quotient. */
76 long rem; /**< The Remainder. */
77 } ldiv_t;
78
79 /** Comparision function type for qsort(), just for convenience. */
80 typedef int (*__compar_fn_t)(const void *, const void *);
81
82 #ifndef __DOXYGEN__
83
84 #ifndef __ATTR_CONST__
85 #define __ATTR_CONST__ __attribute__((__const__))
86 #endif
87
88 #ifndef __ATTR_MALLOC__
89 #define __ATTR_MALLOC__ __attribute__((__malloc__))
90 #endif
91
92 #ifndef __ATTR_NORETURN__
93 #define __ATTR_NORETURN__ __attribute__((__noreturn__))
94 #endif
95
96 #ifndef __ATTR_PURE__
97 #define __ATTR_PURE__ __attribute__((__pure__))
98 #endif
99
100 #endif
101
102 /** The abort() function causes abnormal program termination to occur.
103 This realization disables interrupts and jumps to _exit() function
104 with argument equal to 1. In the limited AVR environment, execution is
105 effectively halted by entering an infinite loop. */
106 extern void abort(void) __ATTR_NORETURN__;
107
108 /** The abs() function computes the absolute value of the integer \c i.
109 \note The abs() and labs() functions are builtins of gcc.
110 */
111 extern int abs(int __i) __ATTR_CONST__;
112 #ifndef __DOXYGEN__
113 #define abs(__i) __builtin_abs(__i)
114 #endif
115
116 /** The labs() function computes the absolute value of the long integer
117 \c i.
118 \note The abs() and labs() functions are builtins of gcc.
119 */
120 extern long labs(long __i) __ATTR_CONST__;
121 #ifndef __DOXYGEN__
122 #define labs(__i) __builtin_labs(__i)
123 #endif
124
125 /**
126 The bsearch() function searches an array of \c nmemb objects, the
127 initial member of which is pointed to by \c base, for a member
128 that matches the object pointed to by \c key. The size of each
129 member of the array is specified by \c size.
130
131 The contents of the array should be in ascending sorted order
132 according to the comparison function referenced by \c compar.
133 The \c compar routine is expected to have two arguments which
134 point to the key object and to an array member, in that order,
135 and should return an integer less than, equal to, or greater than
136 zero if the key object is found, respectively, to be less than,
137 to match, or be greater than the array member.
138
139 The bsearch() function returns a pointer to a matching member of
140 the array, or a null pointer if no match is found. If two
141 members compare as equal, which member is matched is unspecified.
142 */
143 extern void *bsearch(const void *__key, const void *__base, size_t __nmemb,
144 size_t __size, int (*__compar)(const void *, const void *));
145
146 /* __divmodhi4 and __divmodsi4 from libgcc.a */
147 /**
148 The div() function computes the value \c num/denom and returns
149 the quotient and remainder in a structure named \c div_t that
150 contains two int members named \c quot and \c rem.
151 */
152 extern div_t div(int __num, int __denom) __asm__("__divmodhi4") __ATTR_CONST__;
153 /**
154 The ldiv() function computes the value \c num/denom and returns
155 the quotient and remainder in a structure named \c ldiv_t that
156 contains two long integer members named \c quot and \c rem.
157 */
158 extern ldiv_t ldiv(long __num, long __denom) __asm__("__divmodsi4") __ATTR_CONST__;
159
160 /**
161 The qsort() function is a modified partition-exchange sort, or
162 quicksort.
163
164 The qsort() function sorts an array of \c nmemb objects, the
165 initial member of which is pointed to by \c base. The size of
166 each object is specified by \c size. The contents of the array
167 base are sorted in ascending order according to a comparison
168 function pointed to by \c compar, which requires two arguments
169 pointing to the objects being compared.
170
171 The comparison function must return an integer less than, equal
172 to, or greater than zero if the first argument is considered to
173 be respectively less than, equal to, or greater than the second.
174 */
175 extern void qsort(void *__base, size_t __nmemb, size_t __size,
176 __compar_fn_t __compar);
177
178 /**
179 The strtol() function converts the string in \c nptr to a long
180 value. The conversion is done according to the given base, which
181 must be between 2 and 36 inclusive, or be the special value 0.
182
183 The string may begin with an arbitrary amount of white space (as
184 determined by isspace()) followed by a single optional \c '+' or \c '-'
185 sign. If \c base is zero or 16, the string may then include a
186 \c "0x" prefix, and the number will be read in base 16; otherwise,
187 a zero base is taken as 10 (decimal) unless the next character is
188 \c '0', in which case it is taken as 8 (octal).
189
190 The remainder of the string is converted to a long value in the
191 obvious manner, stopping at the first character which is not a
192 valid digit in the given base. (In bases above 10, the letter \c 'A'
193 in either upper or lower case represents 10, \c 'B' represents 11,
194 and so forth, with \c 'Z' representing 35.)
195
196 If \c endptr is not NULL, strtol() stores the address of the first
197 invalid character in \c *endptr. If there were no digits at all,
198 however, strtol() stores the original value of \c nptr in \c
199 *endptr. (Thus, if \c *nptr is not \c '\\0' but \c **endptr is \c '\\0'
200 on return, the entire string was valid.)
201
202 The strtol() function returns the result of the conversion, unless
203 the value would underflow or overflow. If no conversion could be
204 performed, 0 is returned. If an overflow or underflow occurs, \c
205 errno is set to \ref avr_errno "ERANGE" and the function return value
206 is clamped to \c LONG_MIN or \c LONG_MAX, respectively.
207 */
208 extern long strtol(const char *__nptr, char **__endptr, int __base);
209
210 /**
211 The strtoul() function converts the string in \c nptr to an
212 unsigned long value. The conversion is done according to the
213 given base, which must be between 2 and 36 inclusive, or be the
214 special value 0.
215
216 The string may begin with an arbitrary amount of white space (as
217 determined by isspace()) followed by a single optional \c '+' or \c '-'
218 sign. If \c base is zero or 16, the string may then include a
219 \c "0x" prefix, and the number will be read in base 16; otherwise,
220 a zero base is taken as 10 (decimal) unless the next character is
221 \c '0', in which case it is taken as 8 (octal).
222
223 The remainder of the string is converted to an unsigned long value
224 in the obvious manner, stopping at the first character which is
225 not a valid digit in the given base. (In bases above 10, the
226 letter \c 'A' in either upper or lower case represents 10, \c 'B'
227 represents 11, and so forth, with \c 'Z' representing 35.)
228
229 If \c endptr is not NULL, strtoul() stores the address of the first
230 invalid character in \c *endptr. If there were no digits at all,
231 however, strtoul() stores the original value of \c nptr in \c
232 *endptr. (Thus, if \c *nptr is not \c '\\0' but \c **endptr is \c '\\0'
233 on return, the entire string was valid.)
234
235 The strtoul() function return either the result of the conversion
236 or, if there was a leading minus sign, the negation of the result
237 of the conversion, unless the original (non-negated) value would
238 overflow; in the latter case, strtoul() returns ULONG_MAX, and \c
239 errno is set to \ref avr_errno "ERANGE". If no conversion could
240 be performed, 0 is returned.
241 */
242 extern unsigned long strtoul(const char *__nptr, char **__endptr, int __base);
243
244 /**
245 The atol() function converts the initial portion of the string
246 pointed to by \p s to long integer representation. In contrast to
247
248 \code strtol(s, (char **)NULL, 10); \endcode
249
250 this function does not detect overflow (\c errno is not changed and
251 the result value is not predictable), uses smaller memory (flash and
252 stack) and works more quickly.
253 */
254 extern long atol(const char *__s) __ATTR_PURE__;
255
256 /**
257 The atoi() function converts the initial portion of the string
258 pointed to by \p s to integer representation. In contrast to
259
260 \code (int)strtol(s, (char **)NULL, 10); \endcode
261
262 this function does not detect overflow (\c errno is not changed and
263 the result value is not predictable), uses smaller memory (flash and
264 stack) and works more quickly.
265 */
266 extern int atoi(const char *__s) __ATTR_PURE__;
267
268 /**
269 The exit() function terminates the application. Since there is no
270 environment to return to, \c status is ignored, and code execution
271 will eventually reach an infinite loop, thereby effectively halting
272 all code processing. Before entering the infinite loop, interrupts
273 are globally disabled.
274
275 In a C++ context, global destructors will be called before halting
276 execution.
277 */
278 extern void exit(int __status) __ATTR_NORETURN__;
279
280 /**
281 The malloc() function allocates \c size bytes of memory.
282 If malloc() fails, a NULL pointer is returned.
283
284 Note that malloc() does \e not initialize the returned memory to
285 zero bytes.
286
287 See the chapter about \ref malloc "malloc() usage" for implementation
288 details.
289 */
290 extern void *malloc(size_t __size) __ATTR_MALLOC__;
291
292 /**
293 The free() function causes the allocated memory referenced by \c
294 ptr to be made available for future allocations. If \c ptr is
295 NULL, no action occurs.
296 */
297 extern void free(void *__ptr);
298
299 /**
300 \c malloc() \ref malloc_tunables "tunable".
301 */
302 extern size_t __malloc_margin;
303
304 /**
305 \c malloc() \ref malloc_tunables "tunable".
306 */
307 extern char *__malloc_heap_start;
308
309 /**
310 \c malloc() \ref malloc_tunables "tunable".
311 */
312 extern char *__malloc_heap_end;
313
314 /**
315 Allocate \c nele elements of \c size each. Identical to calling
316 \c malloc() using <tt>nele * size</tt> as argument, except the
317 allocated memory will be cleared to zero.
318 */
319 extern void *calloc(size_t __nele, size_t __size) __ATTR_MALLOC__;
320
321 /**
322 The realloc() function tries to change the size of the region
323 allocated at \c ptr to the new \c size value. It returns a
324 pointer to the new region. The returned pointer might be the
325 same as the old pointer, or a pointer to a completely different
326 region.
327
328 The contents of the returned region up to either the old or the new
329 size value (whatever is less) will be identical to the contents of
330 the old region, even in case a new region had to be allocated.
331
332 It is acceptable to pass \c ptr as NULL, in which case realloc()
333 will behave identical to malloc().
334
335 If the new memory cannot be allocated, realloc() returns NULL, and
336 the region at \c ptr will not be changed.
337 */
338 extern void *realloc(void *__ptr, size_t __size) __ATTR_MALLOC__;
339
340 extern double strtod(const char *__nptr, char **__endptr);
341
342 extern double atof(const char *__nptr);
343
344 /** Highest number that can be generated by rand(). */
345 #define RAND_MAX 0x7FFF
346
347 /**
348 The rand() function computes a sequence of pseudo-random integers in the
349 range of 0 to \c RAND_MAX (as defined by the header file <stdlib.h>).
350
351 The srand() function sets its argument \c seed as the seed for a new
352 sequence of pseudo-random numbers to be returned by rand(). These
353 sequences are repeatable by calling srand() with the same seed value.
354
355 If no seed value is provided, the functions are automatically seeded with
356 a value of 1.
357
358 In compliance with the C standard, these functions operate on
359 \c int arguments. Since the underlying algorithm already uses
360 32-bit calculations, this causes a loss of precision. See
361 \c random() for an alternate set of functions that retains full
362 32-bit precision.
363 */
364 extern int rand(void);
365 /**
366 Pseudo-random number generator seeding; see rand().
367 */
368 extern void srand(unsigned int __seed);
369
370 /**
371 Variant of rand() that stores the context in the user-supplied
372 variable located at \c ctx instead of a static library variable
373 so the function becomes re-entrant.
374 */
375 extern int rand_r(unsigned long *__ctx);
376 /*@}*/
377
378 /*@{*/
379 /** \name Non-standard (i.e. non-ISO C) functions.
380 \ingroup avr_stdlib
381 */
382 /**
383 \brief Convert an integer to a string.
384
385 The function itoa() converts the integer value from \c val into an
386 ASCII representation that will be stored under \c s. The caller
387 is responsible for providing sufficient storage in \c s.
388
389 \note The minimal size of the buffer \c s depends on the choice of
390 radix. For example, if the radix is 2 (binary), you need to supply a buffer
391 with a minimal length of 8 * sizeof (int) + 1 characters, i.e. one
392 character for each bit plus one for the string terminator. Using a larger
393 radix will require a smaller minimal buffer size.
394
395 \warning If the buffer is too small, you risk a buffer overflow.
396
397 Conversion is done using the \c radix as base, which may be a
398 number between 2 (binary conversion) and up to 36. If \c radix
399 is greater than 10, the next digit after \c '9' will be the letter
400 \c 'a'.
401
402 If radix is 10 and val is negative, a minus sign will be prepended.
403
404 The itoa() function returns the pointer passed as \c s.
405 */
406 extern char *itoa(int __val, char *__s, int __radix);
407
408 /**
409 \ingroup avr_stdlib
410
411 \brief Convert a long integer to a string.
412
413 The function ltoa() converts the long integer value from \c val into an
414 ASCII representation that will be stored under \c s. The caller
415 is responsible for providing sufficient storage in \c s.
416
417 \note The minimal size of the buffer \c s depends on the choice of
418 radix. For example, if the radix is 2 (binary), you need to supply a buffer
419 with a minimal length of 8 * sizeof (long int) + 1 characters, i.e. one
420 character for each bit plus one for the string terminator. Using a larger
421 radix will require a smaller minimal buffer size.
422
423 \warning If the buffer is too small, you risk a buffer overflow.
424
425 Conversion is done using the \c radix as base, which may be a
426 number between 2 (binary conversion) and up to 36. If \c radix
427 is greater than 10, the next digit after \c '9' will be the letter
428 \c 'a'.
429
430 If radix is 10 and val is negative, a minus sign will be prepended.
431
432 The ltoa() function returns the pointer passed as \c s.
433 */
434 extern char *ltoa(long int __val, char *__s, int __radix);
435
436 /**
437 \ingroup avr_stdlib
438
439 \brief Convert an unsigned integer to a string.
440
441 The function utoa() converts the unsigned integer value from \c val into an
442 ASCII representation that will be stored under \c s. The caller
443 is responsible for providing sufficient storage in \c s.
444
445 \note The minimal size of the buffer \c s depends on the choice of
446 radix. For example, if the radix is 2 (binary), you need to supply a buffer
447 with a minimal length of 8 * sizeof (unsigned int) + 1 characters, i.e. one
448 character for each bit plus one for the string terminator. Using a larger
449 radix will require a smaller minimal buffer size.
450
451 \warning If the buffer is too small, you risk a buffer overflow.
452
453 Conversion is done using the \c radix as base, which may be a
454 number between 2 (binary conversion) and up to 36. If \c radix
455 is greater than 10, the next digit after \c '9' will be the letter
456 \c 'a'.
457
458 The utoa() function returns the pointer passed as \c s.
459 */
460 extern char *utoa(unsigned int __val, char *__s, int __radix);
461
462 /**
463 \ingroup avr_stdlib
464 \brief Convert an unsigned long integer to a string.
465
466 The function ultoa() converts the unsigned long integer value from
467 \c val into an
468 ASCII representation that will be stored under \c s. The caller
469 is responsible for providing sufficient storage in \c s.
470
471 \note The minimal size of the buffer \c s depends on the choice of
472 radix. For example, if the radix is 2 (binary), you need to supply a buffer
473 with a minimal length of 8 * sizeof (unsigned long int) + 1 characters,
474 i.e. one character for each bit plus one for the string terminator. Using a
475 larger radix will require a smaller minimal buffer size.
476
477 \warning If the buffer is too small, you risk a buffer overflow.
478
479 Conversion is done using the \c radix as base, which may be a
480 number between 2 (binary conversion) and up to 36. If \c radix
481 is greater than 10, the next digit after \c '9' will be the letter
482 \c 'a'.
483
484 The ultoa() function returns the pointer passed as \c s.
485 */
486 extern char *ultoa(unsigned long int __val, char *__s, int __radix);
487
488 /** \ingroup avr_stdlib
489 Highest number that can be generated by random(). */
490 #define RANDOM_MAX 0x7FFFFFFF
491
492 /**
493 \ingroup avr_stdlib
494 The random() function computes a sequence of pseudo-random integers in the
495 range of 0 to \c RANDOM_MAX (as defined by the header file <stdlib.h>).
496
497 The srandom() function sets its argument \c seed as the seed for a new
498 sequence of pseudo-random numbers to be returned by rand(). These
499 sequences are repeatable by calling srandom() with the same seed value.
500
501 If no seed value is provided, the functions are automatically seeded with
502 a value of 1.
503 */
504 extern long random(void);
505 /**
506 \ingroup avr_stdlib
507 Pseudo-random number generator seeding; see random().
508 */
509 extern void srandom(unsigned long __seed);
510
511 /**
512 \ingroup avr_stdlib
513 Variant of random() that stores the context in the user-supplied
514 variable located at \c ctx instead of a static library variable
515 so the function becomes re-entrant.
516 */
517 extern long random_r(unsigned long *__ctx);
518 #endif /* __ASSEMBLER */
519 /*@}*/
520
521 /*@{*/
522 /** \name Conversion functions for double arguments.
523 \ingroup avr_stdlib
524 Note that these functions are not located in the default library,
525 <tt>libc.a</tt>, but in the mathematical library, <tt>libm.a</tt>.
526 So when linking the application, the \c -lm option needs to be
527 specified.
528 */
529 /** \ingroup avr_stdlib
530 Bit value that can be passed in \c flags to dtostre(). */
531 #define DTOSTR_ALWAYS_SIGN 0x01 /* put '+' or ' ' for positives */
532 /** \ingroup avr_stdlib
533 Bit value that can be passed in \c flags to dtostre(). */
534 #define DTOSTR_PLUS_SIGN 0x02 /* put '+' rather than ' ' */
535 /** \ingroup avr_stdlib
536 Bit value that can be passed in \c flags to dtostre(). */
537 #define DTOSTR_UPPERCASE 0x04 /* put 'E' rather 'e' */
538
539 #ifndef __ASSEMBLER__
540
541 /**
542 \ingroup avr_stdlib
543 The dtostre() function converts the double value passed in \c val into
544 an ASCII representation that will be stored under \c s. The caller
545 is responsible for providing sufficient storage in \c s.
546
547 Conversion is done in the format \c "[-]d.ddde±dd" where there is
548 one digit before the decimal-point character and the number of
549 digits after it is equal to the precision \c prec; if the precision
550 is zero, no decimal-point character appears. If \c flags has the
551 DTOSTRE_UPPERCASE bit set, the letter \c 'E' (rather than \c 'e' ) will be
552 used to introduce the exponent. The exponent always contains two
553 digits; if the value is zero, the exponent is \c "00".
554
555 If \c flags has the DTOSTRE_ALWAYS_SIGN bit set, a space character
556 will be placed into the leading position for positive numbers.
557
558 If \c flags has the DTOSTRE_PLUS_SIGN bit set, a plus sign will be
559 used instead of a space character in this case.
560
561 The dtostre() function returns the pointer to the converted string \c s.
562 */
563 extern char *dtostre(double __val, char *__s, unsigned char __prec,
564 unsigned char __flags);
565
566 /**
567 \ingroup avr_stdlib
568 The dtostrf() function converts the double value passed in \c val into
569 an ASCII representationthat will be stored under \c s. The caller
570 is responsible for providing sufficient storage in \c s.
571
572 Conversion is done in the format \c "[-]d.ddd". The minimum field
573 width of the output string (including the \c '.' and the possible
574 sign for negative values) is given in \c width, and \c prec determines
575 the number of digits after the decimal sign. \c width is signed value,
576 negative for left adjustment.
577
578 The dtostrf() function returns the pointer to the converted string \c s.
579 */
580 extern char *dtostrf(double __val, signed char __width,
581 unsigned char __prec, char *__s);
582
583 /*@}*/
584
585 #if 0 /* not yet implemented */
586 extern int atexit(void (*)(void));
587 #endif
588
589 #ifdef __cplusplus
590 }
591 #endif
592
593 #endif /* __ASSEMBLER */
594
595 #endif /* _STDLIB_H_ */

Automatically generated by Doxygen 1.8.3.1 on Sat Sep 14 2013.