Netcruzer  V2.02
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
stdlib.h File Reference

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

Go to the source code of this file.

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
iinteger 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
funcfunction 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
spointer 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
sstring 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
sstring 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
keyobject to search for
basepointer to the start of the search data
nelemnumber of elements
sizesize of elements
cmppointer to the comparison function
ckpointer to the key for the search
cepointer 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
nelemnumber of elements
sizelength 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
numernumerator
denomdenominator
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
statusexit 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");
} else {
printf("Success opening samp.fil\n");
}
printf("This will not be printed");
}

Output:
Cannot open samp.fil

void free ( void *  ptr)

Description: Frees memory.

Include: <stdlib.h>

Parameters
ptrpoints 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))) ==
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
namename 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
ilong 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
numernumerator
denomdenominator
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
sizenumber 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))) ==
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
spoints to the multibyte character
nnumber 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
pwcpoints to the wide character
spoints to the multibyte character
nnumber 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
wcspoints to the wide character string
spoints to the multibyte string
nthe 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.