Standard C Libraries - stdlib Utility Functions. More...

Data Structures
struct	div_t

struct	ldiv_t

Macros
#define	size_t size_t

#define	wchar_t

#define	EXIT_FAILURE

#define	EXIT_SUCCESS

#define	MB_CUR_MAX

#define	NULL (0)

#define	RAND_MAX

Functions
void	abort (void)

int	abs (int i)

int	atexit (void(*func)(void))

double	atof (const char *s)

int	atoi (const char *s)

long	atol (const char *s)

void *	bsearch (const void key, const void base, size_t nelem, size_t size, int cmp, const void ck, const void *ce)

void *	calloc (size_t nelem, size_t size)

div_t	div (int numer, int denom)

void	exit (int status)

void	free (void *ptr)

char *	getenv (const char *name)

long	labs (long i)

ldiv_t	ldiv (long numer, long denom)

void *	malloc (size_t size)

int	mblen (const char *s, size_t n)

Variables
size_t mbstowcs *	wcs

int mbtowc *	pwc

Detailed Description

Standard C Libraries - stdlib Utility Functions.

Compiler:: MPLAB XC16 compiler

Description

The header file, stdlib.h, consists of types, macros and functions that provide text conversions, memory management, searching and sorting abilities, and other general utilities.

Software License Agreement

The documentation in this header file has been copied from the documentation provided with the Microchip MPLAB XC16 compiler. The original lincense agreement included with the XC16 compiler applies!

Macro Definition Documentation

#define EXIT_FAILURE

Description: Reports unsuccessful termination.

Include: <stdlib.h>

Remarks:
EXIT_FAILURE is a value for the exit function to return an unsuccessful termination status.

Example:
See exit for example of use.

#define EXIT_SUCCESS

Description: Reports successful termination.

Include: <stdlib.h>

Remarks:
EXIT_SUCCESS is a value for the exit function to return a successful termination status.

Example:
See exit for example of use.

#define MB_CUR_MAX

Description: Maximum number of characters in a multibyte character.

Include: <stdlib.h>

Value: 1

#define NULL (0)

Description: The value of a null pointer constant.

Include: <stdlib.h>

#define RAND_MAX

Description: Maximum value capable of being returned by the rand function.

Include: <stdlib.h>

Value: 32767

#define size_t size_t

Description: The type of the result of the sizeof operator.

Include: <stdlib.h>

#define wchar_t

Description: A type that holds a wide character value.

Include: <stdlib.h>

Function Documentation

void abort ( void )

Description: Aborts the current process.

Include: <stdlib.h>

Remarks:
abort will cause the processor to reset.

Example:

#include <stdio.h> // for fopen, fclose, 
// printf, FILE, NULL 
#include <stdlib.h> // for abort 
int main(void) {
    FILE *myfile;
    if ((myfile = fopen("samp.fil", "r")) == NULL) {
        printf("Cannot open samp.fil\n");
        abort();
    } else
        printf("Success opening samp.fil\n");
    fclose(myfile);
}

Output:
Cannot open samp.fil
ABRT

int abs ( int i)

Description: Calculates the absolute value.

Include: <stdlib.h>

Parameters

i	integer value

Returns: Returns the absolute value of i.

Remarks:
A negative number is returned as positive; a positive number is unchanged.

Example:

#include <stdio.h> // for printf 
#include <stdlib.h> // for abs 
int main(void) {
    int i;
    i = 12;
    printf("The absolute value of %d is %d\n",
            i, abs(i));
    i = -2;
    printf("The absolute value of %d is %d\n",
            i, abs(i));
    i = 0;
    printf("The absolute value of %d is %d\n",
            i, abs(i));
}

Output:
The absolute value of 12 is 12
The absolute value of -2 is 2
The absolute value of 0 is 0

int atexit ( void(*)(void) func)

Description: Registers the specified function to be called when the program terminates normally.

Include: <stdlib.h>

Parameters

func	function to be called

Returns: Returns a zero if successful; otherwise, returns a non-zero value.

Remarks:
For the registered functions to be called, the program must terminate with the exit function call.

Example:

#include <stdio.h> // for scanf, printf 
#include <stdlib.h> // for atexit, exit 
void good_msg(void);
void bad_msg(void);
void end_msg(void);
int main(void) {
    int number;
    atexit(end_msg);
    printf("Enter your favorite number:");
    scanf("%d", &number);
    printf(" %d\n", number);
    if (number == 5) {
        printf("Good Choice\n");
        atexit(good_msg);
        exit(0);
    } else {
        printf("%d!?\n", number);
        atexit(bad_msg);
        exit(0);
    }
}
void good_msg(void) {
    printf("That's an excellent number\n");
}
void bad_msg(void) {
    printf("That's an awful number\n");
}
void end_msg(void) {
    printf("Now go count something\n");
}

Input:
With contents of UartIn.txt (used as stdin input for simulator): 5 Output:
Enter your favorite number: 5
Good Choice
That's an excellent number
Now go count something

Input:
With contents of UartIn.txt (used as stdin input for simulator):
42

Output:
Enter your favorite number: 42
42!?
That's an awful number
Now go count something

double atof ( const char * s)

Description: Converts a string to a double precision floating-point value.

Include: <stdlib.h>

Parameters

s	pointer to the string to be converted

Returns: Returns the converted value if successful; otherwise, returns 0.

Remarks:
The number may consist of the following:
[whitespace] [sign] digits [.digits]
[ { e | E }[sign]digits]
optional whitespace, followed by an optional sign then a sequence of one or more digits with an optional decimal point, followed by one or more optional digits and an optional e or E followed by an optional signed exponent. The conversion stops when the first unrecognized character is reached. The conversion is the same as strtod(s,0) except it does no error checking so errno will not be set.

Example:

#include <stdio.h> // for printf 
#include <stdlib.h> // for atof 
int main(void) {
    char a[] = " 1.28";
    char b[] = "27.835e2";
    char c[] = "Number1";
    double x;
    x = atof(a);
    printf("String = \"%s\" float = %f\n", a, x);
    x = atof(b);
    printf("String = \"%s\" float = %f\n", b, x);
    x = atof(c);
    printf("String = \"%s\" float = %f\n", c, x);
}

Output:
String = "1.28" float = 1.280000
String = "27.835:e2" float = 2783.500000
String = "Number1" float = 0.000000

int atoi ( const char * s)

Description: Converts a string to an integer.

Include: <stdlib.h>

Parameters

s	string to be converted

Returns: Returns the converted integer if successful; otherwise, returns 0.

Remarks:
The number may consist of the following:
[whitespace] [sign] digits
optional whitespace, followed by an optional sign then a sequence of one or more digits. The conversion stops when the first unrecognized character is reached. The conversion is equivalent to (int) strtol(s,0,10) except it does no error checking so errno will not be set.

Example:

#include <stdio.h> // for printf 
#include <stdlib.h> // for atoi 
int main(void) {
    char a[] = " -127";
    char b[] = "Number1";
    int x;
    x = atoi(a);
    printf("String = \"%s\"\tint = %d\n", a, x);
    x = atoi(b);
    printf("String = \"%s\"\tint = %d\n", b, x);
}

Output:
String = " -127" int = -127
String = "Number1" int = 0

long atol ( const char * s)

Description: Converts a string to a long integer.

Include: <stdlib.h>

Parameters

s	string to be converted

Returns: Returns the converted long integer if successful; otherwise, returns 0.

Remarks:
The number may consist of the following:
[whitespace] [sign] digits
optional whitespace, followed by an optional sign then a sequence of one or more digits. The conversion stops when the first unrecognized character is reached. The conversion is equivalent to (int) strtol(s,0,10) except it does no error checking so errno will not be set.

Example:

#include <stdio.h> // for printf 
#include <stdlib.h> // for atol 
int main(void) {
    char a[] = " -123456";
    char b[] = "2Number";
    long x;
    x = atol(a);
    printf("String = \"%s\" int = %ld\n", a, x);
    x = atol(b);
    printf("String = \"%s\" int = %ld\n", b, x);
}

Output:
String = " -123456" int = -123456
String = "2Number" int = 2

void* bsearch	(	const void *	key,
		const void *	base,
		size_t	nelem,
		size_t	size,
		int *	cmp,
		const void *	ck,
		const void *	ce
	)

Description: Performs a binary search.

Include: <stdlib.h>

Parameters

key	object to search for
base	pointer to the start of the search data
nelem	number of elements
size	size of elements
cmp	pointer to the comparison function
ck	pointer to the key for the search
ce	pointer to the element being compared with the key.

Returns: Returns a pointer to the object being searched for if found; otherwise, returns NULL.

Remarks:
The value returned by the compare function is <0 if ck is less than ce, 0 if ck is equal to ce or >0 if ck is greater than ce. In the following example, qsort is used to sort the list before bsearch is called. bsearch requires the list to be sorted according to the comparison function. This comp uses ascending order.

Example:

#include <stdlib.h> // for bsearch, qsort 
#include <stdio.h> // for printf, sizeof 
#define NUM 7
int comp(const void *e1, const void *e2);
int main(void) {
    int list[NUM] = {35, 47, 63, 25, 93, 16, 52};
    int x, y;
    int *r;
    qsort(list, NUM, sizeof (int), comp);
    printf("Sorted List: ");
    for (x = 0; x < NUM; x++)
        printf("%d ", list[x]);
    y = 25;
    r = bsearch(&y, list, NUM, sizeof (int), comp);
    if (r)
        printf("\nThe value %d was found\n", y);
    else
        printf("\nThe value %d was not found\n", y);
    y = 75;
    r = bsearch(&y, list, NUM, sizeof (int), comp);
    if (r)
        printf("\nThe value %d was found\n", y);
    else
        printf("\nThe value %d was not found\n", y);
}
int comp(const void *e1, const void *e2) {
    const int * a1 = e1;
    const int * a2 = e2;
    if (*a1 < *a2)
        return -1;
    else if (*a1 == *a2)
        return 0;
    else
        return 1;
}

Output:
Sorted List: 16 25 35 47 52 63 93
The value 25 was found
The value 75 was not found

void* calloc	(	size_t	nelem,
		size_t	size
	)

Description: Allocates an array in memory and initializes the elements to 0.

Include: <stdlib.h>

Parameters

nelem	number of elements
size	length of each element

Returns: Returns a pointer to the allocated space if successful; otherwise, returns a null pointer.

Remarks:
Memory returned by calloc is aligned correctly for any size data element and is initialized to zero.

Example:

// This program allocates memory for the 
// array 'i' of long integers and initializes 
// them to zero. 
#include <stdio.h> // for printf, NULL 
#include <stdlib.h> // for calloc, free 
int main(void) {
    int x;
    long *i;
    i = (long *) calloc(5, sizeof (long));
    if (i != NULL) {
        for (x = 0; x < 5; x++)
            printf("i[%d] = %ld\n", x, i[x]);
        free(i);
    } else
        printf("Cannot allocate memory\n");
}

Output:
i[0] = 0
i[1] = 0
i[2] = 0
i[3] = 0
i[4] = 0

div_t div	(	int	numer,
		int	denom
	)

Description: Calculates the quotient and remainder of two numbers.

Include: <stdlib.h>

Parameters

numer	numerator
denom	denominator

Returns: Returns the quotient and the remainder.

Remarks:
The returned quotient will have the same sign as the numerator divided by the denominator. The sign for the remainder will be such that the quotient times the denominator plus the remainder will equal the numerator (quot * denom + rem = numer). Division by zero will invoke the math exception error, which by default, will cause a Reset. Write a math error handler to do something else.

Example:

#include <stdlib.h> // for div, div_t 
#include <stdio.h> // for printf 
void __attribute__((__interrupt__))
_MathError(void) {
    printf("Illegal instruction executed\n");
    abort();
}
int main(void) {
    int x, y;
    div_t z;
    x = 7;
    y = 3;
    printf("For div(%d, %d)\n", x, y);
    z = div(x, y);
    printf("The quotient is %d and the "
            "remainder is %d\n\n", z.quot, z.rem);
    x = 7;
    y = -3;
    printf("For div(%d, %d)\n", x, y);
    z = div(x, y);
    printf("The quotient is %d and the "
            "remainder is %d\n\n", z.quot, z.rem);
    x = -5;
    y = 3;
    printf("For div(%d, %d)\n", x, y);
    z = div(x, y);
    printf("The quotient is %d and the "
            "remainder is %d\n\n", z.quot, z.rem);
    x = 7;
    y = 7;
    printf("For div(%d, %d)\n", x, y);
    z = div(x, y);
    printf("The quotient is %d and the "
            "remainder is %d\n\n", z.quot, z.rem);
    x = 7;
    y = 0;
    printf("For div(%d, %d)\n", x, y);
    z = div(x, y);
    printf("The quotient is %d and the "
            "remainder is %d\n\n", z.quot, z.rem);
}

Output:
For div(7, 3)
The quotient is 2 and the remainder is 1
For div(7, -3)
The quotient is -2 and the remainder is 1
For div(-5, 3)
The quotient is -1 and the remainder is -2
For div(7, 7)
The quotient is 1 and the remainder is 0
For div(7, 0)
Illegal instruction executed
ABRT

void exit ( int status)

Description: Terminates program after clean up.

Include: <stdlib.h>

Parameters

status exit status

Remarks:
exit calls any functions registered by atexit in reverse order of registration, flushes buffers, closes stream, closes any temporary files created with tmpfile, and resets the processor. This function is customizable. See pic30-libs.

Example:

#include <stdio.h> // for fopen, printf, 
// FILE, NULL 
#include <stdlib.h> // for exit 
int main(void) {
    FILE *myfile;
    if ((myfile = fopen("samp.fil", "r")) == NULL) {
        printf("Cannot open samp.fil\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Success opening samp.fil\n");
        exit(EXIT_SUCCESS);
    }
    printf("This will not be printed");
}

Output:
Cannot open samp.fil

void free ( void * ptr)

Description: Frees memory.

Include: <stdlib.h>

Parameters

ptr	points to memory to be freed

Remarks:
Frees memory previously allocated with calloc, malloc, or realloc. If free is used on space that has already been deallocated (by a previous call to free or by realloc) or on space not allocated with calloc, malloc, or realloc, the behavior is undefined.

Example:

#include <stdio.h> // for printf, sizeof, 
// NULL 
#include <stdlib.h> // for malloc, free 
int main(void) {
    long *i;
    if ((i = (long *) malloc(50 * sizeof (long))) ==
            NULL)
        printf("Cannot allocate memory\n");
    else {
        printf("Memory allocated\n");
        free(i);
        printf("Memory freed\n");
    }
}

Output:
Memory allocated
Memory freed

char* getenv ( const char * name)

Description: Get a value for an environment variable.

Include: <stdlib.h>

Parameters

name	name of environment variable

Returns: Returns a pointer to the value of the environment variable if successful; otherwise, returns a null pointer.

Remarks:
This function must be customized to be used as described (see pic30-libs). By default there are no entries in the environment list for getenv to find.

Example:

#include <stdio.h> // for printf, NULL 
#include <stdlib.h> // for getenv 
int main(void) {
    char *incvar;
    incvar = getenv("INCLUDE");
    if (incvar != NULL)
        printf("INCLUDE environment variable = %s\n",
            incvar);
    else
        printf("Cannot find environment variable "
            "INCLUDE ");
}

Output:
Cannot find environment variable INCLUDE

long labs ( long i)

Description: Calculates the absolute value of a long integer.

Include: <stdlib.h>

Parameters

i	long integer value

Returns: Returns the absolute value of i.

Remarks:
A negative number is returned as positive; a positive number is unchanged.

Example:

#include <stdio.h> // for printf 
#include <stdlib.h> // for labs 
int main(void) {
    long i;
    i = 123456;
    printf("The absolute value of %7ld is %6ld\n",
            i, labs(i));
    i = -246834;
    printf("The absolute value of %7ld is %6ld\n",
            i, labs(i));
    i = 0;
    printf("The absolute value of %7ld is %6ld\n",
            i, labs(i));
}

Output:
The absolute value of 123456 is 123456
The absolute value of -246834 is 246834
The absolute value of 0 is 0

ldiv_t ldiv	(	long	numer,
		long	denom
	)

Description: Calculates the quotient and remainder of two long integers.

Include: <stdlib.h>

Parameters

numer	numerator
denom	denominator

Returns: Returns the quotient and the remainder.

Remarks:
The returned quotient will have the same sign as the numerator divided by the denominator. The sign for the remainder will be such that the quotient times the denominator plus the remainder will equal the numerator (quot * denom + rem = numer). If the denominator is zero, the behavior is undefined.

Example:

#include <stdlib.h> // for ldiv, ldiv_t 
#include <stdio.h> // for printf 
int main(void) {
    long x, y;
    ldiv_t z;
    x = 7;
    y = 3;
    printf("For ldiv(%ld, %ld)\n", x, y);
    z = ldiv(x, y);
    printf("The quotient is %ld and the "
            "remainder is %ld\n\n", z.quot, z.rem);
    x = 7;
    y = -3;
    printf("For ldiv(%ld, %ld)\n", x, y);
    z = ldiv(x, y);
    printf("The quotient is %ld and the "
            "remainder is %ld\n\n", z.quot, z.rem);
    x = -5;
    y = 3;
    printf("For ldiv(%ld, %ld)\n", x, y);
    z = ldiv(x, y);
    printf("The quotient is %ld and the "
            "remainder is %ld\n\n", z.quot, z.rem);
    x = 7;
    y = 7;
    printf("For ldiv(%ld, %ld)\n", x, y);
    z = ldiv(x, y);
    printf("The quotient is %ld and the "
            "remainder is %ld\n\n", z.quot, z.rem);
    x = 7;
    y = 0;
    printf("For ldiv(%ld, %ld)\n", x, y);
    z = ldiv(x, y);
    printf("The quotient is %ld and the "
            "remainder is %ld\n\n",
            z.quot, z.rem);
}

Output:
For ldiv(7, 3)
The quotient is 2 and the remainder is 1
For ldiv(7, -3)
The quotient is -2 and the remainder is 1
For ldiv(-5, 3)
The quotient is -1 and the remainder is -2
For ldiv(7, 7)
The quotient is 1 and the remainder is 0
For ldiv(7, 0)
The quotient is -1 and the remainder is 7

Explanation:
In the last example (ldiv(7,0)) the denominator is zero, the behavior is undefined.

void* malloc ( size_t size)

Description: Allocates memory.

Include: <stdlib.h>

Parameters

size	number of characters to allocate

Returns: Returns a pointer to the allocated space if successful; otherwise, returns a null pointer.

Remarks:
malloc does not initialize memory it returns.

Example:

#include <stdio.h> // for printf, sizeof, 
// NULL 
#include <stdlib.h> // for malloc, free 
int main(void) {
    long *i;
    if ((i = (long *) malloc(50 * sizeof (long))) ==
            NULL)
        printf("Cannot allocate memory\n");
    else {
        printf("Memory allocated\n");
        free(i);
        printf("Memory freed\n");
    }
}

Output:
Memory allocated
Memory freed

int mblen	(	const char *	s,
		size_t	n
	)

Description: Gets the length of a multibyte character. (See Remarks.)

Include: <stdlib.h>

Parameters

s	points to the multibyte character
n	number of bytes to check

Returns: Returns zero if s points to a null character; otherwise, returns 1.

Remarks:
The 16-bit compiler does not support multibyte characters with length greater than 1 byte.

Variable Documentation

int mbtowc * pwc

Description: Converts a multibyte character to a wide character. (See Remarks.)

Include: <stdlib.h>

Parameters

pwc	points to the wide character
s	points to the multibyte character
n	number of bytes to check

Returns: Returns zero if s points to a null character; otherwise, returns 1.

Remarks:
The resulting wide character will be stored at pwc. The 16-bit compiler does not support multibyte characters with length greater than 1 byte.

size_t mbstowcs * wcs

Description: Converts a multibyte string to a wide character string. (See Remarks.)

Include: <stdlib.h>

Parameters

wcs	points to the wide character string
s	points to the multibyte string
n	the number of wide characters to convert.

Returns: Returns the number of wide characters stored excluding the null character.

Remarks:
mbstowcs converts n number of wide characters unless it encounters a null wide character first. The 16-bit compiler does not support multibyte characters with length greater than 1 byte.

Data Structures

Macros

Functions

Variables

Detailed Description

Description

Software License Agreement

Macro Definition Documentation

Function Documentation

Variable Documentation