Chapter 4. Standard C Library

A subset of the C standard library is supported. This chapter covers the functions that have been supported. Since AVR processors have several memory spaces, developers must be careful when passing parameters to functions that expect pointers. The C library understands only one type of pointer, so passing addresses to data in the EEPROM or FLASH will fail. Routines that understand these other memory spaces are addressed in Section 5.1 and Section 5.3.

It should also be noted that if your application uses the floating point libraries, you'll need to link with them. Add -lm to your link command.

4.1. Function Reference

4.1.1. abort

#include <stdlib.h>
	    

void abort(void);

description. Stops your application. It is currently implemented as an infinite loop.

4.1.2. abs

#include <stdlib.h>
	    

int abs(int x);

description. Computes and returns the absolute value of x

see also. fabs(), labs()

4.1.3. atoi

#include <stdlib.h>
	    

int atoi(char const* str);

description. Returns an integer represented by str. This function ignores leading whitespace. It stops converting when it sees the first nonsensical characters (i.e. "123test" will return 123). If no leading portion of the string represents an integer, 0 is returned.)

4.1.4. atol

#include <stdlib.h>
	    

long atol(char const* str);

description. Returns a long integer represented by str. This function ignores leading whitespace. It stops converting when it sees the first nonsensical characters (i.e. "123test" will return 123). If no leading portion of the string represents a long integer, 0 is returned.)

4.1.5. bsearch

#include <stdlib.h>
	    

void* bsearch(void const* key, void const* data, size_t total, size_t size, __compar_fn_t f);

description. Performs a binary search to find an element of an array that matches a key. The base address of the array is given by the data argument. The size of each element if the array is specifies by the size. The total number of elements in the array is specified by total. The data with which to search is indicated with key.

The function makes decisions by calling the user-supplied function f. It is assumed that the elements of the array are sorted in a fashion meaningful to key. The prototype for this function is:

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

The first argument passed to the compare function will be key. The second argument will be a pointer to an element in the array. If key matches the element, the function should return 0. If key is greater than the element, the function should return 1. Otherwise it should return -1.

4.1.6. cos

#include <math.h>
	    

double cos(double x);

description. Computes the cosine of its argument. The argument x should be in radians.

4.1.7. cosh

#include <math.h>
	    

double cosh(double x);

description. Computes the hyperbolic cosine of its argument.

4.1.8. div

#include <stdlib.h>
	    

div_t div(int num, int denom);

description. Computes num / denom. The quotient and remainder are stored and returned in a div_t structure:

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

see also. ldiv()

4.1.9. exit

#include <stdlib.h>
	    

int exit(void);

description. Stops your application. It is currently implemented as an infinite loop.

4.1.10. fabs

#include <math.h>
	    

double fabs(double x);

description. Returns the absolute value of x.

see also. abs(), labs()

4.1.11. isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

#include <ctype.h>
	    

int isalnum(int ch);

int isalpha(int ch);

int isascii(int ch);

int isblank(int ch);

int iscntrl(int ch);

int isdigit(int ch);

int isgraph(int ch);

int islower(int ch);

int isprint(int ch);

int ispunct(int ch);

int isspace(int ch);

int isupper(int ch);

int isxdigit(int ch);

description. These function perform character classification. They return true or false status depending whether the character passed to the function falls into the function's classification (i.e. isdigit() returns true if its argument is any value '0' though '9', inclusive.)

It should be noted that if any of these functions is used, they all get pulled in to your hex file (they're in the same source file). The comments in the source indicate that 182 bytes will get consumed.

4.1.12. labs

#include <stdlib.h>
	    

long labs(long x);

description. Computes and returns the absolute value of x

see also. abs(), fabs()

4.1.13. ldiv

#include <stdlib.h>
	    

ldiv_t ldiv(long num, long denom);

description. Computes num/denom. The quotient and remainder are stored and returned in a ldiv_t structure:

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

see also. div()

4.1.14. longjmp

#include <setjmp.h>
	    

int longjmp(jmp_buf buf, int ret);

description. This function restores the application environment to what it was when setjmp() was used to initialize buf. This function does not return. Instead, execution continues after the corresponding setjmp(). The only difference is that the function setjmp() returns the value ret rather than 0.

see also. setjmp()

4.1.15. qsort

#include <stdlib.h>
	    

void qsort(void* data, size_t total, size_t size, __compar_fn_t f);

description. Sorts the elements on an array using the "quick sort" algorithm. The base address of the array is given by the data argument. The size of each element if the array is specifies by the size. The total number of elements in the array is specified by total.

The sorting decision is made by passing two elements of the array to the user-supplied function f. The prototype for this function is:

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

If the first element matches the second, the function should return 0. If the first is greater than the second, the function should return 1. Otherwise it should return -1.

4.1.16. setjmp

#include <setjmp.h>
	    

int setjmp(jmp_buf buf);

description. This function saves its environment into the chunk of memory defined by buf. This function returns 0. The buffer is used by a later call to longjmp().

On the AVR processors, jmp_buf structures need 24 bytes of storage, so make sure you have enough stack space or RAM available.

see also. longjmp()

4.1.17. sin

#include <math.h>
	    

double sin(double x);

description. Computes the sine of its argument. The argument x should be in radians.

4.1.18. sinh

#include <math.h>
	    

double sinh(double x);

description. Computes the hyperbolic sine of its argument.

4.1.19. sqrt

#include <math.h>
	    

double sqrt(double x);

description. Computes the square root of its argument. The argument x should be positive. If it is negative, errno will be set to EDOM.

4.1.20. tan

#include <math.h>
	    

double tan(double x);

description. Computes the tangent of its argument. The argument x should be in radians.

4.1.21. toascii

#include <ctype.h>
	    

int toascii(int ch);

description. Converts the argument to a value that fits in the range of ASCII values (0 - 0x7f). It does this masking off the upper bits. This function is defined in the same file as the isalpha(), etc. set of functions, so if you use this function in your code, you will pull in all the others. If you don't need those other functions, you can save a lot of program space by simply ANDing your value with 0x7f.

4.1.22. tolower, toupper

#include <ctype.h>
	    

int tolower(int ch);

int toupper(int ch);

description. Converts the argument to its upper-case or lower-case representation, depending upon which function you call. This function does not recognise international characters. These functions are defined in the same file as the isalpha(), etc. set of functions, so if you use either function in your code, you will pull in all the others.