avr-libc: <stdlib.h>: General utilities

avr-libc 2.0.0 Standard C library for AVR-GCC |

## AVR Libc Home Page |  | ## AVR Libc Development Pages
## Main Page | ## User Manual | ## Library Reference | ## FAQ | ## Example Projects

<stdlib.h>: General utilities

## Non-standard (i.e. non-ISO C) functions.
char * | ltoa (long val, char *s, int radix)
char * | utoa (unsigned int val, char *s, int radix)
char * | ultoa (unsigned long val, char *s, int radix)
long | random (void)
void | srandom (unsigned long __seed)
long | random_r (unsigned long *__ctx)
char * | itoa (int val, char *s, int radix)
#define | RANDOM_MAX 0x7FFFFFFF

## Conversion functions for double arguments.
Note that these functions are not located in the default library, `libc.a`, but in the mathematical library, `libm.a`. So when linking the application, the `-lm` option needs to be specified.
char * | dtostre (double __val, char *__s, unsigned char __prec, unsigned char __flags)
char * | dtostrf (double __val, signed char __width, unsigned char __prec, char *__s)
#define | DTOSTR_ALWAYS_SIGN 0x01 /* put '+' or ' ' for positives */
#define | DTOSTR_PLUS_SIGN 0x02 /* put '+' rather than ' ' */
#define | DTOSTR_UPPERCASE 0x04 /* put 'E' rather 'e' */
#define | EXIT_SUCCESS 0
#define | EXIT_FAILURE 1

## Detailed Description

#include <stdlib.h>

This file declares some basic C macros and functions as defined by the ISO standard, plus some AVR-specific extensions.

## Macro Definition Documentation

## ◆ DTOSTR_ALWAYS_SIGN

#define DTOSTR_ALWAYS_SIGN 0x01 /* put '+' or ' ' for positives */

Bit value that can be passed in `flags` to dtostre().

## ◆ DTOSTR_PLUS_SIGN

#define DTOSTR_PLUS_SIGN 0x02 /* put '+' rather than ' ' */

Bit value that can be passed in `flags` to dtostre().

## ◆ DTOSTR_UPPERCASE

#define DTOSTR_UPPERCASE 0x04 /* put 'E' rather 'e' */

Bit value that can be passed in `flags` to dtostre().

## ◆ EXIT_FAILURE

#define EXIT_FAILURE 1

Unsuccessful termination for exit(); evaluates to a non-zero value.

## ◆ EXIT_SUCCESS

#define EXIT_SUCCESS 0

Successful termination for exit(); evaluates to 0.

## ◆ RANDOM_MAX

#define RANDOM_MAX 0x7FFFFFFF

Highest number that can be generated by random().

## Function Documentation

## ◆ dtostre()

char* dtostre | ( | double | __val,
|  | char * | __s,
|  | unsigned char | __prec,
|  | unsigned char | __flags
| ) |  |

The dtostre() function converts the double value passed in `val` into an ASCII representation that will be stored under `s`. The caller is responsible for providing sufficient storage in `s`.

Conversion is done in the format `"[-]d.ddde±dd"` where there is one digit before the decimal-point character and the number of digits after it is equal to the precision `prec`; if the precision is zero, no decimal-point character appears. If `flags` has the DTOSTRE_UPPERCASE bit set, the letter `'E'` (rather than `'e'` ) will be used to introduce the exponent. The exponent always contains two digits; if the value is zero, the exponent is `"00"`.

If `flags` has the DTOSTRE_ALWAYS_SIGN bit set, a space character will be placed into the leading position for positive numbers.

If `flags` has the DTOSTRE_PLUS_SIGN bit set, a plus sign will be used instead of a space character in this case.

The dtostre() function returns the pointer to the converted string `s`.

## ◆ dtostrf()

char* dtostrf | ( | double | __val,
|  | signed char | __width,
|  | unsigned char | __prec,
|  | char * | __s
| ) |  |

The dtostrf() function converts the double value passed in `val` into an ASCII representationthat will be stored under `s`. The caller is responsible for providing sufficient storage in `s`.

Conversion is done in the format `"[-]d.ddd"`. The minimum field width of the output string (including the possible `'`.' and the possible sign for negative values) is given in `width`, and `prec` determines the number of digits after the decimal sign. `width` is signed value, negative for left adjustment.

The dtostrf() function returns the pointer to the converted string `s`.

## ◆ itoa()

char* itoa | ( | int | val,
|  | char * | s,
|  | int | radix
| ) |  |

Convert an integer to a string.

The function itoa() converts the integer value from `val` into an ASCII representation that will be stored under `s`. The caller is responsible for providing sufficient storage in `s`.

Note
  The minimal size of the buffer `s` depends on the choice of radix. For example, if the radix is 2 (binary), you need to supply a buffer with a minimal length of 8 * sizeof (int) + 1 characters, i.e. one character for each bit plus one for the string terminator. Using a larger radix will require a smaller minimal buffer size.

Warning
  If the buffer is too small, you risk a buffer overflow.

Conversion is done using the `radix` as base, which may be a number between 2 (binary conversion) and up to 36. If `radix` is greater than 10, the next digit after `'9'` will be the letter `'a'`.

If radix is 10 and val is negative, a minus sign will be prepended.

The itoa() function returns the pointer passed as `s`.

## ◆ ltoa()

char* ltoa | ( | long | val,
|  | char * | s,
|  | int | radix
| ) |  |

Convert a long integer to a string.

The function ltoa() converts the long integer value from `val` into an ASCII representation that will be stored under `s`. The caller is responsible for providing sufficient storage in `s`.

Note
  The minimal size of the buffer `s` depends on the choice of radix. For example, if the radix is 2 (binary), you need to supply a buffer with a minimal length of 8 * sizeof (long int) + 1 characters, i.e. one character for each bit plus one for the string terminator. Using a larger radix will require a smaller minimal buffer size.

Warning
  If the buffer is too small, you risk a buffer overflow.

Conversion is done using the `radix` as base, which may be a number between 2 (binary conversion) and up to 36. If `radix` is greater than 10, the next digit after `'9'` will be the letter `'a'`.

If radix is 10 and val is negative, a minus sign will be prepended.

The ltoa() function returns the pointer passed as `s`.

## ◆ random()

long random | ( | void |  | ) |

The random() function computes a sequence of pseudo-random integers in the range of 0 to `RANDOM_MAX` (as defined by the header file <stdlib.h>).

The srandom() function sets its argument `seed` as the seed for a new sequence of pseudo-random numbers to be returned by rand(). These sequences are repeatable by calling srandom() with the same seed value.

If no seed value is provided, the functions are automatically seeded with a value of 1.

## ◆ random_r()

long random_r | ( | unsigned long * | __ctx | ) |

Variant of random() that stores the context in the user-supplied variable located at `ctx` instead of a static library variable so the function becomes re-entrant.

## ◆ srandom()

void srandom | ( | unsigned long | __seed | ) |

Pseudo-random number generator seeding; see random().

## ◆ ultoa()

char* ultoa | ( | unsigned long | val,
|  | char * | s,
|  | int | radix
| ) |  |

Convert an unsigned long integer to a string.

The function ultoa() converts the unsigned long integer value from `val` into an ASCII representation that will be stored under `s`. The caller is responsible for providing sufficient storage in `s`.

Note
  The minimal size of the buffer `s` depends on the choice of radix. For example, if the radix is 2 (binary), you need to supply a buffer with a minimal length of 8 * sizeof (unsigned long int) + 1 characters, i.e. one character for each bit plus one for the string terminator. Using a larger radix will require a smaller minimal buffer size.

Warning
  If the buffer is too small, you risk a buffer overflow.

Conversion is done using the `radix` as base, which may be a number between 2 (binary conversion) and up to 36. If `radix` is greater than 10, the next digit after `'9'` will be the letter `'a'`.

The ultoa() function returns the pointer passed as `s`.

## ◆ utoa()

char* utoa | ( | unsigned int | val,
|  | char * | s,
|  | int | radix
| ) |  |

Convert an unsigned integer to a string.

The function utoa() converts the unsigned integer value from `val` into an ASCII representation that will be stored under `s`. The caller is responsible for providing sufficient storage in `s`.

Note
  The minimal size of the buffer `s` depends on the choice of radix. For example, if the radix is 2 (binary), you need to supply a buffer with a minimal length of 8 * sizeof (unsigned int) + 1 characters, i.e. one character for each bit plus one for the string terminator. Using a larger radix will require a smaller minimal buffer size.

Warning
  If the buffer is too small, you risk a buffer overflow.

Conversion is done using the `radix` as base, which may be a number between 2 (binary conversion) and up to 36. If `radix` is greater than 10, the next digit after `'9'` will be the letter `'a'`.

The utoa() function returns the pointer passed as `s`.

stdlib.h