AVR libc function reference

2001/09/17

This file gives an overview of the C library functions implemented in the avr-libc standard library for the Atmel AVR microcontroller family.

As of the writing of this reference, the current version of avr-libc was 20010821.

avr-libc is maintained by Marek Michalkiewicz <[email protected]>.

This document is written by Enno Luebbers <[email protected]>. I do not take any responsibility about what happens if you use the information in this reference. You are on your own. :) Formally that means:

This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY. ALL WARRANTIES, EXPRESS OR IMPLIED ARE HEREBY DISCLAIMED. This includes but is not limited to warranties of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Documentation for most of the functions that are not hardware specific to the AVR architecture (like I/O ports or interrupt handlers) can be found in the Linux manpages.

Thanks go to Jörg Wunsch for pointing me to several errors in previous versions of this reference and for including it in the FreeBSD Port of the avr-libc. Also thanks to Jochen Pernsteiner for his explanation of strlwr() and to Peter N Lewis for his help about SIGNAL() and INTERRUPT().


Function list by Header files

ctype.h Character type test functions
eeprom.h EEPROM access functions
errno.h Error handling
ina90.h Compatibility header for IAR C
interrupt.h Interrupt handling routines
inttypes.h Defines for different int data types
io-avr.h Includes the correct ioXXX.h header
io.h Includes other I/O-Headers
ioXXX.h I/O-Defines for various AVR microcontrollers
iomacros.h Several macros for I/O access
math.h Various mathematical functions
pgmspace.h Compatibility header for IAR C
progmem.h Alias for pgmspace.h
setjmp.h Provides functions for long jumps
sig-avr.h AVR interrupt and signal handling
signal.h Alias for sig-avr.h. Should no longer be used.
stdlib.h Miscellaneous routines
string-avr.h String manipulation functions
string.h More string manipulation routines
timer.h Timer control functions
twi.h ATmega163 specific defines
wdt.h Watchdog Timer control functions

Alphabetical function list

void abort();
double acos( double x );
double asin( double x );
double atan( double x );
long atoi( char *p );
long atol( char *p );
bit_is_clear( port, bit );
bit_is_set( port, bit );
void bsearch(const void *key, const void *base, size_t nmemb,
BV( x );
cbi( port, bit );
double ceil( doublce x );
cli();
double cos( double x );
double cosh( double x );
div_t div( int x, int y );
int eeprom_is_ready()
unsigned char eeprom_rb(unsigned int addr);
void eeprom_read_block(void *buf, unsigned int addr, size_t n);
unsigned int eeprom_rw(unsigned int addr);
void eeprom_wb(unsigned int addr, unsigned char val);
void enable_external_int( unsigned char ints );
int errno();
double exp( double x );
double fabs( double x );
double floor( double x );
double fmod( double x, double y );
void free( void *ptr );
double frexp( double x, int *exp );
inp( port );
INTERRUPT( signame );
double inverse( double x );
int isalnum(int __c);
int isalpha(int __c);
int isascii(int __c);
int iscntrl(int __c);
int isdigit(int __c);
int isgraph(int __c);
int islower(int __c);
int isprint(int __c);
int ispunct(int __c);
int isspace(int __c);
int isupper(int __c);
int isxdigit(int __c);
char itoa( int value, char *string, int radix ) {
long labs( long x );
double ldexp( double x, int exp );
ldiv_t ldiv( lomg x, long y );
double log( double x );
double log10( double x );
void longjmp( jmp_buf env, int val );
loop_until_bit_is_clear( port, bit );
loop_until_bit_ist_set( port, bit );
void malloc( size_t size );
void memchr( void *s, char c, size_t n );
int memcmp( const void *s1, const void *s2, size_t n );
void memcpy( void *to, void *from, size_t n );
void memmove( void *to, void *from, size_t n );
void memset( void *s, int c, size_t n );
double modf( double x, double *iptr );
outp( value, port );
parity_even_bit( val );
double pow( double x, double y );
void qsort(void *base, size_t nmemb, size_t size, __compar_fn_t compar);
sbi( port, bit );
sei();
int setjmp( jmp_buf env );
SIG_ADC(
SIG_COMPARATOR(
SIG_EEPROM(
SIG_INPUT_CAPTURE1(
  SIG_INTERRUPT0 through SIG_INTERRUPT7
SIG_OUTPUT_COMPARE0
SIG_OUTPUT_COMPARE1A
SIG_OUTPUT_COMPARE1B
SIG_OUTPUT_COMPARE2
SIG_OVERFLOW0
SIG_OVERFLOW1
SIG_OVERFLOW2
SIG_SPI
SIG_UART1_DATA
SIG_UART1_RECV
SIG_UART1_TRANS
SIG_UART_DATA
SIG_UART_RECV
SIG_UART_TRANS
SIGNAL( signame );
double sin( double x );
double sinh( double x );
double sqrt( double x );
double square( double x );
extern int strcasecmp(const char *s1, const char *s2);
char strcat( char *dest, char *src );
char strchr( const char *s, int c );
int strcmp( const char *s1, const char* s2 );
char strcpy( char *dest, char *src );
strdupa( s );
size_t strlen( char *s );
extern char strlwr(char *);
extern int strncasecmp(const char *, const char *, size_t);
char strncat( char *dest, char *src, size_t n );
int strncmp( const char *s1, const char* s2, size_t n );
char strncpy( char *dest, char *src, size_t n );
strndupa( s, n );
size_t strnlen( const char *s, size_t maxlen );
char strrchr( const char *s, int c );
extern char strrev(char *s1);
extern char strstr(const char *haystack, const char *needle);
double strtod( char *, char ** );
double strtod( const char *s, char **endptr );
long strtol(const char *nptr, char **endptr, int base);
unsigned long strtoul(const char *nptr, char **endptr, int base);
extern char strupr(char *);
double tan( double x );
double tanh( double x );
void timer0_source( unsigned int src );
coid timer0_start();
void timer0_stop();
void timer_enable_int( unsigned char ints );
int toascii(int __c);
int tolower(int __c);
int toupper(int __c);
wdt_disable();
wdt_enable( timeout );
wdt_reset();


CTYPE.H

int isalnum(int __c); Returns 1 of c is alphanumeric, otherwise 0.
int isalpha(int __c); Returns 1 of c is alphabetic, otherwise 0.
int isascii(int __c); Returns 1 of c is contained in the 7bit ASCII, otherwise 0.
int iscntrl(int __c); Returns 1 of c is a control character, otherwise 0.
int isdigit(int __c); Returns 1 of c is a digit, otherwise 0.
int isgraph(int __c); Returns 1 of c is printable (excluding space), otherwise 0.
int islower(int __c); Returns 1 of c is a lower case alphabetic character, otherwise 0.
int isprint(int __c); Returns 1 of c is printable (including space), otherwise 0.
int ispunct(int __c); Returns 1 of c is a puntuation character, otherwise 0.
int isspace(int __c); Returns 1 of c is one of space, '\n', '\f', '\r', '\t', '\v', otherwise 0.
int isupper(int __c); Returns 1 of c is an upper case alphabetic character, otherwise 0.
int isxdigit(int __c); Returns 1 of c is a hexadecimal digit (0-9 or A-F), otherwise 0.
int toascii(int __c); Converts c to a 7bit ASCII character.
int tolower(int __c); Converts c to lower case.
int toupper(int __c); Converts c to upper case.

EEPROM.H

int eeprom_is_ready() /* Macro */ Returns != 0 if the EEPROM is ready (bit EEWE in register EECR is 0).
unsigned char eeprom_rb(unsigned int addr); Read one byte from EEPROM address 'addr'.
unsigned int eeprom_rw(unsigned int addr); Read one 16-bit word (little endian) from EEPROM address 'addr'.
void eeprom_wb(unsigned int addr, unsigned char val); Write a byte 'val' to EEPROM address 'addr'.
void eeprom_read_block(void *buf, unsigned int addr, size_t n); Read a block of 'size' bytes from EEPROM address 'addr' to 'buf'.
_EEPUT(addr, val) eeprom_wb(addr, val)
_EEGET(var, addr) (var) = eeprom_rb(addr)
Compatibility macros for IAR C compatibility.

ERRNO.H

int errno; Holds the system-wide error code.

INA90.H

This header file contains some compatibility functions and macros to make porting applications from the IAR C compiler to avr-gcc easier. Since you wouldn't use it for writing new applications, there's no need for documentation here (lazy me).


INTERRUPT.H

sei(); Enable Interrupts. Macro.
cli(); Disable Interrupts. Macro.
void enable_external_int( unsigned char ints ); Write 'ints' to the EIMSK or GIMSK register, depending on whether EIMSK or GIMSK is defined.
void timer_enable_int( unsigned char ints ); Write 'ints' to the TIMSK register, if TIMSK is defined.

INTTYPES.H

Defines the following types:

typedef signed char int8_t;
typedef unsigned char uint8_t;

typedef int int16_t;
typedef unsigned int uint16_t;

typedef long int32_t;
typedef unsigned long uint32_t;

typedef long long int64_t;
typedef unsigned long long uint64_t;

typedef int16_t intptr_t;
typedef uint16_t uintptr_t;

Be careful with the -mint8 option, though.


IO-AVR.H

Automagically includes the ioXXX.h header file for the target AVR microcontroller.


IO.H

Just includes both io-avr.h and iomacros.h.


IOXXX.H

I/O-register definitions for the XXX MCU. Refer to the specific datasheet for a description of the registers and their functions.


IOMACROS.H

BV( x ); Returns the value of bit x (BitValue). Essentially an (1 << x). Macro.
inp( port ); Read byte from port 'port'. Macro. Automagically distinguishes between constant and non-constant memory I/O addresses and calls the macros __inb or __mmio, respectively.
outp( value, port ); Write 'value' to 'port'. Macro. Similar black magic as inp( port ).
cbi( port, bit ); Clear bit 'bit' in port 'port'. Macro. Slowly the black magic here is getting the better of me.
sbi( port, bit ); Set bit 'bit' in port 'port'. Macro. Don't ask.
bit_is_set( port, bit ); Returns something != 0, if bit 'bit' in 'port' is set, otherwise 0. Macro.
bit_is_clear( port, bit ); Returns something != 0, if bit 'bit' in 'port' is clear, otherwise 0. Macro.
loop_until_bit_ist_set( port, bit ); Loops until bit 'bit' in port 'port' is set. Macro.
loop_until_bit_is_clear( port, bit ); Loops until bit 'bit' in port 'port' is clear. Macro.
parity_even_bit( val ); I have no idea what this macro does. Any suggestions? Marek?

MATH.H

Constants:

M_PI = 3.141592653589793238462643
Pi.
M_SQRT2 = 1.4142135623730950488016887
The square root of two.
double cos( double x ); Returns the cosine of x.
double fabs( double x ); Returns the absolute value of x.
double fmod( double x, double y ); Returns the floating point remainder of x/y.
double modf( double x, double *iptr ); Returns the fractional part of x and stores the integral part in *iptr.
double sin( double x ); Returns the sine of x.
double sqrt( double x ); Returns the square root of x.
double tan( double x ); Returns the tangens of x.
double floor( double x ); Returns the biggest integer smaller than x.
double ceil( doublce x ); Returns the smallest integer bigger than x.
double frexp( double x, int *exp ); Splits x into a normalized fraction, which is returned, and an exponent, which is stored in *exp.
double ldexp( double x, int exp ); Returns the result of x*2^exp.
double exp( double x ); Returns e^x;
double cosh( double x ); Returns the hyperbolic cosine of x.
double sinh( double x ); Returns the hyperbolic sine of x.
double tanh( double x ); Returns the hyperbolc tangens of x.
double acos( double x ); Returns the arc cosine of x.
double asin( double x ); Returns the arc sine of x.
double atan( double x ); Returns the arc tangens of x. Output between -PI/2 and PI/2 (inclusive).
double atan2( double x, double y ); Returns the arc tangens of x/y. Also takes the signs of both arguments into account when determinig the quadrant. Output between -PI and PI (inclusive).
double log( double x ); Returns the natural logarithm of x.
double log10( double x ); Returns the logarithm of x to the base 10.
double pow( double x, double y ); Returns x^y.
double strtod( const char *s, char **endptr ); Converts an ASCII string to a double.
double square( double x ); Returns x^2;
double inverse( double x ); Returns 1/x;

PGMSPACE.H

Another compatibility header file for the IAR C compiler. Contains (or is suposed to contain) things like memcpy_P, strcat_P, printf_P etc.

Since it's a compatibility header file, I chose not to document it. Yet.


PROGMEM.H

Includes pgmspace.h.


SETJMP.H

int setjmp( jmp_buf env ); Declares a longjmp-Target to be jumped at with longjmp (see below.).
void longjmp( jmp_buf env, int val ); Executes a long jump to the position previously defined with setjmp( 'env' ), which will return 'val'.

SIG-AVR.H

Defines symbols for the interrupt vectors that are stored at the begining of the flash memory. Defined are:

SIG_INTERRUPT0 through SIG_INTERRUPT7 Handler function name for the external interrupts 0 through 7. Interrupts > 1 are only available on certain ATmega AVRs.
SIG_OUTPUT_COMPARE2 Handler function name for the Compare2 interrupt (Analog Comparator).
SIG_OVERFLOW2 Handler function name for the Overflow2 interrupt.
SIG_INPUT_CAPTURE1 Handler function name for the Capture1 interrupt.
SIG_OUTPUT_COMPARE1A Handler function name for the Compare1(A) interrupt.
SIG_OUTPUT_COMPARE1B Handler function name for the Compare1(B) interrupt.
SIG_OVERFLOW1 Handler function name for the Overflow1 interrupt.
SIG_OUTPUT_COMPARE0 Handler function name for the Compare0 interrupt.
SIG_OVERFLOW0 Handler function name for the Overflow0 interrupt.
SIG_SPI Handler function name for the SPI interrupt.
SIG_UART_RECV Handler function name for the UART(0) Receive Complete interrupt.
SIG_UART1_RECV Handler function name for the UART1 Receive Complete interrupt. UART1 is only available on the ATmega161.
SIG_UART_DATA Handler function name for the UART(0) Data Register Empty interrupt.
SIG_UART1_DATA Handler function name for the UART1 Data Register Empty interrupt. UART1 is only available on the ATmega161.
SIG_UART_TRANS Handler function name for the UART(0) Transmit Complete interrupt.
SIG_UART1_TRANS Handler function name for the UART1 Transmit Complete interrupt. UART1 is only available on the ATmega161.
SIG_ADC Handler function name for the ADC Comversion Complete interrupt.
SIG_EEPROM Handler function name for the EEPROM Ready interrupt.
SIG_COMPARATOR Handler function name for the Analog Comparator interrupt.

Furthermore, the following functions/macros are defined:

SIGNAL( signame ); Used for defining an Signal handler for the signal 'signame'.
INTERRUPT( signame ); Used for defining an Interrupt handler for the signal 'signame'.

In a handler defined with SIGNAL(), additional interrupts are implicitly forbidden, whereas in an INTERRUPT() handler, the first (implicit) instruction is "sei", so that additional interrupts can occur.

Thanks to Jörg Wunsch for correcting me there.


SIGNAL.H

Includes sig-avr.h. You should use sig-avr.h directly, because signal.h might disappear shortly because it conflicts with the "real" ANSI C signal.h.


STDLIB.H

Defines the following types:

typedef struct {
int quot;
int rem;
} div_t;

typedef struct {
long quot;
long rem;
} ldiv_t;

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

Used for comparison functions, eg. qsort().

Additionally, the following functions/macros are declared:

void abort(); Effectively aborts the execution by putting the MCU into an endless loop.
long labs( long x ); Returns the absolute value of x.
void *bsearch(const void *key, const void *base, size_t nmemb,
> size_t size, int (*compar)(const void *, const void *));
Performs a binary search on a sorted array.
div_t div( int x, int y ); Divides x by y and returns the result (quotient and remainder) in a div_t struct (see above).
ldiv_t ldiv( lomg x, long y ); Divides x by y and returns the result (quotient and remainder) in a ldiv_t struct (see above).
void qsort(void *base, size_t nmemb, size_t size, __compar_fn_t compar); Sorts an array at 'base' with 'nmemb' elements of size 'size', using the comparison function 'compar'.
long strtol(const char *nptr, char **endptr, int base); Converts the string at 'nptr' to a long integer according to the base 'base'.
unsigned long strtoul(const char *nptr, char **endptr, int base); Converts the string at 'nptr' to an unsigned long integer according to the base 'base'.
long atol( char *p ); Converts the string 'p' to a long integer.
long atoi( char *p ); Converts the string 'p' to an integer.
void *malloc( size_t size ); Allocates 'size' bytes of memory and returns a pointer to it. Implemented, but not tested.
void free( void *ptr ); Releases the memory at 'ptr', which was previously allocated with malloc(). Implemented, but not tested.
double strtod( char *, char ** ); See math.h.
char *itoa( int value, char *string, int radix ); Converts an integer into a string. This is not ANSI C, but nonetheless (or maybe just because of this) very useful.

The following functions are not yet implemented:

atexit(), atof(), calloc(), rand(), realloc(), srand();


STRING-AVR.H

void *memcpy( void *to, void *from, size_t n ); Copy 'n' bytes from 'from' to 'to'.
void *memmove( void *to, void *from, size_t n ); Copy 'n' bytes of 'from' to 'to', guaranteeing correct behavior for overlapping strings.
void *memset( void *s, int c, size_t n ); Set 'n' bytes of 's' to 'c'.
int memcmp( const void *s1, const void *s2, size_t n ); Compare 'n' bytes of 's1' an 's2'.
void *memchr( void *s, char c, size_t n ); Returns a pointer to the first occurence of 'c' in the first 'n' bytes of 's'.
size_t strlen( char *s ); Returns the length of 's'.
char *strcpy( char *dest, char *src ); Copies 'src' intro 'dest'.
char *strncpy( char *dest, char *src, size_t n ); Copy no more than n bytes from 'src' to 'dest'.
char *strcat( char *dest, char *src ); Append 'src' onto 'dest'.
char *strncat( char *dest, char *src, size_t n ); Append no more than 'n' bytes from 'src' onto 'dest'.
int strcmp( const char *s1, const char* s2 ); Compare 's1' and 's2'.
int strncmp( const char *s1, const char* s2, size_t n ); Compare 'n' characters from 's1' and 's2'.
strdupa( s ); Duplicate 's', returning an identical allocated string. Macro.
strndupa( s, n ); Return an allocated copy of at most 'n' bytes of 's'.
char *strchr( const char *s, int c ); Return a pointer to the first occurence of 'c' in 's'.
char *strrchr( const char *s, int c ); Return a pointer to the last occurence of 'c' in 's'.
size_t strnlen( const char *s, size_t maxlen ); Returns the length of 's', but at most 'maxlen'.

STRING.H

extern void *memccpy(void *dest, const void *src, int c, size_t n); Copy at most 'n bytes from 'src' to 'dest' until character 'c' is found.
extern void *memchr(const void *, int, size_t); See string-avr.h.
extern int memcmp(const void *, const void *, size_t); See string-avr.h.
extern void *memcpy(void *, const void *, size_t); See string-avr.h.
extern void *memmove(void *dest, const void *src, size_t n); See string-avr.h.
extern void *memset(void *, int, size_t); See string-avr.h.
extern char *strcat(char *, const char *); See string-avr.h.
extern char *strchr(const char *, int); See string-avr.h.
extern int strcmp(const char *, const char *); See string-avr.h.
extern char *strcpy(char *, const char *); See string-avr.h.
extern int strcasecmp(const char *s1, const char *s2); Compare 's1' and 's2', ignoring case.
extern size_t strlen(const char *); See string-avr.h.
extern char *strlwr(char *s); Converts all upper case characters in 's' to lower case.
extern char *strncat(char *, const char *, size_t); See string-avr.h.
extern int strncmp(const char *, const char *, size_t); See string-avr.h.
extern char *strncpy(char *, const char *, size_t); See string-avr.h.
extern int strncasecmp(const char *, const char *, size_t); Compare 'n' bytes of 's1' and 's2', ignoring case.
extern size_t strnlen(const char *, size_t); See string-avr.h.
extern char *strrchr(const char *, int); See string-avr.h.
extern char *strrev(char *s1); Probably reverses 's1'.
extern char *strstr(const char *haystack, const char *needle); Locate 'needle' in 'haystack', and return a pointer to it.
extern char *strupr(char *s); Converts all lower case characters in 's' to upper case.

TIMER.H

Defines an enumeration for the Timer Control Register:

enum {
STOP = 0,
CK = 1,
CK8 = 2,
CK64 = 3,
CK256 = 4,
CK1024 = 5,
T0_FALLING_EDGE = 6,
T0_RISING_EDGE = 7
};

And there are the following functions:
void timer0_source( unsigned int src ); Writes 'src' into the TCCR0 register.
void timer0_stop(); Stops Timer 0 by clearing the TCNT0 register.
coid timer0_start(); Starts Timer 0 by writing a 1 into the TCNT0 register.


TWI.H

Defines several constants for the ATmega163.


WDT.H

wdt_reset(); Resets the Watchdog Timer.
wdt_enable( timeout ); Enables the Watchdog Timer with timeout 'timeout'. For the actual timeout value, refer to the Atmel AVR datasheets.
wdt_disable(); Disables the Watchdog Timer.