avr_stdlib(3avr)

πŸ’– NAME πŸ’–

avr_stdlib β€” that's the <stdlib.h> header, bestie: General utilities. It's from the AVR libc manual, section 3avr. This is part 1 of 3, so don't go anywhere πŸŽ€


✨ SYNOPSIS ✨

🧁 Data Structures

struct div_t
struct ldiv_t

πŸŽ€ Macros

#define RAND_MAX   0x7FFF

πŸ¦‹ Typedefs

typedef int(* __compar_fn_t) (const void *, const void *)

πŸ’… Functions

void abort (void)
int abs (int __i)
long labs (long __i)
void * bsearch (const void *__key, const void *__base, size_t __nmemb,
    size_t __size, int(*__compar)(const void *, const void *))
div_t div (int __num, int __denom) __asm__('__divmodhi4')
ldiv_t ldiv (long __num, long __denom) __asm__('__divmodsi4')
void qsort (void *__base, size_t __nmemb, size_t __size, __compar_fn_t
    __compar)
long strtol (const char *__nptr, char **__endptr, int __base)
unsigned long strtoul (const char *__nptr, char **__endptr, int __base)
long atol (const char *__s)
int atoi (const char *__s)
void exit (int __status)
void * malloc (size_t __size)
void free (void *__ptr)
void * calloc (size_t __nele, size_t __size)
void * realloc (void *__ptr, size_t __size)
float strtof (const char *__nptr, char **__endptr)
double strtod (const char *__nptr, char **__endptr)
long double strtold (const char *__nptr, char **__endptr)
int atexit (void(*func)(void))
float atoff (const char *__nptr)
double atof (const char *__nptr)
long double atofl (const char *__nptr)
int rand (void)
void srand (unsigned int __seed)
int rand_r (unsigned long *__ctx)

🌈 Variables

size_t __malloc_margin
char * __malloc_heap_start
char * __malloc_heap_end

πŸ”₯ Non-standard (i.e. non-ISO C) functions.

These ones are extra. Not ISO C. Just AVR being generous fr fr.

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.

char * ftostre (float __val, char *__s, unsigned char __prec, unsigned
    char __flags)
char * dtostre (double __val, char *__s, unsigned char __prec, unsigned
    char __flags)
char * ldtostre (long double __val, char *__s, unsigned char __prec,
    unsigned char __flags)
char * ftostrf (float __val, signed char __width, unsigned char __prec,
    char *__s)
char * dtostrf (double __val, signed char __width, unsigned char __prec,
    char *__s)
char * ldtostrf (long 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. That's the vibe: standard stuff, but with a little AVR sprinkle on top ✨


πŸ“ Macro Definition Documentation πŸ“

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

A bit value you can pass in as flags to ftostre(), dtostre() and ldtostre(). πŸ’…

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

Another bit value for the flags argument of ftostre(), dtostre() and ldtostre(). πŸŽ€

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

Yep, also a bit value for flags in ftostre(), dtostre() and ldtostre(). πŸ¦‹

#define EXIT_FAILURE 1

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

#define EXIT_SUCCESS 0

Successful termination for exit(); evaluates to 0. πŸ‘‘

#define RAND_MAX 0x7FFF

Highest number that can be generated by rand(). That's the ceiling, bestie. πŸ”₯

#define RANDOM_MAX 0x7FFFFFFF

Highest number that can be generated by random(). Bigger ceiling, same energy. ⭐


πŸ‘‘ Typedef Documentation πŸ‘‘

typedef int(* __compar_fn_t) (const void *, const void *)

Comparision function type for qsort(), just for convenience. (yes, "Comparision" β€” we're quoting the source, we don't fix, we don't touch, we don't breathe on it πŸ™ˆ)


πŸ”₯ Function Documentation πŸ”₯

void abort (void ) [extern]

The abort() function causes abnormal program termination to occur. This realization disables interrupts and jumps to _exit() function with argument equal to 1. In the limited AVR environment, execution is effectively halted by entering an infinite loop. πŸ˜΅β€πŸ’«

int abs (int __i) [extern]

The abs() function computes the absolute value of the integer i. ✨

πŸ“Œ Note: The abs() and labs() functions are builtins of gcc.

int atexit (void(* func )(void)) [extern]

The atexit() function registers function func to be run as part of the exit() function during .fini8. atexit() calls malloc(). 🫢

double atof (const char * nptr) [extern]

The atof() function converts the initial portion of the string pointed to by nptr to double representation.

It is equivalent to calling:

strtod(nptr, (char**) 0);

float atoff (const char * nptr) [extern]

The atoff() function converts the initial portion of the string pointed to by nptr to float representation.

It is equivalent to calling:

strtof(nptr, (char**) 0);

long double atofl (const char * nptr) [extern]

The atofl() function converts the initial portion of the string pointed to by nptr to long double representation.

It is equivalent to calling:

strtold(nptr, (char**) 0);

int atoi (const char * __s) [extern]

The atoi() function converts the initial portion of the string pointed to by s to integer representation. In contrast to:

(int)strtol(s, (char **)NULL, 10);

this function does not detect overflow (errno is not changed and the result value is not predictable), uses smaller memory (flash and stack) and works more quickly. fast and tiny, slay, but read the fine print bestie. πŸ‘‘

long atol (const char * __s) [extern]

The atol() function converts the initial portion of the string pointed to by s to long integer representation. In contrast to:

strtol(s, (char **)NULL, 10);

this function does not detect overflow (errno is not changed and the result value is not predictable), uses smaller memory (flash and stack) and works more quickly. same deal, different type πŸ’…

void * bsearch (const void * __key, const void * __base, size_t __nmemb, size_t __size, int(* __compar )(const void *, const void *)) [extern]

The bsearch() function searches an array of nmemb objects, the initial member of which is pointed to by base, for a member that matches the object pointed to by key. The size of each member of the array is specified by size.

The contents of the array should be in ascending sorted order according to the comparison function referenced by compar. The compar routine is expected to have two arguments which point to the key object and to an array member, in that order, and should return an integer less than, equal to, or greater than zero if the key object is found, respectively, to be less than, to match, or be greater than the array member. 🌈

The bsearch() function returns a pointer to a matching member of the array, or a null pointer if no match is found. If two members compare as equal, which member is matched is unspecified. πŸ‘€

void * calloc (size_t __nele, size_t __size) [extern]

Allocate nele elements of size each. Identical to calling malloc() using nele * size as argument, except the allocated memory will be cleared to zero. ✨

div_t div (int __num, int __denom) [extern]

The div() function computes the value num/denom and returns the quotient and remainder in a structure named div_t that contains two int members named quot and rem. two-for-one, iconic πŸ’…

char * dtostre (double __val, char * __s, unsigned char __prec, unsigned char __flags) [extern]

The dtostre() function is similar to the ftostre() function, except that it converts a double value instead of a float value.

⚠️ dtostre() is currently only supported when double is a 32-bit type.

char * dtostrf (double __val, signed char __width, unsigned char __prec, char * __s) [extern]

The dtostrf() function is similar to the ftostrf() function, except that converts a double value instead of a float value.

⚠️ ldtostre() is currently only supported when double is a 32-bit type.

void exit (int __status) [extern]

The exit() function terminates the application. Since there is no environment to return to, status is ignored, and code execution will eventually reach an infinite loop, thereby effectively halting all code processing. Before entering the infinite loop, interrupts are globally disabled. 😭

Global destructors will be called before halting execution, see the .fini sections.

void free (void * __ptr) [extern]

The free() function causes the allocated memory referenced by ptr to be made available for future allocations. If ptr is NULL, no action occurs. 🫢

char * ftostre (float __val, char * __s, unsigned char __prec, unsigned char __flags) [extern]

The ftostre() function converts the float 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.dddedd" 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 DTOSTR_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 DTOSTR_ALWAYS_SIGN bit set, a space character will be placed into the leading position for positive numbers.

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

The ftostre() function returns the pointer to the converted string s. ✨

char * ftostrf (float __val, signed char __width, unsigned char __prec, char * __s) [extern]

The ftostrf() function converts the float value passed in val into an ASCII representationthat will be stored in 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 ftostrf() function returns the pointer to the converted string s.

char * itoa (int val, char * s, int radix) [extern]

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. πŸ¦‹


more coming in part 2, bestie β€” don't wander off πŸ’–

Note 🧠 β€” the minimal size of the buffer s depends on which radix you picked. Like, if radix is 2 (binary), you gotta 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. Pick a bigger radix and you need a smaller minimal buffer. Math is mathing.

⚠️ Warning β€” if the buffer is too small, you risk a buffer overflow. Not the cute kind of overflow. The kind that ruins your whole day. Give it room bestie.

Conversion is done using radix as the base, and that can 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 gets prepended. As it should.

The itoa() function returns the pointer passed as s. πŸ’…


labs

long labs (long __i) [extern]

The labs() function computes the absolute value of the long integer i. Negative in, positive out, glow-up complete. ✨

Note πŸ“Œ β€” the abs() and labs() functions are builtins of gcc. They're not just library girls, they're compiler girls.

ldiv

ldiv_t ldiv (long __num, long __denom) [extern]

The ldiv() function computes the value num/denom and returns the quotient and the remainder in a structure named ldiv_t that contains two long integer members named quot and rem. Two for one, we love a bundle deal πŸŽ€

ldtostre

char * ldtostre (long double __val, char * __s, unsigned char __prec, unsigned char __flags) [extern]

The ldtostre() function is similar to the ftostre() function, except that it converts a long double value instead of a float value.

ldtostre() is currently only supported when long double is a 32-bit type. That's the vibe check it has to pass.

ldtostrf

char * ldtostrf (long double __val, signed char __width, unsigned char __prec, char * __s) [extern]

The ldtostrf() function is similar to the ftostrf() function, except that converts a long double value instead of a float value.

ldtostre() is currently only supported when long double is a 32-bit type.

(yes it says ldtostre() in the ldtostrf() entry. i don't make the rules, i just relay them faithfully fr fr πŸ™ˆ)

ltoa

char * ltoa (long val, char * s, int radix) [extern]

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. That's on you, bestie πŸ‘‘

Note 🧠 β€” the minimal size of the buffer s depends on which radix you picked. For example, if 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. Bigger radix, smaller minimal buffer size.

⚠️ Warning β€” if the buffer is too small, you risk a buffer overflow. Again. Please just size your buffers. It's giving self-care 🫢

Conversion is done using radix as the 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 gets prepended.

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

malloc

void * malloc (size_t __size) [extern]

The malloc() function allocates size bytes of memory. If malloc() fails, a NULL pointer is returned. No memory, no pointer, no drama (well, some drama).

Note that malloc() does not initialize the returned memory to zero bytes. It hands you whatever was chillin' there before. Zero it yourself if you care.

See the chapter about malloc() usage for implementation details. πŸ“–

qsort

void qsort (void * __base, size_t __nmemb, size_t __size, __compar_fn_t __compar) [extern]

The qsort() function is a modified partition-exchange sort, or quicksort. Classic. Iconic. Main character energy of sorting algorithms.

The qsort() function sorts an array of nmemb objects, the initial member of which is pointed to by base. The size of each object is specified by size. The contents of the array base are sorted in ascending order according to a comparison function pointed to by compar, which requires two arguments pointing to the objects being compared.

The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. Three moods: negative, zero, positive. Slay.

rand

int rand (void ) [extern]

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

The srand() 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 srand() with the same seed value. Same seed, same numbers, every single time β€” it's giving determinism πŸ’€

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

In compliance with the C standard, these functions operate on int arguments. Since the underlying algorithm already uses 32-bit calculations, this causes a loss of precision. See random() for an alternate set of functions that retains full 32-bit precision. Upgrade your girlies ✨

rand_r

int rand_r (unsigned long * __ctx) [extern]

Variant of rand() that stores the context in the user-supplied variable located at ctx instead of a static library variable so the function becomes re-entrant. Thread-safe girlie behavior 🧡

random

long random (void ) [extern]

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.

(that's literally what the page says about rand() in the srandom() paragraph. relaying it exactly, no edits from me πŸ™)

random_r

long random_r (unsigned long * __ctx) [extern]

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. Again. But with the 32-bit-precision one. Obsessed 😌

realloc

void * realloc (void * __ptr, size_t __size) [extern]

The realloc() function tries to change the size of the region allocated at ptr to the new size value. It returns a pointer to the new region. The returned pointer might be the same as the old pointer, or a pointer to a completely different region. It's giving mystery. Don't assume, just use the return value πŸ’…

The contents of the returned region up to either the old or the new size value (whatever is less) will be identical to the contents of the old region, even in case a new region had to be allocated. Your data survives the move πŸŽ€

It is acceptable to pass ptr as NULL, in which case realloc() will behave identical to malloc(). Glow-up to malloc, periodt.

If the new memory cannot be allocated, realloc() returns NULL, and the region at ptr will not be changed. Old region stays untouched, that's a promise.

srand

void srand (unsigned int __seed) [extern]

Pseudo-random number generator seeding; see rand(). Short entry, huge responsibility 🌱

srandom

void srandom (unsigned long __seed) [extern]

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

strtod

double strtod (const char * __nptr, char ** __endptr) [extern]

The strtod() function is similar to strtof(), except that the conversion result is of type double instead of float.

strtod() is currently only supported when double is a 32-bit type.

strtof

float strtof (const char * nptr, char ** endptr) [extern]

The strtof() function converts the initial portion of the string pointed to by nptr to float representation.

The expected form of the string is an optional plus ( '+' ) or minus sign ( '-' ) followed by a sequence of digits optionally containing a decimal-point character, optionally followed by an exponent. An exponent consists of an 'E' or 'e', followed by an optional plus or minus sign, followed by a sequence of digits. Very specific outfit, but it eats πŸ’–

Leading white-space characters in the string are skipped. Bye whitespace, not relevant to the plot.

The strtof() function returns the converted value, if any.

If endptr is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by endptr. So you know exactly where parsing peaced out ✌️

If no conversion is performed, zero is returned and the value of nptr is stored in the location referenced by endptr.

If the correct value would cause overflow, plus or minus INFINITY is returned (according to the sign of the value), and ERANGE is stored in errno. If the correct value would cause underflow, zero is returned and ERANGE is stored in errno. The value left the chat in both directions 😭

strtol

long strtol (const char * __nptr, char ** __endptr, int __base) [extern]

The strtol() function converts the string in nptr to a long value. The conversion is done according to the given base, which must be between 2 and 36 inclusive, or be the special value 0.

The string may begin with an arbitrary amount of white space (as determined by isspace()) followed by a single optional '+' or '-' sign. If base is zero or 16, the string may then include a "0x" prefix, and the number will be read in base 16; otherwise, a zero base is taken as 10 (decimal) unless the next character is '0', in which case it is taken as 8 (octal). Sneaky auto-detect behavior, we love a flexible queen 🌈

The remainder of the string is converted to a long value in the obvious manner, stopping at the first character which is not a valid digit in the given base. (In bases above 10, the letter 'A' in either upper or lower case represents 10, 'B' represents 11, and so forth, with 'Z' representing 35.)

If endptr is not NULL, strtol() stores the address of the first invalid character in *endptr. If there were no digits at all, however, strtol() stores the original value of nptr in endptr. (Thus, if *nptr is not '\0' but **endptr is '\0' on return, the entire string was valid.) Neat little trick, iykyk πŸ‘€

The strtol() function returns the result of the conversion, unless the value would underflow or overflow. If no conversion could be performed, 0 is returned. If an overflow or underflow occurs, errno is set to ERANGE and the function return value is clamped to LONG_MIN or LONG_MAX, respectively. It gets clamped. Hard. 🫠

strtold

long double strtold (const char * __nptr, char ** __endptr) [extern]

The strtold() function is similar to strtof(), except that the conversion result is of type long double instead of float.

strtold() is currently only supported when long double is a 32-bit type.

strtoul

unsigned long strtoul (const char * __nptr, char ** __endptr, int __base) [extern]

The strtoul() function converts the string in nptr to an unsigned long value. The conversion is done according to the given base, which must be between 2 and 36 inclusive, or be the special value 0.

The string may begin with an arbitrary amount of white space (as determined by isspace()) followed by a single optional '+' or '-' sign. If base is zero or 16, the string may then include a "0x" prefix, and the number will be read in base 16; otherwise, a zero base is taken as 10 (decimal) unless the next character is '0', in which case it is taken as 8 (octal).

The remainder of the string is converted to an unsigned long value in the obvious manner, stopping at the first character which is not a valid digit in the given base. (In bases above 10, the letter 'A' in either upper or lower case represents 10, 'B' represents 11, and so forth, with 'Z' representing 35.)

If endptr is not NULL, strtoul() stores the address of the first invalid character in *endptr. If there were no digits at all, however, strtoul() stores the original value of nptr in endptr. (Thus, if *nptr is not '\0' but **endptr is '\0' on return, the entire string was valid.)


okay so the tea on strtoul()'s return value is lowkey a whole saga, so let's break it down bestie: it hands you back either the result of the conversion, or β€” if there was a leading minus sign β€” the negation of the result of the conversion, unless the original (non-negated) value would overflow 😭 and in that cursed case, strtoul() returns ULONG_MAX and errno gets set to ERANGE. And if no conversion could be performed at all? You get 0. That's it. That's the whole vibe. πŸ’€


🌈 char * ultoa (unsigned long val, char * s, int radix) [extern] 🌈

Converts an unsigned long integer into a string, slay πŸ’…. The function ultoa() takes the unsigned long integer value chillin' in val and turns it into an ASCII representation that gets stored under s. And who is responsible for making sure s has enough room? You, bestie. The caller. It's giving "bring your own storage" energy 🫢.

πŸ“ 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. Not cute. Not the moment. 😭

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' β€” so like, a is just 10 in a trench coat, iykyk πŸ‘‘

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


πŸ¦‹ char * utoa (unsigned int val, char * s, int radix) [extern] πŸ¦‹

Same energy, smaller integer πŸ’–. The function utoa() converts the unsigned integer value from val into an ASCII representation that will be stored under s. And once again, the caller is responsible for providing sufficient storage in s β€” this is a group project and the storage part is your slide πŸ™ˆ.

πŸ“ 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. The way that this is genuinely dangerous... please size your buffers fr fr πŸ’€

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. Chef's kiss, consistent queen πŸ‘‘


🌸 Variable Documentation 🌸

  • char* __malloc_heap_end [extern] β€” malloc() tunable.
  • char* __malloc_heap_start [extern] β€” malloc() tunable.
  • size_t __malloc_margin [extern] β€” malloc() tunable.

(yes bestie, that's the entire description for all three, they're mysterious like that πŸŽ€)


πŸ‘‘ Author πŸ‘‘

Generated automatically by Doxygen for AVR-LibC from the source code. Not a human typing dramatically at 3am β€” just the robot doing its lil thing πŸ€–βœ¨


and that's a wrap on avr_stdlib(3avr) from AVR-LibC, Version 2.2.1 β€” thanks for reading all the way to the end bestie, you ate that πŸ’…πŸ«Ά mwah, go size your buffers correctly and stay iconic πŸ’–

πŸ“¦ where this page comes from