/** @file ../include/stdlib.h

@internalComponent

*/

/** @fn  abort(void)

@return   The abort function

never returns.

  The abort function causes abnormal program termination to occur, unless the

signal SIGABRT is being caught and the signal handler does not return.

 Any open streams are flushed and closed.

Examples:

@code

#include  <stdio.h>

#include  <stdlib.h>

int main( void )

{

   FILE *stream;

   if( (stream = fopen( "notexist.file", "r" )) == NULL )

   {

      perror( "Error occurred while opening file" );

      abort();

   }

   else

      fclose( stream );

   return 0;

}

@endcode

 Output

@code

Error occurred while opening file: No such file or directory

@endcode

Implementation notes: 

  The abort function is thread-safe. It is unknown whether it is async-cancel-safe.

Limitations:

The signal related functionalities are not applicable to the Symbian OS implementation

as there is no support for signals from Symbian OS.

@see exit()

@publishedAll

@externallyDefinedApi

*/

/** @fn  abs(int j)

@param j

@return   The abs function

returns

the absolute value.

  The abs function computes the absolute value of an integer j. The absolute value is always postive, it has size but not direction.

Examples:

@code

#include  <stdio.h>

#include  <stdlib.h>

int main( void )

{

   int    ix = -4, iy;

   long   lx = -41567L, ly;

   long long llx = -5343546758, lly;

   iy = abs( ix );

   printf( "The absolute value of %d is %d

", ix, iy);

   ly = labs( lx );

   printf( "The absolute value of %ld is %ld

", lx, ly);

   lly = llabs( llx );

   printf( "The absolute value of %lld is %lld

", llx, lly );

   return 0;

}

@endcode

@code

Output

The absolute value of -4 is 4

The absolute value of -41567 is 41567

The absolute value of -5343546758 is 5343546758

@endcode

@see fabs()

@see floor()

@see hypot()

@see labs()

@see llabs()

@see math()

@publishedAll

@externallyDefinedApi

*/

/** @fn  atexit(void(*)(void) func)

@param func

@return   The atexit function returns the value 0 if successful; otherwise it returns 

the value -1 and sets the global variable errno to indicate the error.

  The atexit function

registers the given function to be called at program exit, whether via exit or via return from the program's main. Functions so registered are called in reverse order;

no arguments are passed.

 These functions must not call exit . If it is necessary to terminate the process while in such a 

  function, the _exit function should be used. Alternatively, 

  the function may cause abnormal process termination, for example by calling abort

 At least 32 functions can always be registered and more are allowed as long 

  as sufficient memory can be allocated.

In Symbian app with an entry point E32Main, the registered functions will not be called unless exit() is specified explicitly.

Limitation:

atexit() is not supported on emulator.

Examples:

@code

#include <stdlib.h>

#include <stdio.h>

void fun1( void ), fun2( void ), fun3( void ), fun4( void );

int main( void )

{

   atexit( fun1 );

   atexit( fun2 );

   atexit( fun3 );

   atexit( fun4 );

   printf( "Before exiting...." );

}

void fun1()

{

   printf( " fun1 " );

}

void fun2()

{

   printf( " fun2" );

}

void fun3()

{

   printf( " fun3 " );

}

void fun4()

{

   printf( " fun4 " );

}

@endcode

@code

Output

Before exiting...

fun4

fun3

fun2

fun1

@endcode

@code

#include <stdlib.h>

#include <stdio.h>

#include <e32base.h>

void fun1(void),fun2(void),fun3(void);

LOCAL_C int MainL()

	{

	atexit( fun1 );

   	atexit( fun2 );

   	atexit( fun3 );

    	printf( "Before exiting....\n" );

  	getchar();

	exit();

	}

void fun1()

{

printf( " fun1\n " );

getchar();

}

void fun2()

{

printf( " fun2\n " );

getchar();

}

void fun3()

{

printf( " fun3\n " );

getchar();

}

GLDEF_C TInt E32Main()

	{

	__UHEAP_MARK;

	CTrapCleanup* cleanup = CTrapCleanup::New();

	if(cleanup == NULL)

		{

		return KErrNoMemory;

		}

	TInt ret;

	TRAPD(err,ret = MainL());

	delete cleanup;

	__UHEAP_MARKEND;

	return KErrNone;

   	}

@encode

@code

Output

Before exiting...

fun3

fun2

fun1

@endcode

@see exit()

@publishedAll

@externallyDefinedApi

*/

/** @fn  atof(const char *nptr)

@param nptr

@return   The atof function

returns

the converted value if the value can be represented.

  The atof function converts the initial portion of the string pointed to by nptr to double

representation.

@code

 It is equivalent to: strtod(nptr, (char **)NULL);

The decimal point

character is defined in the program's locale (category LC_NUMERIC).

@endcode

Examples:

@code

#include <stdlib.h>

#include <stdio.h>

void main( void )

{

 /* Test of atof */

 double d = atof("  86778E-2");

 printf( "result of atof: %f

", d );

}

@endcode

@code

Output

result of atof: 867.78

@endcode

Implementation notes:

The atof function is not thread-safe and also not async-cancel-safe. The atof function has been deprecated. Use strtod instead.

@see atoi()

@see atol()

@see strtod()

@see strtol()

@see strtoul()

@publishedAll

@externallyDefinedApi

*/

/** @fn  atoi(const char *nptr)

@param nptr

@return   The atoi function

returns

the converted value if the value can be represented.

  The atoi function converts the initial portion of the string pointed to by nptr to int

representation.

@code

 It is equivalent to: (int)strtol(nptr, (char **)NULL, 10);

@endocde

Examples:

@code

#include <stdlib.h>

#include <stdio.h>

void main( void )

{

  /* call to atoi */

  char *str = "  -56957jdhfjk";    

  int i = atoi( str );

  printf( "result of atoi: %d

", i );

}

@endcode

@code

Output

result of atoi: -56957

@endcode

Implementation notes:

The atoi function is not thread-safe and also not async-cancel safe. The atoi function has been deprecated. Use strtol instead.

@see atof()

@see atol()

@see strtod()

@see strtol()

@see strtoul()

@publishedAll

@externallyDefinedApi

*/

/** @fn  atol(const char *nptr)

@param nptr

Note: 

This description also covers the following functions -

 atoll() 

@return   The atol and atoll functions

return

the converted value if the value can be represented.

  The atol function converts the initial portion of the string pointed to by nptr to long

integer

representation.

 It is equivalent to:

@code

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

@endcode

The atoll function converts the initial portion of the string pointed to by nptr to long long

integer representation. It is equivalent to:    

@code

    strtoll(nptr, (char **)NULL, 10);

@endcode

Examples:

@code

#include <stdlib.h>

#include <stdio.h>

void main( void )

{

 /* call to atol */

 long l = atol( "-000002344" );

 printf( "result of atol: %ld

", l );

}

@endcode

@code

Output

result of atol: -2344

@endcode

@code

#include <stdlib.h>

#include <stdio.h>

void main( void )

{

 /* call to atoll */

 long long l = atoll("454756356bs");

 printf( "result of atoll: %ld

", l );

}

@endcode

@code

Output

result of atoll: 454756356

@endcode

@see atof()

@see atoi()

@see strtod()

@see strtol()

@see strtoul()

@publishedAll

@externallyDefinedApi

*/

/** @fn  bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (*compar) (const void *, const void *))

@param key

@param base

@param nmemb

@param size

@param compar

@return   The bsearch function returns a pointer to a matching member of the array, 

or a null pointer if no match is found. If two or more matching members are found 

the result is unspecified.

  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. It 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.

Examples:

@code

#include<stdlib.h>

#include<stdio.h>

int search_function(const void* a,const void* b)

{

    return(*(int *)a - *(int *)b);

}

int main()

{

int arr[] = {3,5,7,8,10};

int key = 7;

int i = 5;

int *ele;

ele  = ( int* ) bsearch(&key;, (void *)arr, i, sizeof(arr[0]), search_function);

if (ele != NULL)

        printf("

element found: %d", *ele);

else

        printf("

element not found");

return 0;

}

@endcode

@code

Output

element found: 7

@endcode

@see qsort()

@publishedAll

@externallyDefinedApi

*/

/** @fn  calloc(size_t number, size_t size)

@param number

@param size

Refer to  malloc() for the documentation

@see brk()

@see mmap()

@see getpagesize()

@publishedAll

@externallyDefinedApi

*/

/** @fn  div(int num, int denom)

@param num

@param denom

@return   The div function

returns a structure of type div_t that contains two int

members named quot (quotient)

and rem (remainder).

  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.

Examples:

@code

#include <stdlib.h>

#include <stdio.h>

void main( void )

{

 int numer = -14;

 int denom = -3;

 int exp_numer = 0;

 /* call to div */

 div_t x = div(numer, denom);

 printf("Result->

 Quotient = %d

 Remainder = %d

", x.quot, x.rem);

 exp_numer = (denom * x.quot) + x.rem;

 if( exp_numer == (numer) )

    printf("Result is same as the expected output");  

 else

    printf("Unexpected output");

 return 0; 

}

@endcode

@code

Output

Result->

Quotient = 4

Remainder = -2

Result is same as the expected output

@endcode

@see ldiv()

@see lldiv()

@publishedAll

@externallyDefinedApi

*/

/** @fn  exit(int status)

@param status

Note: 

This description also covers the following functions -

 _Exit() 

@return   The exit and _Exit functions

never return.

 The  exit and  _Exit functions terminate a process.

Before termination, exit performs the following functions in the order listed:

@code

   1. Call the functions registered with the atexit function, in the reverse order of their registration.

   2. Flush all open output streams.

   3. Close all open streams.

   4. Unlink all files created with the tmpfile function. 

@endcode

The _Exit function terminates without calling the functions registered with the atexit function, and may or may not perform the other actions listed. 

Both functions make the low-order eight bits of the status argument available to a parent process which has called a wait function.

The C Standard (-isoC-99) defines the values 0, EXIT_SUCCESS, and EXIT_FAILURE as possible values of status. 

Cooperating processes may use other values.

Note that exit does nothing to prevent bottomless recursion should a function registered using atexit itself call exit. 

Such functions must call _Exit instead (although this has other effects as well which may not be desired).

Examples:

@code

/* Detailed description : Sample usage of exit system call. */

#include <stdlib.h>

void main()

{

  exit(0) ; //Here 0 is exit status of the process

}

@endcode

@see _exit()

@see wait()

@see atexit()

@see tmpfile()

@publishedAll

@externallyDefinedApi

*/

/** @fn  free(void *p)

@param p

Refer to  malloc() for the documentation

@see brk()

@see mmap()

@see getpagesize()

@publishedAll

@externallyDefinedApi

*/

/** @fn  getenv(const char *name)

@param name

Note: 

This description also covers the following functions -

 setenv()  putenv()  unsetenv() 

@return   The getenv function returns the value of the environment variable as a NULL -terminated string. If the variable name is not in the current environment, NULL is returned. The setenv and putenv functions return the value 0 if successful; otherwise they 

  return the value -1 and set the global variable errno is set to indicate the error. The unsetenv function never returns.

These functions set, unset and fetch environment variables from the

host environment list.

For compatibility with differing environment conventions,

the given arguments name and value may be appended and prepended,

respectively,

with an equal sign "="

 The getenv function obtains the current value of the environment variable name.

 The setenv function inserts or resets the environment variable name in the current environment list.

If the variable name does not exist in the list,

it is inserted with the given value. If the variable does exist, the argument overwrite is tested; if overwrite is

zero, the

variable is not reset, otherwise it is reset

to the given value.

 The putenv function takes an argument of the form "name=value" and is

equivalent to: setenv(name, value, 1);

 The unsetenv function

deletes all instances of the variable name pointed to by name from the list.

Examples:

@code

#include <stdlib.h> //getenv

#include <stdio.h> //printf

int main( void )

{

  int iret = putenv("PATH=c:\sys\bin;");

  if( iret == -1)

     printf( "putenv() failed!!

" );

   /* fetch new value. */

  char *psc = getenv("PATH");

  if( psc != NULL )

      printf( "new PATH variable is: %s

", psc );

  return 0;

}

@endcode

@code

Output

new PATH variable is: c:\sys\bin;

@endcode

@code

#include <stdlib.h> //setenv, getenv

#include <stdio.h> //printf

int main( void )

{

   char *var;

   /* Unset the value of the HOME environment variable

    * to make sure that it is non-existing.

    */

   unsetenv( "HOME" );

   /* Set the value of HOME environment with no overwrite option */

   int iret = setenv("HOME", "/home", 0);

   if(iret == -1)

      printf( "Setenv failed!!" );

   /* Get new value. */

   var = getenv( "HOME" );

   if( var != NULL )

      printf( "new HOME variable is: %s

", var );

   /* Set the value of HOME environment with the overwrite option */

   iret = setenv("HOME", "/check", 1);

   /* Get new value. */

   var = getenv( "HOME" );

   if( var != NULL )

      printf( "new HOME variable is: %s

", var );

   return 0;

}

@endcode

@code

Output

new HOME variable is: \home

new HOME variable is: \check

@endcode

@publishedAll

@externallyDefinedApi

*/

/** @fn  labs(long j)

@param j

@return   The labs() function shall return the absolute value of the long integer operand.

 The labs function

returns the absolute value of the long integer j.

Examples:

@code

#include  <stdio.h>

#include  <stdlib.h>

int main( void )

{

   int    ix = -4, iy;

   long   lx = -41567L, ly;

   long long llx = -5343546758, lly;

   iy = abs( ix );

   printf( "The abs value of %d is %d

", ix, iy);

   ly = labs( lx );

   printf( "The abs value of %ld is %ld

", lx, ly);

   lly = llabs( llx );

   printf( "The abs value of %lld is %lld

", llx, lly );

   return 0;

}

@endcode

@code

Output

The absolute value of -4 is 4

The absolute value of -41567 is 41567

The absolute value of -5343546758 is 5343546758

@endcode

@see abs()

@see floor()

@see llabs()

@see math()

@publishedAll

@externallyDefinedApi

*/

/** @fn  ldiv(long num, long denom)

@param num

@param denom

@return   The ldiv function

returns a structure of type ldiv_t that contains two long

members named quot (quotient)

and rem (remainder).

  The ldiv function

computes the value num / denom and returns the quotient and remainder in a structure named ldiv_t

that contains two long

members named quot and rem.

Examples:

@code

#include <stdlib.h>

#include <stdio.h>

int main( void )

{

 long numer = 13;

 long denom = -3;

 /* call to ldiv */

 ldiv_t x = ldiv(numer, denom);

 printf("Result-> 

Quotient = %ld 

Remainder = %ld", x.quot, x.rem);

 long exp_numer = (denom * x.quot) + x.rem;

 if( exp_numer == (numer) )

    printf("

Result is same as the expected output");  

 else

    printf("

Unexpected output");

 return 0;

}

@endcode

@code

Output

Result->

Quotient = 4

Remainder = -1

Result is same as the expected output

@endcode

@see div()

@see lldiv()

@publishedAll

@externallyDefinedApi

*/

/** @fn  malloc(size_t nbytes)

@param nbytes

Note: 

This description also covers the following functions -

 calloc()  realloc()  reallocf()  free() 

@return   The malloc and calloc functions return a pointer to the allocated memory if successful; otherwise

a NULL pointer is returned and errno is set to ENOMEM. The realloc and reallocf functions return a pointer, possibly identical to ptr, to the allocated memory if successful; otherwise a NULL pointer is returned and errno is set to ENOMEM if the error was the result of an allocation failure. The realloc function always leaves the original buffer intact when an 

  error occurs, whereas reallocf deallocates it in this case. The free function returns no value.

  The malloc function allocates nbytes of memory. The allocated space is suitably aligned (after possible 

pointer coercion) for storage of any type of object. If the space is at least pagesize bytes in length (see getpagesize ) the returned memory will be 

page boundary aligned as well. If malloc fails a NULL pointer is returned.

 Note that malloc does NOT normally initialize the returned memory to zero bytes.

 The calloc function allocates space for number of objects, each nbytes in length. The result is identical to calling malloc with an argument of "number * nbytes", with the exception that the allocated memory is explicitly 

  initialized to zero bytes.

 The realloc function changes the size of the previously allocated memory 

  referenced by ptr to nbytes. The contents of the memory are unchanged up to the lesser 

  of the new and old sizes. If the new size is larger, the value of the newly 

  allocated portion of the memory is undefined. If the requested memory cannot 

  be allocated, NULL is returned and the memory referenced by ptr is valid and unchanged. If memory can be allocated, the memory referenced 

  by ptr is freed and a pointer to the newly allocated memory is returned. 

  Note that realloc and reallocf may move the memory allocation resulting in a different return 

  value from ptr. If ptr is NULL, the realloc function behaves identically to malloc for the specified nbytes.

 The reallocf function is identical to the realloc function, except that it

will free the passed pointer when the requested memory cannot be allocated.

This is a specific API designed to ease the problems with traditional coding styles

for realloc causing memory leaks in libraries.

 The free function causes the allocated memory referenced by ptr to be made available for future allocations.

If ptr is NULL, no action occurs.

Examples:

@code

#include <stdlib.h>    //malloc

#include <stdio.h>    //printf

int main( void )

{

   /* allocate memory */

   char  *pc = (char *)malloc( sizeof(char) * 3);

   if( pc == NULL )

      printf( "memory insufficient

" );

   else

   {

      printf( "memory allocated

" );

      free( pc );

      printf( "memory freed

" );

   }

   return 0;

}

@endcode

@code

Output

memory allocated

memory freed

@endcode

@code

#include <stdio.h> //printf

#include <stdlib.h> //calloc

int main( void )

{

   int  *pint = (int *)calloc(2, sizeof (int) * 2);

   if( pint != NULL )

      printf( "allocated 2 blocks of memory, each of size -

               twice the size of an integer

" );

   else

      printf( "can't allocate memory

" );

   free( pint );

   return 0;

}

@endcode

@code

Output

allocated 2 blocks of memory, each of size - 2 integers

@endcode

@code

#include <stdio.h> //printf

#include <stdlib.h> //realloc

int main( void )

{

 int  *pint = (int *)calloc(2, sizeof (int) * 2);

 if (pint == NULL)

  {

  printf("calloc failed to allocate memory

");

  return -1;

  }

 else

  {

  printf("calloc allocated memory: 128 bytes

");

  }

 pint = (int *)realloc(pint, (sizeof (int) * 6) );

 if (pint == NULL)

  {

  printf("realloc failed to allocate memory