/** @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

 ");

   return -1;

   }

  else

   {

   printf("realloc allocated memory: 192 bytes

 ");

   }

   free( pint );

   return 0;

 }

 @endcode

 @code

 Output

 calloc allocated memory: 128 bytes

 realloc allocated memory: 192 bytes

 @endcode

 @see brk()

 @see mmap()

 @see getpagesize()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  mblen(const char *s, size_t n)

 @param s

 @param n

 @return   If s is a null pointer, mblen returns non-zero 0 value depending upon the current locale (see 

   below). If s is not a null pointer, mblen returns : 0 (if mbchar points to the null byte), the number of bytes that constitute the character (if the next n or fewer bytes form a valid character), or -1 (if they do not form a valid character) and may set errno to indicate the error. In no case is the value returned greater than n or the value of the {MB_CUR_MAX} macro.

   The mblen function computes the length in bytes

 of a multibyte character s according to the current conversion state.

 Up to n bytes are examined.

  A call with a null s pointer returns nonzero if the current locale requires shift states,

 zero otherwise;

 if shift states are required, the shift state is reset to the initial state.

  The behavior of the mblen is affected by LC_CTYPE category of the current locale.

 Examples:

 @code

 #include <stdlib.h>

 #include <wchar.h>

 /* Illustrates how to use mblen API */

 int example_mblen(wchar_t wc)

 {

  int len;

  /* determine the number bytes in the multibyte char */

  len = mblen(wc, MB_CUR_MAX);

  if(len == -1)

  {

         wprintf(L"mblen returned error!!

 ");

  }

  /* return the no of bytes */

  return(len);

 }

 @endcode

 Limitations:   

 The current implementation of mblen is not affected by the LC_CTYPE category of the current locale.

 It works only for UTF8 character set.

 @see mbrlen()

 @see mbtowc()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  mbstowcs(wchar_t *  pwcs, const char *  s, size_t n)

 @param pwcs

 @param s

 @param n

 @return   The mbstowcs function returns the number of wide characters converted,

 not counting any terminating null wide character, or -1

 if an invalid multibyte character was encountered.

   The mbstowcs function converts a multibyte character string mbstring beginning in the initial conversion state

 into a wide character string wcstring. No more than n wide characters are stored.

 A terminating null wide character is appended if there is room.

  The behavior of the mbstowcs is affected by LC_CTYPE category of the current locale.

 Examples:

 @code

 #include <stdio.h>

 #include <stdlib.h>

 #include <wchar.h>

 /* Illustrates how to use mbstowcs API */

 size_t example_mbstowcs(wchar_t *wc, char *s, size_t n)

 {

  size_t len;

  /* converting multibyte string to a wide-char string */

  len = mbstowcs(wc, s, n);

  /* checking for error */

  if(len < 0)

  {

         wprintf(L"mbstowcs returned error!!

 ");

  }

  /* returning no of bytes consumed */

  return (len);

 }

 @endcode

 Limitations:   

 The current implementation of mbstowcs is not affected by the LC_CTYPE category of the current locale.

 It works only for UTF8 character set.

 @see mbsrtowcs()

 @see mbtowc()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  mbtowc(wchar_t * pwc, const char *  s, size_t n)

 @param pwc

 @param s

 @param n

 @return   If mbchar is NULL, the mbtowc function returns nonzero if shift states are supported,

 zero otherwise. Otherwise, if mbchar is not a null pointer, mbtowc either returns 0 if mbchar represents the null wide character, or returns

 the number of bytes processed in mbchar, or returns -1 if no multibyte character

 could be recognized or converted.

 In this case, mbtowc internal conversion state is undefined.

   The mbtowc function converts a multibyte character mbchar into a wide character according to the current conversion state,

 and stores the result in the object pointed to by wcharp. Up to n bytes are examined.

  A call with a null mbchar pointer returns nonzero if the current encoding requires shift 

   states, zero otherwise. If shift states are required the shift state is reset 

   to the initial state.

  The behavior of the mbtowc is affected by LC_CTYPE category of the current locale.

 Examples:

 @code

 #include <stdlib.h>

 #include <wchar.h>

 /* Illustrates how to use mbtowc API */

 int example_mbtowc(wchar_t *wc, char *s)

 {

  int len;

  /* converting multibyte sequence to a wide-character */

  len = mbtowc(wc, s, MB_CUR_MAX);

  /* checking for error */

  if(len < 0)

  {

         wprintf(L"mbtowc returned error!!

 ");

  }

  /* returning no of bytes consumed */

  return (len;);

 }

 @endcode

 Limitations:

 The current implementation of mbtowc is not affected by the LC_CTYPE category of the current locale.

 It works only for UTF8 character set.

 @see btowc()

 @see mblen()

 @see mbrtowc()

 @see mbstowcs()

 @see wctomb()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  qsort(void *, size_t, size_t, int(*)(const void *, const void *))

 @return   The qsort function

 returns no value.

   The qsort function is a modified partition-exchange sort, or quicksort.

  The qsort function sorts an array of nmemb objects, the initial member of which is pointed to by base. The size of each object is specified by size.

  The contents of the array base are sorted in ascending order according to

 a comparison function pointed to by compar, which requires two arguments pointing to the objects being

 compared.

  The comparison function must return an integer less than, equal to, or

 greater than zero if the first argument is considered to be respectively

 less than, equal to, or greater than the second.

  The algorithm implemented by qsort is not stable, that is, if two members compare as equal, their order in

 the sorted array is undefined.

  The qsort function is an implementation of C.A.R.

 Hoare's "quicksort"

 algorithm,

 a variant of partition-exchange sorting; in particular, see D.E. Knuth Ns's Algorithm Q . Quicksort takes O N lg N average time.

 @code

 This implementation uses median selection to avoid its O N**2 worst-case behavior.

 @endcode

 Examples:

 @code

 #include <stdio.h>

 #include <stdlib.h>

 int sort_function( const void *a, const void *b);

 int main(void)

 {

    int  x;

    int list[5] = {4,2,3,5,1};

    qsort((void *)list, 5, sizeof(list[0]), sort_function);

    for (x = 0; x < 5; x++)

    printf("%d

 ", list[x]);

    return 0;

 }

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

 {

  int *p1 = (int *)a;

  int val1 = *p1;

  int *p2 = (int *)b;

  int val2 = *p2;

  int x = -1;

  if(val1  > val2 )

    x=1;

  if(val1  == val2 )

    x=0; 

  return x;

 }

 @endcode

 @code

 Output

 1

 2

 3

 4

 5

 @endcode

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  rand(void)

 Refer to  srand() for the documentation

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  realloc(void *p, size_t nbytes)

 @param p

 @param nbytes

 Refer to  malloc() for the documentation

 @see brk()

 @see mmap()

 @see getpagesize()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  srand(unsigned seed)

 @param seed

 Note: 

 This description also covers the following functions -

  rand() 

 @return   The rand function

 never returns return the next pseudo-random number in the sequence. The srand function never returns.

   The rand function computes a sequence of pseudo-random integers in the range

 of 0 to RAND_MAX (as defined by the header file \#include \<stdlib.h\> ).

  The srand function sets its argument seed as the seed for a new sequence of

 pseudo-random numbers to be returned by rand. These sequences are repeatable by calling srand with the same seed value.

  If no seed value is provided, the functions are automatically

 seeded with a value of 1.

 Examples:

 @code

 #include <stdlib.h>

 #include <stdio.h>

 int main( void )

 {

   int randArray[20];

   int i=0;

   while(i<20)

   {

         randArray[i]=rand();

         printf("

 %d", randArray[i]);

         i++;

   }

   return 0;

 }

 @endcode

 @code

 Output

 16807

 282475249

 1622650073

 984943658

 1144108930

 470211272

 101027544

 1457850878

 1458777923

 2007237709

 823564440

 1115438165

 1784484492

 74243042

 114807987

 1137522503

 1441282327

 16531729

 823378840

 143542612

 @endcode

 @code

 #include <stdlib.h>

 #include <stdio.h>

 int main( void )

 {

  int seedVal = 45454652;

  int randVal;

  srand(seedVal);

  randVal=rand();

  printf("Random Value returned is %d"), randVal);

 }

 @endcode

 @code

 Output

 Random Value returned is 1599641479

 @endcode

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  strtod(const char *  s, char **  tail)

 @param s

 @param tail

 Note: 

 This description also covers the following functions -

  strtof()  strtold() 

 @return   The strtod , strtof ,

 and strtold functions return the converted value, if any. If endptr is not NULL ,

 a pointer to the character after the last character used

 in the conversion is stored in the location referenced by endptr . If no conversion is performed, zero is returned and the value of nptr is stored in the location referenced by endptr . If the correct value would cause overflow, plus or minus HUGE_VAL , HUGE_VALF , or HUGE_VALL is returned (according to the sign and type of the return 

   value), and ERANGE is stored in errno . If the correct value would cause underflow a value, of the appropriate 

   type, with magnitude is no greater than the smallest normalized positive number 

   (KMinTReal in case of Symbian OS) is returned and ERANGE is stored in errno .

   These conversion functions convert the initial portion of the string pointed to by  nptr to double , float , and long double representation, respectively.

 The expected form of the string is an optional plus ("+") or minus sign ("-") followed by either:

 @code

     * a decimal significand consisting of a sequence of decimal digits optionally containing a decimal-point character, or

     * a hexadecimal significand consisting of a "0X" or "0x" followed by a sequence of hexadecimal digits optionally containing a decimal-point character. 

 @endcode

 In both cases, the significand may be optionally followed by an exponent. An exponent consists of an "E" or "e" (for decimal constants) or a "P" or 

 "p" (for hexadecimal constants), followed by an optional plus or minus sign, followed by a sequence of decimal digits. 

 For decimal constants, the exponent indicates the power of 10 by which the significand should be scaled. For hexadecimal constants, the scaling is instead done by powers of 2.

 Alternatively, if the portion of the string following the optional plus or minus sign begins with "INFINITY" or "NAN", ignoring case, it is interpreted as an infinity or a quiet NaN, respectively.

 In any of the above cases, leading white-space characters in the string (as defined by the isspace function) are skipped. The decimal point character is defined in the program's locale (category LC_NUMERIC).

 Examples:

 @code

 #include <stdlib.h>

 #include <stdio.h>

 int main( void )

 {

  char *endpt = NULL;

  double d = 0.0;

  d = strtod("0x00e123bhduitri", &endpt;);

  printf("{Expected: 922171.0} %f

 ", d);

  printf("{Expected: \"hduitri\"} %s

 ", endpt);

  return 0;

 }

 @endcode

  Output

 @code

 {Expected: 922171.0} 922171.0

 {Expected: "hduitri"} hduitri

 @endcode

 Limitations:

 All these functions don't support the long double length modifiers.

 @see atof()

 @see atoi()

 @see atol()

 @see strtol()

 @see strtoul()

 @see wcstod()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  strtof(const char *  s, char **  tail)

 @param s

 @param tail

 Refer to  strtod() for the documentation

 @see atof()

 @see atoi()

 @see atol()

 @see strtol()

 @see strtoul()

 @see wcstod()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  strtol(const char *  nptr, char **  endptr, int base)

 @param nptr

 @param endptr

 @param base

 Note: 

 This description also covers the following functions -

  strtoll()  strtoimax()  strtoq() 

 @return   The strtol , strtoll , strtoimax and strtoq functions return the result of the conversion, unless the value 

   would underflow or overflow. If no conversion could be performed, 0 is returned 

   and the global variable errno is set to EINVAL (the last feature is not portable across all platforms). If 

   an overflow or underflow occurs, errno is set to ERANGE and the function return value is clamped according to the following 

   table:

  @code

   Function	underflow	overflow 

   strtol        LONG_MIN	LONG_MAX 

   strtoll	LLONG_MIN	LLONG_MAX 

   strtoimax	INTMAX_MIN	INTMAX_MAX 

   strtoq	LLONG_MIN	LLONG_MAX

 @endcode

   The strtol function

 converts the string in nptr to a long

 value.

 The strtoll function

 converts the string in nptr to a long long

 value.

 The strtoimax function

 converts the string in nptr to an intmax_t

 value.

 The strtoq function

 converts the string in nptr to a quad_t

 value.

 The conversion is done according to the given base ,

 which must be between 2 and 36 inclusive,

 or be the special value 0.

  The string may begin with an arbitrary amount of white space

 (as determined by isspace )

 followed by a single optional "+"

 or "-"

 sign.

 If base is zero or 16,

 the string may then include a "0x"

 prefix,

 and the number will be read in base 16; otherwise, a zero base is taken as 10 (decimal) unless the next character is "0",

 in which case it is taken as 8 (octal).

  The remainder of the string is converted to a long , long long , intmax_t

 or quad_t

 value in the obvious manner,

 stopping at the first character which is not a valid digit

 in the given base.

 (In bases above 10, the letter "A"

 in either upper or lower case

 represents 10, "B"

 represents 11, and so forth, with "Z"

 representing 35.)

  If endptr is not NULL , strtol stores the address of the first invalid character in *endptr .

 If there were no digits at all, however, strtol stores the original value of nptr in *endptr .

 (Thus, if *nptr is not "\\0"

 but **endptr is "\\0"

 on return, the entire string was valid.)

 Examples:

 @code

 #include <stdlib.h>

 #include <stdio.h>

 int main( void )

 {

  char *endpt = NULL;

  long l = 0;

  l = strtol("0x1236nvbi", &endpt;, 0);

  printf("{Expected: 4662} %ld

 ", l);

  printf("{Expected: \"nvbi\"} %s

 ", endpt);

  return 0;

 }

 @endcode

 @code

 Output

 {Expected: 4662} 4662

 {Expected: "nvbi"} nvbi

 @endcode

 @see atof()

 @see atoi()

 @see atol()

 @see strtod()

 @see strtoul()

 @see wcstol()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  strtold(const char *s, char **sp)

 @param s

 @param sp

 Refer to  strtod() for the documentation

 @see atof()

 @see atoi()

 @see atol()

 @see strtol()

 @see strtoul()

 @see wcstod()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  strtoul(const char *  nptr, char **  endptr, int base)

 @param nptr

 @param endptr

 @param base

 Note: 

 This description also covers the following functions -

  strtoull()  strtoumax()  strtouq() 

 @return   The strtoul , strtoull , strtoumax and strtouq functions

 return either the result of the conversion

 or, if there was a leading minus sign,

 the negation of the result of the conversion,

 unless the original (non-negated) value would overflow;

 in the latter case, strtoul returns ULONG_MAX , strtoull returns ULLONG_MAX , strtoumax returns UINTMAX_MAX ,

 and strtouq returns ULLONG_MAX .

 In all cases, errno is set to ERANGE .

 If no conversion could be performed, 0 is returned and

 the global variable errno is set to EINVAL (the last feature is not portable across all platforms).

   The strtoul function

 converts the string in nptr to an unsigned long

 value.

 The strtoull function

 converts the string in nptr to an unsigned long long

 value.

 The strtoumax function

 converts the string in nptr to an uintmax_t

 value.

 The strtouq function

 converts the string in nptr to a u_quad_t

 value.

 The conversion is done according to the given base ,

 which must be between 2 and 36 inclusive,

 or be the special value 0.

  The string may begin with an arbitrary amount of white space

 (as determined by isspace )

 followed by a single optional "+"

 or "-"

 sign.

 If base is zero or 16,

 the string may then include a "0x"

 prefix,

 and the number will be read in base 16; otherwise, a zero base is taken as 10 (decimal) unless the next character is 'o',

 in which case it is taken as 8 (octal).

  The remainder of the string is converted to an unsigned long

 value in the obvious manner,

 stopping at the end of the string

 or at the first character that does not produce a valid digit

 in the given base.

 (In bases above 10, the letter "A"

 in either upper or lower case

 represents 10, "B"

 represents 11, and so forth, with "Z"

 representing 35.)

  If endptr is not NULL , strtoul stores the address of the first invalid character in *endptr .

 If there were no digits at all, however, strtoul stores the original value of nptr in *endptr .

 (Thus, if *nptr is not "\\0"

 but **endptr is "\\0"

 on return, the entire string was valid.)

 Examples:

 @code

 #include <stdlib.h>

 #include <stdio.h>

 int main( void )

 {

  char *endpt = NULL;

  unsigned long ul = 0;

  ul = strtoul("435435hmnb", &endpt;, 12);

  printf("{Expected: 1066793} %ld

 ", ul);

  printf("{Expected: \"hmnb\"} %s

 ", endpt);

  return 0;

 }

 @endcode

 @code

 Output

 {Expected: 1066793} 1066793

 {Expected: "hmnb"} hmnb

 @endcode

 @see strtol()

 @see wcstoul()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  system(const char *cmd)

 @param cmd

 @return   The system function returns the exit status of the child process as returned by process exit reason or -1 if an error occurred when spawning a new process. It returns a non-zero value when NULL is passed as its argument.

   The system function

 spawns another process with the argument cmd. The calling process waits for the child process

 to finish executing.

  If cmd is a NULL pointer, system will return non-zero to indicate that system is suporrted

 and zero if it is not supported.

  The system function

 returns the exit status of the child process as returned by

 process' exit reason

 or -1 if an error occurred when spawning a new process.

 Examples:

 @code

 #include <stdlib.h> //system

 #include <stdio.h> //printf

 int main( void )

 {

    int retVal = -1;

    printf( "Calling system()...

 " );

    /* helloworld.exe is an executable that just prints

     * "Hello world!" and it should be created before

     * executing this example code.

     */

    retVal = system("c:\sys\bin\helloworld.exe");

    /* Print the return value of system() */

    printf( "system() returned: %d", retVal );

    return 0;

 }

 @endcode

 @code

 Output

 Calling system()...

 system() returned: -1

 @endcode

 @see popen()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  wctomb(char *s, wchar_t wchar)

 @param s

 @param wchar

 @return   If s is a null pointer, wctomb returns a non-zero or 0 value according to the current locale. If s is not a null pointer, wctomb returns -1 if the value of src does not correspond to 

   a valid character, or returns the number of bytes that constitute the character 

   corresponding to the value of wchar . In no case is value returned greater than the value of the {MB_CUR_MAX} macro.

   The wctomb function converts a wide character wchar into a multibyte character and stores

 the result in mbchar .

 The object pointed to by mbchar must be large enough to accommodate the multibyte character, which

 may be up to MB_LEN_MAX bytes.

  A call with a null mbchar pointer returns nonzero if the current locale requires shift states,

 zero otherwise;

 if shift states are required, the shift state is reset to the initial state.

  The behavior of the wctomb is affected by LC_CTYPE category of the current locale.

 Examples:

 @code

 #include <stdlib.h>

 #include <wchar.h>

 /* Illustrates how to use wctomb API */

 int example_wctomb(wchar_t wc)

 {

  char s[MAX_CUR_MAX];

   int len;

   /* represent a wide-char in a single byte*/

   len = wctomb(s, wc);

   /* return the number of bytes */

   return(len);

 }

 @endcode

 Limitations:

 The current implementation of wctomb is not affected by the LC_CTYPE category of the current locale.

 It works only for UTF8 character set.

 @see mbtowc()

 @see wcrtomb()

 @see wcstombs()

 @see wctob()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  wcstombs(char *  s, const wchar_t *  pwcs, size_t n)

 @param s

 @param pwcs

 @param n

 @return   The wcstombs function returns the number of bytes converted (not including 

 any terminating null), if successful, otherwise it returns ( size_t)(-1) .

   The wcstombs function converts a wide character string wcstring into a multibyte character string, mbstring ,

 beginning in the initial conversion state.

 Up to n bytes are stored in mbstring .

 Partial multibyte characters at the end of the string are not stored.

 The multibyte character string is null terminated if there is room.

  The behavior of the wcstombs is affected by LC_CTYPE category of the current locale.

 Examples:

 @code

 #include <stdlib.h>

 #include <wchar.h>

 /* Illustrates how to use wcstombs API */

 size_t example_wcstombs(wchar_t *wcs, char *s, size_t n)

 {

  size_t len;

  /* converting multibyte string to a wide-char string */

  len = wcstombs(s, (const wchar_t *)wcs, n);

  /* returning no of bytes that make up the multibyte sequence */

  return (len;);

 }

 @endcode

 Limitations:

 The current implementation of wcstombs is not affected by the LC_CTYPE category of the current locale.

 It works only for UTF8 character set.

 @see mbstowcs()

 @see wcsrtombs()

 @see wctomb()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  atoll(str) const char *str

 @param str

 Refer to  atol() for the documentation

 @see atof()

 @see atoi()

 @see strtod()

 @see strtol()

 @see strtoul()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  llabs(long long j)

 @param j

 @return   The llabs function

 returns the absolue value.

   The llabs function returns the absolute value of 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 fabs()

 @see hypot()

 @see labs()

 @see math()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  lldiv(long long numer, long long denom)

 @param numer

 @param denom

 The  lldiv function computes the value of  numer divided by  denom and returns the stored result in the form of the lldiv_t type.

 The lldiv_t type is defined as:

 @code

 typedef struct {

         long long quot; /* Quotient. */

         long long rem;  /* Remainder. */

 } lldiv_t;

 @endcode

 Examples:

 @code

 #include <stdlib.h>

 #include <stdio.h>

 #include <math.h> /* link to the math lib -libm */

 int main( void )

 {

  long long numer = pow(2, 40);

  long long denom = 3;

  /* call to lldiv */

  lldiv_t x = lldiv(-numer, denom);

  printf("Result-> 

 Quotient = %ld 

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

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

  if( exp_numer == (-numer) )

     printf("

 Expected output");  

  else

     printf("Unexpected output");

  return 0;

 }

 @endcode

 @code

 Output

 Result->

 Quotient = -366503875925

 Remainder = -1

 Expected output

 @endcode

 @see div()

 @see ldiv()

 @see math()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  strtoll(const char *  nptr, char **  endptr, int base)

 @param nptr

 @param endptr

 @param base

 Refer to  strtol() for the documentation

 @see atof()

 @see atoi()

 @see atol()

 @see strtod()

 @see strtoul()

 @see wcstol()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  strtoull(const char *  nptr, char **  endptr, int base)

 @param nptr

 @param endptr

 @param base

 Refer to  strtoul() for the documentation

 @see strtol()

 @see wcstoul()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn _Exit(int code) 

 @param code

 Refer to  _exit() for the documentation

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  setenv(const char *name, const char *value, int overwrite)

 @param name

 @param value

 @param overwrite

 Refer to  getenv() for the documentation

 @publishedAll

 @externallyDefinedApi

 */

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

 @param name

 Refer to  getenv() for the documentation

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  mkstemp(char *template)

 @param template

 @return   The mkstemp function

 returns -1 if no suitable file could be created

 and an error code is placed in the global variable. errno.

 The mkstemp function

 takes the given file name template and overwrites a portion of it

 to create a file with that name and returns a file descriptor

 opened for reading and writing.

 This file name is guaranteed not to exist at the time of function invocation

 and is suitable for use

 by the application.

 The template may be any file name with some number of "X s"

 appended

 to it, for example

 @code

 /tmp/temp.XXXXXX.

 @endcode

  The trailing "X s" are replaced with a

 unique alphanumeric combination.

 The number of unique file names mkstemp can return depends on the number of "X s"

 provided; six "X s"

 will

 result in mkstemp selecting one of 56800235584 (62 ** 6) possible temporary file names.

 Examples:

 @code

 #include <stdlib.h>

 #include <stdio.h> //printf, SEEK_SET

 #include <unistd.h>

 int main( void )

 {

  char arr[] = "c:\someXXXXXXXX";

  char buf[10];

  //create a temporary file using mkstemp()

  int fd = mkstemp(arr);

  if(fd != -1)

  {

     //write to the file

     write(fd, "hello", 5);

     //seek to the beginning of the file

     lseek(fd, 0, SEEK_SET); //beg of the file

     //read from the file

     read(fd, buf, 5);

     buf[5] = '\0';

     //close the file

     close(fd);

  }

  printf("buf read: %s", buf);

  return 0;

 }

 @endcode

 @code

 Output

 buf read: hello

 @endcode

 Notes:

  A common problem that results in a core dump is that the programmer passes 

 in a read-only string to mkstemp. This is particulary so with programs that were developed before -isoC compilers were common. For example, calling mkstemp with an argument of "/tmp/tempfile.XXXXXX" will result in a core dump due to mkstemp attempting to modify the string constant that was given. If 

 the program in question makes heavy use of that type of function call, you do 

 have the option of compiling the program so that it will store string constants 

 in a writable segment of memory.

 @see chmod()

 @see getpid()

 @see mkdir()

 @see open()

 @see stat()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  mkstemp64(char *template)

 @param template

 @return   The mkstemp64 function

 returns -1 if no suitable file could be created

 and an error code is placed in the global variable. errno.

 The mkstemp64() function generates a unique temporary file name from template. The last six characters of template must be XXXXXX and these are replaced with a string that makes the filename unique.

 The mkstemp64() function is a 64-bit version of mkstemp.

 This function can be used to create tmp files which can grow more than 32 bit sizes

 @see mkstemp()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  putenv(const char *string)

 @param string

 Refer to  getenv() for the documentation

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  random(void)

 Note: 

 This description also covers the following functions -

  srandom()  srandomdev()  initstate()  setstate() 

 The random function

 uses a non-linear additive feedback random number generator employing a

 default table of size 31 long integers to return successive pseudo-random

 numbers in the range from 0 to

 (2**(310) -1). The period of this random number generator is very large, approximately

 16*(2**(310) -1).

  The random and srandom functions have (almost) the same calling sequence and initialization properties as the rand and srand functions.

 The difference is that rand produces a much less random sequence  in fact, the low dozen bits

 generated by rand go through a cyclic pattern.

 All the bits generated by random are usable.

 For example, 'random()\&01'

 will produce a random binary

 value.

  Like rand random will by default produce a sequence of numbers that can be duplicated

 by calling srandom with "1"

 as the seed.

  The srandomdev routine initializes a state array using the random random number device which returns good random numbers,

 suitable for cryptographic use.

 Note that this particular seeding

 procedure can generate states which are impossible to reproduce by

 calling srandom with any value, since the succeeding terms in the

 state buffer are no longer derived from the LC algorithm applied to

 a fixed seed.

  The initstate routine allows a state array, passed in as an argument, to be initialized

 for future use.

 The size of the state array (in bytes) is used by initstate to decide how sophisticated a random number generator it should use  the

 more state, the better the random numbers will be.

 (Current "optimal" values for the amount of state information are

 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to

 the nearest known amount.

 Using less than 8 bytes will cause an error.)

 The seed for the initialization (which specifies a starting point for

 the random number sequence, and provides for restarting at the same

 point) is also an argument.

 The initstate function

 returns a pointer to the previous state information array.

  Once a state has been initialized, the setstate routine provides for rapid switching between states.

 The setstate function

 returns a pointer to the previous state array; its

 argument state array is used for further random number generation

 until the next call to initstate or setstate.

  Once a state array has been initialized, it may be restarted at a different 

   point either by calling initstate (with the desired seed, the state array, and its size) or 

   by calling both setstate (with the state array) and srandom (with the desired seed). The advantage of calling both setstate and srandom is that the size of the state array does not have to be remembered 

   after it is initialized.

  With 256 bytes of state information, the period of the random number generator 

   is greater than 2**(690) , which should be sufficient for most purposes.

 Examples:

 @code

 //Illustrates how to use srandom API.

 #include <stdlib.h>

 void  srandomTest()

 {

        long randNum;

        // srandom function call sets its argument as the seed for the new sequence of random integers //generated by  random

        srandom(2);

 // Function call to generate the random number, which will generate the random based on the //argument passed to the srandom function.

        randNum = random();

        //print the random number generated.

        printf("random number is %d",randNum);

 }

 @endcode

 @code

 Output

 random number is 1505335290.

 @endcode

 Diagnostics:

  If initstate is called with less than 8 bytes of state information, or if setstate detects that the state information has been garbled, error

 messages are printed on the standard error output.

 @see arc4random()

 @see rand()

 @see srand()

 @see random()

 Bugs:

  About 2/3 the speed of rand The historical implementation used to have a very weak seeding; the

 random sequence did not vary much with the seed.

 The current implementation employs a better pseudo-random number

 generator for the initial state calculation. Applications requiring cryptographic quality randomness should use arc4random .

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  srandom(unsigned long seed)

 @param seed

 Refer to  random() for the documentation

 @see arc4random()

 @see rand()

 @see srand()

 @see random()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  realpath(const char *pathname, char resolved_path[])

 @param pathname

 @param resolved_path[]

 @return   The realpath function returns resolved_path on success.

 If an error occurs, realpath returns NULL, and resolved_path contains the pathname which caused the problem.

   The realpath function resolves all symbolic links, extra "/"

 characters and references to /./ and /../ in pathname, and copies the resulting absolute pathname into

 the memory referenced by resolved_path. The resolved_path argument must refer to a buffer capable of storing at least PATH_MAX characters.

  The realpath function will resolve both absolute and relative paths

 and return the absolute pathname corresponding to pathname. All but the last component of pathname must exist when realpath is called.

 Examples:

 @code

 #include<stdlib.h>

 #include<stdio.h> //printf

 #include<sys/stat.h> //S_IWUSR

 #include<sys/syslimits.h> //PATH_MAX

 #include<unistd.h> //chdir

 int main()

 {

  char resolvepath[PATH_MAX];

  FILE *fp = NULL;

  char *rpath = NULL;

  int isymlink = 0;

  fp = fopen("c:\xyz.txt", "w");

  if(!fp)

  {

      printf("fopen failed!!");

      return -1;

  }

  mkdir("c:\tmdir", S_IWUSR);

  int c = chdir("c:\");

  if(c == -1)

  {

      printf("chdir failed!!");

      return -1;

  }

  rpath = realpath(".\tmdir\..\xyz.txt", resolvepath);

  printf("resolvepath: %s", resolvepath);

  if(rpath != NULL)

     printf("rpath: %s", rpath);

  fclose(fp);

  rmdir("c:\tmdir");

  unlink("c:\xyz.txt");

  mkdir("c:\tdir", S_IWUSR);

  fp = fopen("c:\tdir\xyz.txt", "w");

  if(!fp)

  {

      printf("fopen failed!!");

      return -1;

  }

  fclose(fp);

  unlink("c:\linkname.txt");

  isymlink = symlink("c:\tdir\xyz.txt", "c:\linkname.txt");

  if (isymlink == -1)

  {

      printf("symlink failed!!");

      return -1;

  }

  rpath = realpath("c:\linkname.txt", resolvepath);

  printf("resolvepath: %s", resolvepath);

  if(rpath != NULL)

     printf("rpath: %s", rpath);

  unlink("c:\tdir\xyz.txt");

  rmdir("c:\tdir");

  return 0;

 }

 @endcode

 @code

 Output

 resolvepath: C:\xyz.txt

 rpath: C:\xyz.txt

 resolvepath: c:	dir\xyz.txt

 rpath: c:	dir\xyz.txt

 @endcode

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  setstate(char *state)

 @param state

 Refer to  random() for the documentation

 @see arc4random()

 @see rand()

 @see srand()

 @see random()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  initstate(unsigned long seed, char *state, long n)

 @param seed

 @param state

 @param n

 Refer to  random() for the documentation

 @see arc4random()

 @see rand()

 @see srand()

 @see random()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  getprogname(void)

 Refer to  setprogname() for the documentation

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  reallocf(void *ptr, size_t size)

 @param ptr

 @param size

 Refer to  malloc() for the documentation

 @see brk()

 @see mmap()

 @see getpagesize()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn setprogname(const char *programname)

 @param programname

 These utility functions get and set the current program's name as used by

 various error-reporting functions.getprogname() returns the name of the current program.

 This function is typically useful when generating error messages or other diagnostic out-put.

 If the program name has not been set, getprogname() will return NULL.

 setprogname() sets the name of the current program to be the last path-name component of the programname argument.

 It should be invoked at the start of the program, using the argv[0] passed into the program's main() function.

 A pointer into the string pointed to by the programname argument is kept as the program name.

 Therefore, the string pointed to by programname should not be modified during the rest of the program's operation.

 A program's name can only be set once, and in NetBSD that is actually done by program start-up code that is run before main() is called.

 Therefore, in NetBSD, calling setprogname() from main() has no effect.

 However, it does serve to increase the portability of the program:

 on other operating systems, getprogname() and setprogname() may be implemented by a portability library, 

 and a call to setprogname() allows that library to know the program name without modifications to that system's program start-up code.

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  strtoq(const char *nptr, char **endptr, int base)

 @param nptr

 @param endptr

 @param base

 Refer to  strtol() for the documentation

 @see atof()

 @see atoi()

 @see atol()

 @see strtod()

 @see strtoul()

 @see wcstol()

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  strtouq(const char *nptr, char **endptr, int base)

 @param nptr

 @param endptr

 @param base

 Refer to  strtoul() for the documentation

 @see strtol()

 @see wcstoul()

 @publishedAll

 @externallyDefinedApi

 */

 /** @struct div_t 

 Contains the following members

 @publishedAll

 @externallyDefinedApi

 */

 /** @var div_t::quot

 quotient

 */

 /** @var div_t::rem

 remainder

 */

 /** @struct ldiv_t 

 Contains the following members

 @publishedAll

 @externallyDefinedApi

 */

 /** @var ldiv_t::quot

 quotient

 */

 /** @var ldiv_t::rem

 remainder

 */

 /** @struct lldiv_t 

 Contains the following members

 @publishedAll

 @externallyDefinedApi

 */

 /** @var lldiv_t::quot

 quotient

 */

 /** @var lldiv_t::rem

 remainder

 */

 /** @def EXIT_FAILURE 

 These are arguments for the exit and _exit functions and the return values for the atexit and _onexit functions.

 @publishedAll

 @externallyDefinedApi

 */

 /** @def EXIT_SUCCESS 

 These are arguments for the exit and _exit functions and the return values for the atexit and _onexit functions.

 @publishedAll

 @externallyDefinedApi

 */

 /** @def  RAND_MAX

 The constant RAND_MAX is the maximum value that can be returned by the rand function.

 @publishedAll

 @externallyDefinedApi

 */

 /** @def MB_CUR_MAX 

 The value of MB_CUR_MAX is the maximum number of bytes in a multibyte character for the current locale.

 @publishedAll

 @externallyDefinedApi

 */