sl@0: /** @file ../include/stdlib.h
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @fn  abort(void)
sl@0: 
sl@0: @return   The abort function
sl@0: never returns.
sl@0: 
sl@0:   The abort function causes abnormal program termination to occur, unless the
sl@0: signal SIGABRT is being caught and the signal handler does not return.
sl@0: 
sl@0:  Any open streams are flushed and closed.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include  <stdio.h>
sl@0: #include  <stdlib.h>
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:    FILE *stream;
sl@0:  
sl@0:    if( (stream = fopen( "notexist.file", "r" )) == NULL )
sl@0:    {
sl@0:       perror( "Error occurred while opening file" );
sl@0:       abort();
sl@0:    }
sl@0:    else
sl@0:       fclose( stream );
sl@0:    return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0:  Output
sl@0: @code
sl@0: Error occurred while opening file: No such file or directory
sl@0: 
sl@0: @endcode
sl@0:   
sl@0: Implementation notes: 
sl@0:   
sl@0:   The abort function is thread-safe. It is unknown whether it is async-cancel-safe.
sl@0: 
sl@0: Limitations:
sl@0: 
sl@0: The signal related functionalities are not applicable to the Symbian OS implementation
sl@0: as there is no support for signals from Symbian OS.
sl@0: 
sl@0: @see exit()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  abs(int j)
sl@0: @param j
sl@0: @return   The abs function
sl@0: returns
sl@0: the absolute value.
sl@0: 
sl@0:   The abs function computes the absolute value of an integer j. The absolute value is always postive, it has size but not direction.
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include  <stdio.h>
sl@0: #include  <stdlib.h>
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:    int    ix = -4, iy;
sl@0:    long   lx = -41567L, ly;
sl@0:    long long llx = -5343546758, lly;
sl@0:  
sl@0:    iy = abs( ix );
sl@0:    printf( "The absolute value of %d is %d
sl@0: ", ix, iy);
sl@0:  
sl@0:    ly = labs( lx );
sl@0:    printf( "The absolute value of %ld is %ld
sl@0: ", lx, ly);
sl@0:  
sl@0:    lly = llabs( llx );
sl@0:    printf( "The absolute value of %lld is %lld
sl@0: ", llx, lly );
sl@0:  
sl@0:    return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  
sl@0: @code
sl@0: Output
sl@0: 
sl@0: The absolute value of -4 is 4
sl@0: The absolute value of -41567 is 41567
sl@0: The absolute value of -5343546758 is 5343546758
sl@0: 
sl@0: @endcode
sl@0: @see fabs()
sl@0: @see floor()
sl@0: @see hypot()
sl@0: @see labs()
sl@0: @see llabs()
sl@0: @see math()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  atexit(void(*)(void) func)
sl@0: @param func
sl@0: @return   The atexit function returns the value 0 if successful; otherwise it returns 
sl@0: the value -1 and sets the global variable errno to indicate the error.
sl@0: 
sl@0:   The atexit function
sl@0: 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;
sl@0: no arguments are passed.
sl@0: 
sl@0:  These functions must not call exit . If it is necessary to terminate the process while in such a 
sl@0:   function, the _exit function should be used. Alternatively, 
sl@0:   the function may cause abnormal process termination, for example by calling abort
sl@0: 
sl@0:  At least 32 functions can always be registered and more are allowed as long 
sl@0:   as sufficient memory can be allocated.
sl@0: 
sl@0: In Symbian app with an entry point E32Main, the registered functions will not be called unless exit() is specified explicitly.
sl@0: 
sl@0: Limitation:
sl@0: atexit() is not supported on emulator.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: void fun1( void ), fun2( void ), fun3( void ), fun4( void );
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:    atexit( fun1 );
sl@0:    atexit( fun2 );
sl@0:    atexit( fun3 );
sl@0:    atexit( fun4 );
sl@0:    printf( "Before exiting...." );
sl@0: }
sl@0:  
sl@0: void fun1()
sl@0: {
sl@0:    printf( " fun1 " );
sl@0: }
sl@0:  
sl@0: void fun2()
sl@0: {
sl@0:    printf( " fun2" );
sl@0: }
sl@0:  
sl@0: void fun3()
sl@0: {
sl@0:    printf( " fun3 " );
sl@0: }
sl@0:  
sl@0: void fun4()
sl@0: {
sl@0:    printf( " fun4 " );
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: Before exiting...
sl@0: fun4
sl@0: fun3
sl@0: fun2
sl@0: fun1
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0: #include <e32base.h>
sl@0: 
sl@0: void fun1(void),fun2(void),fun3(void);
sl@0: 
sl@0: LOCAL_C int MainL()
sl@0: 	{
sl@0: 	atexit( fun1 );
sl@0:    	atexit( fun2 );
sl@0:    	atexit( fun3 );
sl@0:     	printf( "Before exiting....\n" );
sl@0:   	getchar();
sl@0: 	exit();
sl@0: 	}
sl@0: 
sl@0: 
sl@0: void fun1()
sl@0: {
sl@0: printf( " fun1\n " );
sl@0: getchar();
sl@0: }
sl@0:  
sl@0: void fun2()
sl@0: {
sl@0: printf( " fun2\n " );
sl@0: getchar();
sl@0: }
sl@0:  
sl@0: void fun3()
sl@0: {
sl@0: printf( " fun3\n " );
sl@0: getchar();
sl@0: }
sl@0: 
sl@0: 
sl@0: GLDEF_C TInt E32Main()
sl@0: 	{
sl@0: 	__UHEAP_MARK;
sl@0: 	CTrapCleanup* cleanup = CTrapCleanup::New();
sl@0: 	if(cleanup == NULL)
sl@0: 		{
sl@0: 		return KErrNoMemory;
sl@0: 		}
sl@0: 	TInt ret;
sl@0: 	TRAPD(err,ret = MainL());
sl@0: 
sl@0: 	delete cleanup;
sl@0: 	__UHEAP_MARKEND;
sl@0: 	return KErrNone;
sl@0:    	}
sl@0: 
sl@0: @encode
sl@0: 
sl@0: @code
sl@0: Output
sl@0: 
sl@0: Before exiting...
sl@0: 
sl@0: fun3
sl@0: fun2
sl@0: fun1
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: @see exit()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  atof(const char *nptr)
sl@0: @param nptr
sl@0: @return   The atof function
sl@0: returns
sl@0: the converted value if the value can be represented.
sl@0: 
sl@0:   The atof function converts the initial portion of the string pointed to by nptr to double
sl@0: representation.
sl@0: 
sl@0: @code
sl@0:  It is equivalent to: strtod(nptr, (char **)NULL);
sl@0: 
sl@0: The decimal point
sl@0: character is defined in the program's locale (category LC_NUMERIC).
sl@0: @endcode
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: void main( void )
sl@0: {
sl@0:  /* Test of atof */
sl@0:  double d = atof("  86778E-2");
sl@0:  
sl@0:  printf( "result of atof: %f
sl@0: ", d );
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: @code
sl@0: Output
sl@0: result of atof: 867.78
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Implementation notes:
sl@0:   
sl@0: The atof function is not thread-safe and also not async-cancel-safe. The atof function has been deprecated. Use strtod instead.
sl@0: 
sl@0: @see atoi()
sl@0: @see atol()
sl@0: @see strtod()
sl@0: @see strtol()
sl@0: @see strtoul()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  atoi(const char *nptr)
sl@0: @param nptr
sl@0: @return   The atoi function
sl@0: returns
sl@0: the converted value if the value can be represented.
sl@0: 
sl@0:   The atoi function converts the initial portion of the string pointed to by nptr to int
sl@0: representation.
sl@0: 
sl@0: @code
sl@0: 
sl@0:  It is equivalent to: (int)strtol(nptr, (char **)NULL, 10);
sl@0: @endocde
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: void main( void )
sl@0: {
sl@0:   /* call to atoi */
sl@0:   char *str = "  -56957jdhfjk";    
sl@0:   int i = atoi( str );
sl@0:   printf( "result of atoi: %d
sl@0: ", i );
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: @code
sl@0: Output
sl@0: result of atoi: -56957
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Implementation notes:
sl@0:   
sl@0: The atoi function is not thread-safe and also not async-cancel safe. The atoi function has been deprecated. Use strtol instead.
sl@0: 
sl@0: @see atof()
sl@0: @see atol()
sl@0: @see strtod()
sl@0: @see strtol()
sl@0: @see strtoul()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  atol(const char *nptr)
sl@0: @param nptr
sl@0: 
sl@0: Note: 
sl@0: 
sl@0: This description also covers the following functions -
sl@0:  atoll() 
sl@0: 
sl@0: @return   The atol and atoll functions
sl@0: return
sl@0: the converted value if the value can be represented.
sl@0: 
sl@0:   The atol function converts the initial portion of the string pointed to by nptr to long
sl@0: integer
sl@0: representation.
sl@0: 
sl@0:  It is equivalent to:
sl@0: 
sl@0: @code
sl@0: 
sl@0:     strtol(nptr, (char **)NULL, 10); 
sl@0: @endcode
sl@0: The atoll function converts the initial portion of the string pointed to by nptr to long long
sl@0: integer representation. It is equivalent to:    
sl@0: @code
sl@0:     strtoll(nptr, (char **)NULL, 10);
sl@0: @endcode
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: void main( void )
sl@0: {
sl@0:  /* call to atol */
sl@0:  long l = atol( "-000002344" );
sl@0:  
sl@0:  printf( "result of atol: %ld
sl@0: ", l );
sl@0: }
sl@0: @endcode
sl@0: 
sl@0: @code
sl@0: Output
sl@0: 
sl@0: result of atol: -2344
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: void main( void )
sl@0: {
sl@0:  /* call to atoll */
sl@0:  long long l = atoll("454756356bs");
sl@0:  
sl@0:  printf( "result of atoll: %ld
sl@0: ", l );
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: @code
sl@0: Output
sl@0: 
sl@0: result of atoll: 454756356
sl@0: 
sl@0: @endcode
sl@0: @see atof()
sl@0: @see atoi()
sl@0: @see strtod()
sl@0: @see strtol()
sl@0: @see strtoul()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (*compar) (const void *, const void *))
sl@0: @param key
sl@0: @param base
sl@0: @param nmemb
sl@0: @param size
sl@0: @param compar
sl@0: @return   The bsearch function returns a pointer to a matching member of the array, 
sl@0: or a null pointer if no match is found. If two or more matching members are found 
sl@0: the result is unspecified.
sl@0: 
sl@0:   The bsearch function searches an array of nmemb objects, the initial member of which is
sl@0: 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.
sl@0: 
sl@0:  The contents of the array should be in ascending sorted order according to 
sl@0:   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 
sl@0:   less than, equal to, or greater than zero if the key object is found, respectively, to be less than, to match, or be 
sl@0:   greater than the array member.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include<stdlib.h>
sl@0: #include<stdio.h>
sl@0:  
sl@0: int search_function(const void* a,const void* b)
sl@0: {
sl@0:     return(*(int *)a - *(int *)b);
sl@0: }
sl@0:  
sl@0: int main()
sl@0: {
sl@0: int arr[] = {3,5,7,8,10};
sl@0: int key = 7;
sl@0: int i = 5;
sl@0:  
sl@0: int *ele;
sl@0:  
sl@0: ele  = ( int* ) bsearch(&key;, (void *)arr, i, sizeof(arr[0]), search_function);
sl@0:  
sl@0: if (ele != NULL)
sl@0:         printf("
sl@0: element found: %d", *ele);
sl@0: else
sl@0:         printf("
sl@0: element not found");
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: element found: 7
sl@0: 
sl@0: @endcode
sl@0: @see qsort()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  calloc(size_t number, size_t size)
sl@0: @param number
sl@0: @param size
sl@0: 
sl@0: Refer to  malloc() for the documentation
sl@0: @see brk()
sl@0: @see mmap()
sl@0: @see getpagesize()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  div(int num, int denom)
sl@0: @param num
sl@0: @param denom
sl@0: @return   The div function
sl@0: returns a structure of type div_t that contains two int
sl@0: members named quot (quotient)
sl@0: and rem (remainder).
sl@0: 
sl@0:   The div function
sl@0: computes the value num/denom and returns the quotient and remainder in a structure named div_t that contains two int
sl@0: members named quot and rem.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: void main( void )
sl@0: {
sl@0:  int numer = -14;
sl@0:  int denom = -3;
sl@0:  int exp_numer = 0;
sl@0:     
sl@0:  /* call to div */
sl@0:  div_t x = div(numer, denom);
sl@0:  
sl@0:  printf("Result->
sl@0:  Quotient = %d
sl@0:  Remainder = %d
sl@0: ", x.quot, x.rem);
sl@0:                 
sl@0:  exp_numer = (denom * x.quot) + x.rem;
sl@0:  
sl@0:  if( exp_numer == (numer) )
sl@0:     printf("Result is same as the expected output");  
sl@0:  else
sl@0:     printf("Unexpected output");
sl@0:     
sl@0:  return 0; 
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: Result->
sl@0: Quotient = 4
sl@0: Remainder = -2
sl@0: Result is same as the expected output
sl@0: 
sl@0: @endcode
sl@0: @see ldiv()
sl@0: @see lldiv()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  exit(int status)
sl@0: @param status
sl@0: 
sl@0: Note: 
sl@0: 
sl@0: This description also covers the following functions -
sl@0:  _Exit() 
sl@0: 
sl@0: @return   The exit and _Exit functions
sl@0: never return.
sl@0: 
sl@0:  The  exit and  _Exit functions terminate a process.
sl@0: 
sl@0: Before termination, exit performs the following functions in the order listed:
sl@0: 
sl@0: @code
sl@0: 
sl@0:    1. Call the functions registered with the atexit function, in the reverse order of their registration.
sl@0:    2. Flush all open output streams.
sl@0:    3. Close all open streams.
sl@0:    4. Unlink all files created with the tmpfile function. 
sl@0: @endcode
sl@0: 
sl@0: The _Exit function terminates without calling the functions registered with the atexit function, and may or may not perform the other actions listed. 
sl@0: Both functions make the low-order eight bits of the status argument available to a parent process which has called a wait function.
sl@0: 
sl@0: The C Standard (-isoC-99) defines the values 0, EXIT_SUCCESS, and EXIT_FAILURE as possible values of status. 
sl@0: Cooperating processes may use other values.
sl@0: 
sl@0: Note that exit does nothing to prevent bottomless recursion should a function registered using atexit itself call exit. 
sl@0: Such functions must call _Exit instead (although this has other effects as well which may not be desired).
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: /* Detailed description : Sample usage of exit system call. */
sl@0: #include <stdlib.h>
sl@0:  
sl@0: void main()
sl@0: {
sl@0:   exit(0) ; //Here 0 is exit status of the process
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @see _exit()
sl@0: @see wait()
sl@0: @see atexit()
sl@0: @see tmpfile()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  free(void *p)
sl@0: @param p
sl@0: 
sl@0: Refer to  malloc() for the documentation
sl@0: @see brk()
sl@0: @see mmap()
sl@0: @see getpagesize()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  getenv(const char *name)
sl@0: @param name
sl@0: 
sl@0: Note: 
sl@0: 
sl@0: This description also covers the following functions -
sl@0:  setenv()  putenv()  unsetenv() 
sl@0: 
sl@0: @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 
sl@0:   return the value -1 and set the global variable errno is set to indicate the error. The unsetenv function never returns.
sl@0: 
sl@0: These functions set, unset and fetch environment variables from the
sl@0: host environment list.
sl@0: For compatibility with differing environment conventions,
sl@0: the given arguments name and value may be appended and prepended,
sl@0: respectively,
sl@0: with an equal sign "="
sl@0: 
sl@0:  The getenv function obtains the current value of the environment variable name.
sl@0: 
sl@0:  The setenv function inserts or resets the environment variable name in the current environment list.
sl@0: If the variable name does not exist in the list,
sl@0: it is inserted with the given value. If the variable does exist, the argument overwrite is tested; if overwrite is
sl@0: zero, the
sl@0: variable is not reset, otherwise it is reset
sl@0: to the given value.
sl@0: 
sl@0:  The putenv function takes an argument of the form "name=value" and is
sl@0: equivalent to: setenv(name, value, 1);
sl@0: 
sl@0:  The unsetenv function
sl@0: deletes all instances of the variable name pointed to by name from the list.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h> //getenv
sl@0: #include <stdio.h> //printf
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:   int iret = putenv("PATH=c:\sys\bin;");
sl@0:  
sl@0:   if( iret == -1)
sl@0:      printf( "putenv() failed!!
sl@0: " );
sl@0:  
sl@0:    /* fetch new value. */
sl@0:   char *psc = getenv("PATH");
sl@0:  
sl@0:   if( psc != NULL )
sl@0:       printf( "new PATH variable is: %s
sl@0: ", psc );
sl@0:  
sl@0:   return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: new PATH variable is: c:\sys\bin;
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include <stdlib.h> //setenv, getenv
sl@0: #include <stdio.h> //printf
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:    char *var;
sl@0:  
sl@0:    /* Unset the value of the HOME environment variable
sl@0:     * to make sure that it is non-existing.
sl@0:     */
sl@0:    unsetenv( "HOME" );
sl@0:  
sl@0:    /* Set the value of HOME environment with no overwrite option */
sl@0:    int iret = setenv("HOME", "/home", 0);
sl@0:     
sl@0:    if(iret == -1)
sl@0:       printf( "Setenv failed!!" );
sl@0:     
sl@0:    /* Get new value. */
sl@0:    var = getenv( "HOME" );
sl@0:  
sl@0:    if( var != NULL )
sl@0:       printf( "new HOME variable is: %s
sl@0: ", var );
sl@0:     
sl@0:    /* Set the value of HOME environment with the overwrite option */
sl@0:    iret = setenv("HOME", "/check", 1);
sl@0:     
sl@0:    /* Get new value. */
sl@0:    var = getenv( "HOME" );
sl@0:  
sl@0:    if( var != NULL )
sl@0:       printf( "new HOME variable is: %s
sl@0: ", var );
sl@0:      
sl@0:    return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: new HOME variable is: \home
sl@0: new HOME variable is: \check
sl@0: 
sl@0: @endcode
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  labs(long j)
sl@0: @param j
sl@0: @return   The labs() function shall return the absolute value of the long integer operand.
sl@0: 
sl@0:  The labs function
sl@0: returns the absolute value of the long integer j.
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include  <stdio.h>
sl@0: #include  <stdlib.h>
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:    int    ix = -4, iy;
sl@0:    long   lx = -41567L, ly;
sl@0:    long long llx = -5343546758, lly;
sl@0:  
sl@0:    iy = abs( ix );
sl@0:    printf( "The abs value of %d is %d
sl@0: ", ix, iy);
sl@0:  
sl@0:    ly = labs( lx );
sl@0:    printf( "The abs value of %ld is %ld
sl@0: ", lx, ly);
sl@0:  
sl@0:    lly = llabs( llx );
sl@0:    printf( "The abs value of %lld is %lld
sl@0: ", llx, lly );
sl@0:  
sl@0:    return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: The absolute value of -4 is 4
sl@0: The absolute value of -41567 is 41567
sl@0: The absolute value of -5343546758 is 5343546758
sl@0: 
sl@0: @endcode
sl@0: @see abs()
sl@0: @see floor()
sl@0: @see llabs()
sl@0: @see math()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  ldiv(long num, long denom)
sl@0: @param num
sl@0: @param denom
sl@0: @return   The ldiv function
sl@0: returns a structure of type ldiv_t that contains two long
sl@0: members named quot (quotient)
sl@0: and rem (remainder).
sl@0: 
sl@0:   The ldiv function
sl@0: computes the value num / denom and returns the quotient and remainder in a structure named ldiv_t
sl@0: that contains two long
sl@0: members named quot and rem.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:  long numer = 13;
sl@0:  long denom = -3;
sl@0:  
sl@0:  /* call to ldiv */
sl@0:  ldiv_t x = ldiv(numer, denom);
sl@0:  
sl@0:  printf("Result-> 
sl@0: Quotient = %ld 
sl@0: Remainder = %ld", x.quot, x.rem);
sl@0:                  
sl@0:  long exp_numer = (denom * x.quot) + x.rem;
sl@0:   
sl@0:  if( exp_numer == (numer) )
sl@0:     printf("
sl@0: Result is same as the expected output");  
sl@0:  else
sl@0:     printf("
sl@0: Unexpected output");
sl@0:  
sl@0:  return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: Result->
sl@0: Quotient = 4
sl@0: Remainder = -1
sl@0: Result is same as the expected output
sl@0: 
sl@0: @endcode
sl@0: @see div()
sl@0: @see lldiv()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  malloc(size_t nbytes)
sl@0: @param nbytes
sl@0: 
sl@0: Note: 
sl@0: 
sl@0: This description also covers the following functions -
sl@0:  calloc()  realloc()  reallocf()  free() 
sl@0: 
sl@0: @return   The malloc and calloc functions return a pointer to the allocated memory if successful; otherwise
sl@0: 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 
sl@0:   error occurs, whereas reallocf deallocates it in this case. The free function returns no value.
sl@0: 
sl@0:   The malloc function allocates nbytes of memory. The allocated space is suitably aligned (after possible 
sl@0: 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 
sl@0: page boundary aligned as well. If malloc fails a NULL pointer is returned.
sl@0: 
sl@0:  Note that malloc does NOT normally initialize the returned memory to zero bytes.
sl@0: 
sl@0:  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 
sl@0:   initialized to zero bytes.
sl@0: 
sl@0:  The realloc function changes the size of the previously allocated memory 
sl@0:   referenced by ptr to nbytes. The contents of the memory are unchanged up to the lesser 
sl@0:   of the new and old sizes. If the new size is larger, the value of the newly 
sl@0:   allocated portion of the memory is undefined. If the requested memory cannot 
sl@0:   be allocated, NULL is returned and the memory referenced by ptr is valid and unchanged. If memory can be allocated, the memory referenced 
sl@0:   by ptr is freed and a pointer to the newly allocated memory is returned. 
sl@0:   Note that realloc and reallocf may move the memory allocation resulting in a different return 
sl@0:   value from ptr. If ptr is NULL, the realloc function behaves identically to malloc for the specified nbytes.
sl@0: 
sl@0:  The reallocf function is identical to the realloc function, except that it
sl@0: will free the passed pointer when the requested memory cannot be allocated.
sl@0: This is a specific API designed to ease the problems with traditional coding styles
sl@0: for realloc causing memory leaks in libraries.
sl@0: 
sl@0:  The free function causes the allocated memory referenced by ptr to be made available for future allocations.
sl@0: If ptr is NULL, no action occurs.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>    //malloc
sl@0: #include <stdio.h>    //printf
sl@0:   
sl@0: int main( void )
sl@0: {
sl@0:    /* allocate memory */
sl@0:    char  *pc = (char *)malloc( sizeof(char) * 3);
sl@0:    
sl@0:    if( pc == NULL )
sl@0:       printf( "memory insufficient
sl@0: " );
sl@0:    else
sl@0:    {
sl@0:       printf( "memory allocated
sl@0: " );
sl@0:       free( pc );
sl@0:       printf( "memory freed
sl@0: " );
sl@0:    }
sl@0:   
sl@0:    return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: memory allocated
sl@0: memory freed
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include <stdio.h> //printf
sl@0: #include <stdlib.h> //calloc
sl@0:    
sl@0: int main( void )
sl@0: {
sl@0:    int  *pint = (int *)calloc(2, sizeof (int) * 2);
sl@0:    if( pint != NULL )
sl@0:       printf( "allocated 2 blocks of memory, each of size -
sl@0:                twice the size of an integer
sl@0: " );
sl@0:    else
sl@0:       printf( "can't allocate memory
sl@0: " );
sl@0:    free( pint );
sl@0:   
sl@0:    return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: allocated 2 blocks of memory, each of size - 2 integers
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include <stdio.h> //printf
sl@0: #include <stdlib.h> //realloc
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:  int  *pint = (int *)calloc(2, sizeof (int) * 2);
sl@0:  if (pint == NULL)
sl@0:   {
sl@0:   printf("calloc failed to allocate memory
sl@0: ");
sl@0:   return -1;
sl@0:   }
sl@0:  else
sl@0:   {
sl@0:   printf("calloc allocated memory: 128 bytes
sl@0: ");
sl@0:   }
sl@0:  
sl@0:  pint = (int *)realloc(pint, (sizeof (int) * 6) );
sl@0:  if (pint == NULL)
sl@0:   {
sl@0:   printf("realloc failed to allocate memory
sl@0: ");
sl@0:   return -1;
sl@0:   }
sl@0:  else
sl@0:   {
sl@0:   printf("realloc allocated memory: 192 bytes
sl@0: ");
sl@0:   }
sl@0:   
sl@0:   free( pint );
sl@0:   return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: calloc allocated memory: 128 bytes
sl@0: realloc allocated memory: 192 bytes
sl@0: 
sl@0: @endcode
sl@0: @see brk()
sl@0: @see mmap()
sl@0: @see getpagesize()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  mblen(const char *s, size_t n)
sl@0: @param s
sl@0: @param n
sl@0: @return   If s is a null pointer, mblen returns non-zero 0 value depending upon the current locale (see 
sl@0:   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.
sl@0: 
sl@0:   The mblen function computes the length in bytes
sl@0: of a multibyte character s according to the current conversion state.
sl@0: Up to n bytes are examined.
sl@0: 
sl@0:  A call with a null s pointer returns nonzero if the current locale requires shift states,
sl@0: zero otherwise;
sl@0: if shift states are required, the shift state is reset to the initial state.
sl@0: 
sl@0:  The behavior of the mblen is affected by LC_CTYPE category of the current locale.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <wchar.h>
sl@0: /* Illustrates how to use mblen API */
sl@0: int example_mblen(wchar_t wc)
sl@0: {
sl@0:  int len;
sl@0:  
sl@0:  /* determine the number bytes in the multibyte char */
sl@0:  len = mblen(wc, MB_CUR_MAX);
sl@0:  if(len == -1)
sl@0:  {
sl@0:         wprintf(L"mblen returned error!!
sl@0: ");
sl@0:  }
sl@0:  /* return the no of bytes */
sl@0:  return(len);
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Limitations:   
sl@0: 
sl@0: The current implementation of mblen is not affected by the LC_CTYPE category of the current locale.
sl@0: It works only for UTF8 character set.
sl@0: 
sl@0: @see mbrlen()
sl@0: @see mbtowc()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  mbstowcs(wchar_t *  pwcs, const char *  s, size_t n)
sl@0: @param pwcs
sl@0: @param s
sl@0: @param n
sl@0: @return   The mbstowcs function returns the number of wide characters converted,
sl@0: not counting any terminating null wide character, or -1
sl@0: if an invalid multibyte character was encountered.
sl@0: 
sl@0:   The mbstowcs function converts a multibyte character string mbstring beginning in the initial conversion state
sl@0: into a wide character string wcstring. No more than n wide characters are stored.
sl@0: A terminating null wide character is appended if there is room.
sl@0: 
sl@0:  The behavior of the mbstowcs is affected by LC_CTYPE category of the current locale.
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdio.h>
sl@0: #include <stdlib.h>
sl@0: #include <wchar.h>
sl@0: /* Illustrates how to use mbstowcs API */
sl@0: size_t example_mbstowcs(wchar_t *wc, char *s, size_t n)
sl@0: {
sl@0:  size_t len;
sl@0:  /* converting multibyte string to a wide-char string */
sl@0:  len = mbstowcs(wc, s, n);
sl@0:  /* checking for error */
sl@0:  if(len < 0)
sl@0:  {
sl@0:         wprintf(L"mbstowcs returned error!!
sl@0: ");
sl@0:  }
sl@0:  /* returning no of bytes consumed */
sl@0:  return (len);
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Limitations:   
sl@0: 
sl@0: The current implementation of mbstowcs is not affected by the LC_CTYPE category of the current locale.
sl@0: It works only for UTF8 character set.
sl@0: 
sl@0: @see mbsrtowcs()
sl@0: @see mbtowc()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  mbtowc(wchar_t * pwc, const char *  s, size_t n)
sl@0: @param pwc
sl@0: @param s
sl@0: @param n
sl@0: @return   If mbchar is NULL, the mbtowc function returns nonzero if shift states are supported,
sl@0: zero otherwise. Otherwise, if mbchar is not a null pointer, mbtowc either returns 0 if mbchar represents the null wide character, or returns
sl@0: the number of bytes processed in mbchar, or returns -1 if no multibyte character
sl@0: could be recognized or converted.
sl@0: In this case, mbtowc internal conversion state is undefined.
sl@0: 
sl@0:   The mbtowc function converts a multibyte character mbchar into a wide character according to the current conversion state,
sl@0: and stores the result in the object pointed to by wcharp. Up to n bytes are examined.
sl@0: 
sl@0:  A call with a null mbchar pointer returns nonzero if the current encoding requires shift 
sl@0:   states, zero otherwise. If shift states are required the shift state is reset 
sl@0:   to the initial state.
sl@0: 
sl@0:  The behavior of the mbtowc is affected by LC_CTYPE category of the current locale.
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <wchar.h>
sl@0: /* Illustrates how to use mbtowc API */
sl@0: int example_mbtowc(wchar_t *wc, char *s)
sl@0: {
sl@0:  int len;
sl@0:  /* converting multibyte sequence to a wide-character */
sl@0:  len = mbtowc(wc, s, MB_CUR_MAX);
sl@0:  /* checking for error */
sl@0:  if(len < 0)
sl@0:  {
sl@0:         wprintf(L"mbtowc returned error!!
sl@0: ");
sl@0:  }
sl@0:  /* returning no of bytes consumed */
sl@0:  return (len;);
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Limitations:
sl@0: 
sl@0: The current implementation of mbtowc is not affected by the LC_CTYPE category of the current locale.
sl@0: It works only for UTF8 character set.
sl@0: 
sl@0: @see btowc()
sl@0: @see mblen()
sl@0: @see mbrtowc()
sl@0: @see mbstowcs()
sl@0: @see wctomb()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  qsort(void *, size_t, size_t, int(*)(const void *, const void *))
sl@0: 
sl@0: @return   The qsort function
sl@0: returns no value.
sl@0: 
sl@0:   The qsort function is a modified partition-exchange sort, or quicksort.
sl@0: 
sl@0:  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.
sl@0: 
sl@0:  The contents of the array base are sorted in ascending order according to
sl@0: a comparison function pointed to by compar, which requires two arguments pointing to the objects being
sl@0: compared.
sl@0: 
sl@0:  The comparison function must return an integer less than, equal to, or
sl@0: greater than zero if the first argument is considered to be respectively
sl@0: less than, equal to, or greater than the second.
sl@0: 
sl@0:  The algorithm implemented by qsort is not stable, that is, if two members compare as equal, their order in
sl@0: the sorted array is undefined.
sl@0: 
sl@0:  The qsort function is an implementation of C.A.R.
sl@0: Hoare's "quicksort"
sl@0: algorithm,
sl@0: a variant of partition-exchange sorting; in particular, see D.E. Knuth Ns's Algorithm Q . Quicksort takes O N lg N average time.
sl@0: 
sl@0: @code
sl@0: 
sl@0: This implementation uses median selection to avoid its O N**2 worst-case behavior.
sl@0: @endcode
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdio.h>
sl@0: #include <stdlib.h>
sl@0: int sort_function( const void *a, const void *b);
sl@0:  
sl@0: int main(void)
sl@0: {
sl@0:    int  x;
sl@0:    int list[5] = {4,2,3,5,1};
sl@0:    qsort((void *)list, 5, sizeof(list[0]), sort_function);
sl@0:    for (x = 0; x < 5; x++)
sl@0:    printf("%d
sl@0: ", list[x]);
sl@0:   
sl@0:    return 0;
sl@0: }
sl@0: int sort_function( const void *a, const void *b)
sl@0: {
sl@0:  int *p1 = (int *)a;
sl@0:  int val1 = *p1;
sl@0:  int *p2 = (int *)b;
sl@0:  int val2 = *p2;
sl@0:  int x = -1;
sl@0:  if(val1  > val2 )
sl@0:    x=1;
sl@0:  if(val1  == val2 )
sl@0:    x=0; 
sl@0:  
sl@0:  return x;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: 1
sl@0: 2
sl@0: 3
sl@0: 4
sl@0: 5
sl@0: 
sl@0: @endcode
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  rand(void)
sl@0: 
sl@0: 
sl@0: Refer to  srand() for the documentation
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  realloc(void *p, size_t nbytes)
sl@0: @param p
sl@0: @param nbytes
sl@0: 
sl@0: Refer to  malloc() for the documentation
sl@0: @see brk()
sl@0: @see mmap()
sl@0: @see getpagesize()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  srand(unsigned seed)
sl@0: @param seed
sl@0: 
sl@0: Note: 
sl@0: 
sl@0: This description also covers the following functions -
sl@0:  rand() 
sl@0: 
sl@0: @return   The rand function
sl@0: never returns return the next pseudo-random number in the sequence. The srand function never returns.
sl@0: 
sl@0:   The rand function computes a sequence of pseudo-random integers in the range
sl@0: of 0 to RAND_MAX (as defined by the header file \#include \<stdlib.h\> ).
sl@0: 
sl@0:  The srand function sets its argument seed as the seed for a new sequence of
sl@0: pseudo-random numbers to be returned by rand. These sequences are repeatable by calling srand with the same seed value.
sl@0: 
sl@0:  If no seed value is provided, the functions are automatically
sl@0: seeded with a value of 1.
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:   int randArray[20];
sl@0:   int i=0;
sl@0:     
sl@0:   while(i<20)
sl@0:   {
sl@0:         randArray[i]=rand();
sl@0:         printf("
sl@0: %d", randArray[i]);
sl@0:         i++;
sl@0:   }
sl@0:  
sl@0:   return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: 16807
sl@0: 282475249
sl@0: 1622650073
sl@0: 984943658
sl@0: 1144108930
sl@0: 470211272
sl@0: 101027544
sl@0: 1457850878
sl@0: 1458777923
sl@0: 2007237709
sl@0: 823564440
sl@0: 1115438165
sl@0: 1784484492
sl@0: 74243042
sl@0: 114807987
sl@0: 1137522503
sl@0: 1441282327
sl@0: 16531729
sl@0: 823378840
sl@0: 143542612
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0: int main( void )
sl@0: {
sl@0:  int seedVal = 45454652;
sl@0:  int randVal;
sl@0:  srand(seedVal);
sl@0:  randVal=rand();
sl@0:  printf("Random Value returned is %d"), randVal);
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: Random Value returned is 1599641479
sl@0: 
sl@0: @endcode
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  strtod(const char *  s, char **  tail)
sl@0: @param s
sl@0: @param tail
sl@0: 
sl@0: Note: 
sl@0: 
sl@0: This description also covers the following functions -
sl@0:  strtof()  strtold() 
sl@0: 
sl@0: @return   The strtod , strtof ,
sl@0: and strtold functions return the converted value, if any. If endptr is not NULL ,
sl@0: a pointer to the character after the last character used
sl@0: 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 
sl@0:   value), and ERANGE is stored in errno . If the correct value would cause underflow a value, of the appropriate 
sl@0:   type, with magnitude is no greater than the smallest normalized positive number 
sl@0:   (KMinTReal in case of Symbian OS) is returned and ERANGE is stored in errno .
sl@0: 
sl@0:   These conversion functions convert the initial portion of the string pointed to by  nptr to double , float , and long double representation, respectively.
sl@0: 
sl@0: The expected form of the string is an optional plus ("+") or minus sign ("-") followed by either:
sl@0: 
sl@0: @code
sl@0: 
sl@0:     * a decimal significand consisting of a sequence of decimal digits optionally containing a decimal-point character, or
sl@0:     * a hexadecimal significand consisting of a "0X" or "0x" followed by a sequence of hexadecimal digits optionally containing a decimal-point character. 
sl@0: @endcode
sl@0: 
sl@0: 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 
sl@0: "p" (for hexadecimal constants), followed by an optional plus or minus sign, followed by a sequence of decimal digits. 
sl@0: 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.
sl@0: 
sl@0: 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.
sl@0: 
sl@0: 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).
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:  char *endpt = NULL;
sl@0:  double d = 0.0;
sl@0:   
sl@0:  d = strtod("0x00e123bhduitri", &endpt;);
sl@0:   
sl@0:  printf("{Expected: 922171.0} %f
sl@0: ", d);
sl@0:  printf("{Expected: \"hduitri\"} %s
sl@0: ", endpt);
sl@0:   
sl@0:  return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: {Expected: 922171.0} 922171.0
sl@0: {Expected: "hduitri"} hduitri
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Limitations:
sl@0: 
sl@0: All these functions don't support the long double length modifiers.
sl@0: 
sl@0: @see atof()
sl@0: @see atoi()
sl@0: @see atol()
sl@0: @see strtol()
sl@0: @see strtoul()
sl@0: @see wcstod()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  strtof(const char *  s, char **  tail)
sl@0: @param s
sl@0: @param tail
sl@0: 
sl@0: Refer to  strtod() for the documentation
sl@0: @see atof()
sl@0: @see atoi()
sl@0: @see atol()
sl@0: @see strtol()
sl@0: @see strtoul()
sl@0: @see wcstod()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  strtol(const char *  nptr, char **  endptr, int base)
sl@0: @param nptr
sl@0: @param endptr
sl@0: @param base
sl@0: 
sl@0: Note: 
sl@0: 
sl@0: This description also covers the following functions -
sl@0:  strtoll()  strtoimax()  strtoq() 
sl@0: 
sl@0: @return   The strtol , strtoll , strtoimax and strtoq functions return the result of the conversion, unless the value 
sl@0:   would underflow or overflow. If no conversion could be performed, 0 is returned 
sl@0:   and the global variable errno is set to EINVAL (the last feature is not portable across all platforms). If 
sl@0:   an overflow or underflow occurs, errno is set to ERANGE and the function return value is clamped according to the following 
sl@0:   table:
sl@0: 
sl@0:  @code
sl@0: 
sl@0:   Function	underflow	overflow 
sl@0: 
sl@0:   strtol        LONG_MIN	LONG_MAX 
sl@0:   strtoll	LLONG_MIN	LLONG_MAX 
sl@0:   strtoimax	INTMAX_MIN	INTMAX_MAX 
sl@0:   strtoq	LLONG_MIN	LLONG_MAX
sl@0: @endcode
sl@0: 
sl@0:   The strtol function
sl@0: converts the string in nptr to a long
sl@0: value.
sl@0: The strtoll function
sl@0: converts the string in nptr to a long long
sl@0: value.
sl@0: The strtoimax function
sl@0: converts the string in nptr to an intmax_t
sl@0: value.
sl@0: The strtoq function
sl@0: converts the string in nptr to a quad_t
sl@0: value.
sl@0: The conversion is done according to the given base ,
sl@0: which must be between 2 and 36 inclusive,
sl@0: or be the special value 0.
sl@0: 
sl@0:  The string may begin with an arbitrary amount of white space
sl@0: (as determined by isspace )
sl@0: followed by a single optional "+"
sl@0: or "-"
sl@0: sign.
sl@0: If base is zero or 16,
sl@0: the string may then include a "0x"
sl@0: prefix,
sl@0: and the number will be read in base 16; otherwise, a zero base is taken as 10 (decimal) unless the next character is "0",
sl@0: in which case it is taken as 8 (octal).
sl@0: 
sl@0:  The remainder of the string is converted to a long , long long , intmax_t
sl@0: or quad_t
sl@0: value in the obvious manner,
sl@0: stopping at the first character which is not a valid digit
sl@0: in the given base.
sl@0: (In bases above 10, the letter "A"
sl@0: in either upper or lower case
sl@0: represents 10, "B"
sl@0: represents 11, and so forth, with "Z"
sl@0: representing 35.)
sl@0: 
sl@0:  If endptr is not NULL , strtol stores the address of the first invalid character in *endptr .
sl@0: If there were no digits at all, however, strtol stores the original value of nptr in *endptr .
sl@0: (Thus, if *nptr is not "\\0"
sl@0: but **endptr is "\\0"
sl@0: on return, the entire string was valid.)
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:   
sl@0: int main( void )
sl@0: {
sl@0:  char *endpt = NULL;
sl@0:  long l = 0;
sl@0:   
sl@0:  l = strtol("0x1236nvbi", &endpt;, 0);
sl@0:   
sl@0:  printf("{Expected: 4662} %ld
sl@0: ", l);
sl@0:  printf("{Expected: \"nvbi\"} %s
sl@0: ", endpt);
sl@0:   
sl@0:  return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: {Expected: 4662} 4662
sl@0: {Expected: "nvbi"} nvbi
sl@0: 
sl@0: @endcode
sl@0: @see atof()
sl@0: @see atoi()
sl@0: @see atol()
sl@0: @see strtod()
sl@0: @see strtoul()
sl@0: @see wcstol()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  strtold(const char *s, char **sp)
sl@0: @param s
sl@0: @param sp
sl@0: 
sl@0: Refer to  strtod() for the documentation
sl@0: @see atof()
sl@0: @see atoi()
sl@0: @see atol()
sl@0: @see strtol()
sl@0: @see strtoul()
sl@0: @see wcstod()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  strtoul(const char *  nptr, char **  endptr, int base)
sl@0: @param nptr
sl@0: @param endptr
sl@0: @param base
sl@0: 
sl@0: Note: 
sl@0: 
sl@0: This description also covers the following functions -
sl@0:  strtoull()  strtoumax()  strtouq() 
sl@0: 
sl@0: @return   The strtoul , strtoull , strtoumax and strtouq functions
sl@0: return either the result of the conversion
sl@0: or, if there was a leading minus sign,
sl@0: the negation of the result of the conversion,
sl@0: unless the original (non-negated) value would overflow;
sl@0: in the latter case, strtoul returns ULONG_MAX , strtoull returns ULLONG_MAX , strtoumax returns UINTMAX_MAX ,
sl@0: and strtouq returns ULLONG_MAX .
sl@0: In all cases, errno is set to ERANGE .
sl@0: If no conversion could be performed, 0 is returned and
sl@0: the global variable errno is set to EINVAL (the last feature is not portable across all platforms).
sl@0: 
sl@0:   The strtoul function
sl@0: converts the string in nptr to an unsigned long
sl@0: value.
sl@0: The strtoull function
sl@0: converts the string in nptr to an unsigned long long
sl@0: value.
sl@0: The strtoumax function
sl@0: converts the string in nptr to an uintmax_t
sl@0: value.
sl@0: The strtouq function
sl@0: converts the string in nptr to a u_quad_t
sl@0: value.
sl@0: The conversion is done according to the given base ,
sl@0: which must be between 2 and 36 inclusive,
sl@0: or be the special value 0.
sl@0: 
sl@0:  The string may begin with an arbitrary amount of white space
sl@0: (as determined by isspace )
sl@0: followed by a single optional "+"
sl@0: or "-"
sl@0: sign.
sl@0: If base is zero or 16,
sl@0: the string may then include a "0x"
sl@0: prefix,
sl@0: and the number will be read in base 16; otherwise, a zero base is taken as 10 (decimal) unless the next character is 'o',
sl@0: in which case it is taken as 8 (octal).
sl@0: 
sl@0:  The remainder of the string is converted to an unsigned long
sl@0: value in the obvious manner,
sl@0: stopping at the end of the string
sl@0: or at the first character that does not produce a valid digit
sl@0: in the given base.
sl@0: (In bases above 10, the letter "A"
sl@0: in either upper or lower case
sl@0: represents 10, "B"
sl@0: represents 11, and so forth, with "Z"
sl@0: representing 35.)
sl@0: 
sl@0:  If endptr is not NULL , strtoul stores the address of the first invalid character in *endptr .
sl@0: If there were no digits at all, however, strtoul stores the original value of nptr in *endptr .
sl@0: (Thus, if *nptr is not "\\0"
sl@0: but **endptr is "\\0"
sl@0: on return, the entire string was valid.)
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:  char *endpt = NULL;
sl@0:  unsigned long ul = 0;
sl@0:   
sl@0:  ul = strtoul("435435hmnb", &endpt;, 12);
sl@0:   
sl@0:  printf("{Expected: 1066793} %ld
sl@0: ", ul);
sl@0:  printf("{Expected: \"hmnb\"} %s
sl@0: ", endpt);
sl@0:   
sl@0:  return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: {Expected: 1066793} 1066793
sl@0: {Expected: "hmnb"} hmnb
sl@0: 
sl@0: @endcode
sl@0: @see strtol()
sl@0: @see wcstoul()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  system(const char *cmd)
sl@0: @param cmd
sl@0: @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.
sl@0: 
sl@0:   The system function
sl@0: spawns another process with the argument cmd. The calling process waits for the child process
sl@0: to finish executing.
sl@0: 
sl@0:  If cmd is a NULL pointer, system will return non-zero to indicate that system is suporrted
sl@0: and zero if it is not supported.
sl@0: 
sl@0:  The system function
sl@0: returns the exit status of the child process as returned by
sl@0: process' exit reason
sl@0: or -1 if an error occurred when spawning a new process.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h> //system
sl@0: #include <stdio.h> //printf
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:    int retVal = -1;
sl@0:   
sl@0:    printf( "Calling system()...
sl@0: " );
sl@0:   
sl@0:    /* helloworld.exe is an executable that just prints
sl@0:     * "Hello world!" and it should be created before
sl@0:     * executing this example code.
sl@0:     */
sl@0:    retVal = system("c:\sys\bin\helloworld.exe");
sl@0:    
sl@0:    /* Print the return value of system() */
sl@0:    printf( "system() returned: %d", retVal );
sl@0:    
sl@0:    return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: Calling system()...
sl@0: system() returned: -1
sl@0: 
sl@0: @endcode
sl@0: @see popen()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  wctomb(char *s, wchar_t wchar)
sl@0: @param s
sl@0: @param wchar
sl@0: @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 
sl@0:   a valid character, or returns the number of bytes that constitute the character 
sl@0:   corresponding to the value of wchar . In no case is value returned greater than the value of the {MB_CUR_MAX} macro.
sl@0: 
sl@0:   The wctomb function converts a wide character wchar into a multibyte character and stores
sl@0: the result in mbchar .
sl@0: The object pointed to by mbchar must be large enough to accommodate the multibyte character, which
sl@0: may be up to MB_LEN_MAX bytes.
sl@0: 
sl@0:  A call with a null mbchar pointer returns nonzero if the current locale requires shift states,
sl@0: zero otherwise;
sl@0: if shift states are required, the shift state is reset to the initial state.
sl@0: 
sl@0:  The behavior of the wctomb is affected by LC_CTYPE category of the current locale.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <wchar.h>
sl@0: /* Illustrates how to use wctomb API */
sl@0: int example_wctomb(wchar_t wc)
sl@0: {
sl@0:  char s[MAX_CUR_MAX];
sl@0:   int len;
sl@0:   
sl@0:   /* represent a wide-char in a single byte*/
sl@0:   len = wctomb(s, wc);
sl@0:   /* return the number of bytes */
sl@0:   return(len);
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Limitations:
sl@0: 
sl@0: The current implementation of wctomb is not affected by the LC_CTYPE category of the current locale.
sl@0: It works only for UTF8 character set.
sl@0: 
sl@0: @see mbtowc()
sl@0: @see wcrtomb()
sl@0: @see wcstombs()
sl@0: @see wctob()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  wcstombs(char *  s, const wchar_t *  pwcs, size_t n)
sl@0: @param s
sl@0: @param pwcs
sl@0: @param n
sl@0: @return   The wcstombs function returns the number of bytes converted (not including 
sl@0: any terminating null), if successful, otherwise it returns ( size_t)(-1) .
sl@0: 
sl@0:   The wcstombs function converts a wide character string wcstring into a multibyte character string, mbstring ,
sl@0: beginning in the initial conversion state.
sl@0: Up to n bytes are stored in mbstring .
sl@0: Partial multibyte characters at the end of the string are not stored.
sl@0: The multibyte character string is null terminated if there is room.
sl@0: 
sl@0:  The behavior of the wcstombs is affected by LC_CTYPE category of the current locale.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <wchar.h>
sl@0: /* Illustrates how to use wcstombs API */
sl@0: size_t example_wcstombs(wchar_t *wcs, char *s, size_t n)
sl@0: {
sl@0:  size_t len;
sl@0:  /* converting multibyte string to a wide-char string */
sl@0:  len = wcstombs(s, (const wchar_t *)wcs, n);
sl@0:  /* returning no of bytes that make up the multibyte sequence */
sl@0:  return (len;);
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Limitations:
sl@0: 
sl@0: The current implementation of wcstombs is not affected by the LC_CTYPE category of the current locale.
sl@0: It works only for UTF8 character set.
sl@0: 
sl@0: @see mbstowcs()
sl@0: @see wcsrtombs()
sl@0: @see wctomb()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  atoll(str) const char *str
sl@0: @param str
sl@0: 
sl@0: Refer to  atol() for the documentation
sl@0: @see atof()
sl@0: @see atoi()
sl@0: @see strtod()
sl@0: @see strtol()
sl@0: @see strtoul()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  llabs(long long j)
sl@0: @param j
sl@0: @return   The llabs function
sl@0: returns the absolue value.
sl@0: 
sl@0:   The llabs function returns the absolute value of j.
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include  <stdio.h>
sl@0: #include  <stdlib.h>
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:    int    ix = -4, iy;
sl@0:    long   lx = -41567L, ly;
sl@0:    long long llx = -5343546758, lly;
sl@0:  
sl@0:    iy = abs( ix );
sl@0:    printf( "The abs value of %d is %d
sl@0: ", ix, iy);
sl@0:  
sl@0:    ly = labs( lx );
sl@0:    printf( "The abs value of %ld is %ld
sl@0: ", lx, ly);
sl@0:  
sl@0:    lly = llabs( llx );
sl@0:    printf( "The abs value of %lld is %lld
sl@0: ", llx, lly );
sl@0:  
sl@0:    return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: The absolute value of -4 is 4
sl@0: The absolute value of -41567 is 41567
sl@0: The absolute value of -5343546758 is 5343546758
sl@0: 
sl@0: @endcode
sl@0: @see abs()
sl@0: @see fabs()
sl@0: @see hypot()
sl@0: @see labs()
sl@0: @see math()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  lldiv(long long numer, long long denom)
sl@0: @param numer
sl@0: @param denom
sl@0: 
sl@0: The  lldiv function computes the value of  numer divided by  denom and returns the stored result in the form of the lldiv_t type.
sl@0: 
sl@0: The lldiv_t type is defined as:
sl@0: @code
sl@0: typedef struct {
sl@0:         long long quot; /* Quotient. */
sl@0:         long long rem;  /* Remainder. */
sl@0: } lldiv_t;
sl@0: @endcode
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0: #include <math.h> /* link to the math lib -libm */
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:  long long numer = pow(2, 40);
sl@0:  long long denom = 3;
sl@0:  
sl@0:  /* call to lldiv */
sl@0:  lldiv_t x = lldiv(-numer, denom);
sl@0:  
sl@0:  printf("Result-> 
sl@0: Quotient = %ld 
sl@0: Remainder = %ld", x.quot, x.rem);
sl@0:                  
sl@0:  long long exp_numer = (denom * x.quot) + x.rem;
sl@0:   
sl@0:  if( exp_numer == (-numer) )
sl@0:     printf("
sl@0: Expected output");  
sl@0:  else
sl@0:     printf("Unexpected output");
sl@0:   
sl@0:  return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: Result->
sl@0: Quotient = -366503875925
sl@0: Remainder = -1
sl@0: Expected output
sl@0: 
sl@0: 
sl@0: @endcode
sl@0: @see div()
sl@0: @see ldiv()
sl@0: @see math()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  strtoll(const char *  nptr, char **  endptr, int base)
sl@0: @param nptr
sl@0: @param endptr
sl@0: @param base
sl@0: 
sl@0: Refer to  strtol() for the documentation
sl@0: @see atof()
sl@0: @see atoi()
sl@0: @see atol()
sl@0: @see strtod()
sl@0: @see strtoul()
sl@0: @see wcstol()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  strtoull(const char *  nptr, char **  endptr, int base)
sl@0: @param nptr
sl@0: @param endptr
sl@0: @param base
sl@0: 
sl@0: Refer to  strtoul() for the documentation
sl@0: @see strtol()
sl@0: @see wcstoul()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn _Exit(int code) 
sl@0: @param code
sl@0: 
sl@0: Refer to  _exit() for the documentation
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  setenv(const char *name, const char *value, int overwrite)
sl@0: @param name
sl@0: @param value
sl@0: @param overwrite
sl@0: 
sl@0: Refer to  getenv() for the documentation
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  unsetenv(const char *name)
sl@0: @param name
sl@0: 
sl@0: Refer to  getenv() for the documentation
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @fn  mkstemp(char *template)
sl@0: @param template
sl@0: @return   The mkstemp function
sl@0: returns -1 if no suitable file could be created
sl@0: and an error code is placed in the global variable. errno.
sl@0: 
sl@0: The mkstemp function
sl@0: takes the given file name template and overwrites a portion of it
sl@0: to create a file with that name and returns a file descriptor
sl@0: opened for reading and writing.
sl@0: This file name is guaranteed not to exist at the time of function invocation
sl@0: and is suitable for use
sl@0: by the application.
sl@0: The template may be any file name with some number of "X s"
sl@0: appended
sl@0: to it, for example
sl@0: @code
sl@0: /tmp/temp.XXXXXX.
sl@0: @endcode
sl@0:  The trailing "X s" are replaced with a
sl@0: unique alphanumeric combination.
sl@0: The number of unique file names mkstemp can return depends on the number of "X s"
sl@0: provided; six "X s"
sl@0: will
sl@0: result in mkstemp selecting one of 56800235584 (62 ** 6) possible temporary file names.
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h> //printf, SEEK_SET
sl@0: #include <unistd.h>
sl@0:  
sl@0: int main( void )
sl@0: {
sl@0:  char arr[] = "c:\someXXXXXXXX";
sl@0:  char buf[10];
sl@0:   
sl@0:  //create a temporary file using mkstemp()
sl@0:  int fd = mkstemp(arr);
sl@0:   
sl@0:  if(fd != -1)
sl@0:  {
sl@0:     //write to the file
sl@0:     write(fd, "hello", 5);
sl@0:     //seek to the beginning of the file
sl@0:     lseek(fd, 0, SEEK_SET); //beg of the file
sl@0:     //read from the file
sl@0:     read(fd, buf, 5);
sl@0:     buf[5] = '\0';
sl@0:     //close the file
sl@0:     close(fd);
sl@0:  }
sl@0:  
sl@0:  printf("buf read: %s", buf);
sl@0:  return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: buf read: hello
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Notes:
sl@0: 
sl@0:  A common problem that results in a core dump is that the programmer passes 
sl@0: 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 
sl@0: the program in question makes heavy use of that type of function call, you do 
sl@0: have the option of compiling the program so that it will store string constants 
sl@0: in a writable segment of memory.
sl@0: @see chmod()
sl@0: @see getpid()
sl@0: @see mkdir()
sl@0: @see open()
sl@0: @see stat()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  mkstemp64(char *template)
sl@0: @param template
sl@0: @return   The mkstemp64 function
sl@0: returns -1 if no suitable file could be created
sl@0: and an error code is placed in the global variable. errno.
sl@0: 
sl@0: 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.
sl@0: The mkstemp64() function is a 64-bit version of mkstemp.
sl@0: This function can be used to create tmp files which can grow more than 32 bit sizes
sl@0: 
sl@0: @see mkstemp()
sl@0:  
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  putenv(const char *string)
sl@0: @param string
sl@0: 
sl@0: Refer to  getenv() for the documentation
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  random(void)
sl@0: 
sl@0: Note: 
sl@0: 
sl@0: This description also covers the following functions -
sl@0:  srandom()  srandomdev()  initstate()  setstate() 
sl@0: 
sl@0: The random function
sl@0: uses a non-linear additive feedback random number generator employing a
sl@0: default table of size 31 long integers to return successive pseudo-random
sl@0: numbers in the range from 0 to
sl@0: (2**(310) -1). The period of this random number generator is very large, approximately
sl@0: 16*(2**(310) -1).
sl@0: 
sl@0:  The random and srandom functions have (almost) the same calling sequence and initialization properties as the rand and srand functions.
sl@0: The difference is that rand produces a much less random sequence  in fact, the low dozen bits
sl@0: generated by rand go through a cyclic pattern.
sl@0: All the bits generated by random are usable.
sl@0: For example, 'random()\&01'
sl@0: will produce a random binary
sl@0: value.
sl@0: 
sl@0:  Like rand random will by default produce a sequence of numbers that can be duplicated
sl@0: by calling srandom with "1"
sl@0: as the seed.
sl@0: 
sl@0:  The srandomdev routine initializes a state array using the random random number device which returns good random numbers,
sl@0: suitable for cryptographic use.
sl@0: Note that this particular seeding
sl@0: procedure can generate states which are impossible to reproduce by
sl@0: calling srandom with any value, since the succeeding terms in the
sl@0: state buffer are no longer derived from the LC algorithm applied to
sl@0: a fixed seed.
sl@0: 
sl@0:  The initstate routine allows a state array, passed in as an argument, to be initialized
sl@0: for future use.
sl@0: The size of the state array (in bytes) is used by initstate to decide how sophisticated a random number generator it should use  the
sl@0: more state, the better the random numbers will be.
sl@0: (Current "optimal" values for the amount of state information are
sl@0: 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
sl@0: the nearest known amount.
sl@0: Using less than 8 bytes will cause an error.)
sl@0: The seed for the initialization (which specifies a starting point for
sl@0: the random number sequence, and provides for restarting at the same
sl@0: point) is also an argument.
sl@0: The initstate function
sl@0: returns a pointer to the previous state information array.
sl@0: 
sl@0:  Once a state has been initialized, the setstate routine provides for rapid switching between states.
sl@0: The setstate function
sl@0: returns a pointer to the previous state array; its
sl@0: argument state array is used for further random number generation
sl@0: until the next call to initstate or setstate.
sl@0: 
sl@0:  Once a state array has been initialized, it may be restarted at a different 
sl@0:   point either by calling initstate (with the desired seed, the state array, and its size) or 
sl@0:   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 
sl@0:   after it is initialized.
sl@0: 
sl@0:  With 256 bytes of state information, the period of the random number generator 
sl@0:   is greater than 2**(690) , which should be sufficient for most purposes.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: //Illustrates how to use srandom API.
sl@0: #include <stdlib.h>
sl@0: void  srandomTest()
sl@0: {
sl@0:        long randNum;
sl@0:        // srandom function call sets its argument as the seed for the new sequence of random integers //generated by  random
sl@0:        srandom(2);
sl@0: // Function call to generate the random number, which will generate the random based on the //argument passed to the srandom function.
sl@0:        randNum = random();
sl@0:        //print the random number generated.
sl@0:        printf("random number is %d",randNum);
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: random number is 1505335290.
sl@0: 
sl@0: @endcode
sl@0: Diagnostics:
sl@0: 
sl@0:  If initstate is called with less than 8 bytes of state information, or if setstate detects that the state information has been garbled, error
sl@0: messages are printed on the standard error output.
sl@0: @see arc4random()
sl@0: @see rand()
sl@0: @see srand()
sl@0: @see random()
sl@0: 
sl@0: Bugs:
sl@0: 
sl@0:  About 2/3 the speed of rand The historical implementation used to have a very weak seeding; the
sl@0: random sequence did not vary much with the seed.
sl@0: The current implementation employs a better pseudo-random number
sl@0: generator for the initial state calculation. Applications requiring cryptographic quality randomness should use arc4random .
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  srandom(unsigned long seed)
sl@0: @param seed
sl@0: 
sl@0: Refer to  random() for the documentation
sl@0: @see arc4random()
sl@0: @see rand()
sl@0: @see srand()
sl@0: @see random()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  realpath(const char *pathname, char resolved_path[])
sl@0: @param pathname
sl@0: @param resolved_path[]
sl@0: @return   The realpath function returns resolved_path on success.
sl@0: If an error occurs, realpath returns NULL, and resolved_path contains the pathname which caused the problem.
sl@0: 
sl@0:   The realpath function resolves all symbolic links, extra "/"
sl@0: characters and references to /./ and /../ in pathname, and copies the resulting absolute pathname into
sl@0: the memory referenced by resolved_path. The resolved_path argument must refer to a buffer capable of storing at least PATH_MAX characters.
sl@0: 
sl@0:  The realpath function will resolve both absolute and relative paths
sl@0: and return the absolute pathname corresponding to pathname. All but the last component of pathname must exist when realpath is called.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include<stdlib.h>
sl@0: #include<stdio.h> //printf
sl@0: #include<sys/stat.h> //S_IWUSR
sl@0: #include<sys/syslimits.h> //PATH_MAX
sl@0: #include<unistd.h> //chdir
sl@0:  
sl@0: int main()
sl@0: {
sl@0:  char resolvepath[PATH_MAX];
sl@0:  FILE *fp = NULL;
sl@0:  char *rpath = NULL;
sl@0:  int isymlink = 0;
sl@0:   
sl@0:  fp = fopen("c:\xyz.txt", "w");
sl@0:  if(!fp)
sl@0:  {
sl@0:      printf("fopen failed!!");
sl@0:      return -1;
sl@0:  }
sl@0:     
sl@0:  mkdir("c:\tmdir", S_IWUSR);
sl@0:   
sl@0:  int c = chdir("c:\");
sl@0:  if(c == -1)
sl@0:  {
sl@0:      printf("chdir failed!!");
sl@0:      return -1;
sl@0:  }
sl@0:   
sl@0:  rpath = realpath(".\tmdir\..\xyz.txt", resolvepath);
sl@0:  printf("resolvepath: %s", resolvepath);
sl@0:  if(rpath != NULL)
sl@0:     printf("rpath: %s", rpath);
sl@0:   
sl@0:  fclose(fp);
sl@0:  rmdir("c:\tmdir");
sl@0:  unlink("c:\xyz.txt");
sl@0:   
sl@0:  mkdir("c:\tdir", S_IWUSR);
sl@0:   
sl@0:  fp = fopen("c:\tdir\xyz.txt", "w");
sl@0:  if(!fp)
sl@0:  {
sl@0:      printf("fopen failed!!");
sl@0:      return -1;
sl@0:  }
sl@0:   
sl@0:  fclose(fp);
sl@0:   
sl@0:  unlink("c:\linkname.txt");
sl@0:     
sl@0:  isymlink = symlink("c:\tdir\xyz.txt", "c:\linkname.txt");
sl@0:  if (isymlink == -1)
sl@0:  {
sl@0:      printf("symlink failed!!");
sl@0:      return -1;
sl@0:  }
sl@0:    
sl@0:  rpath = realpath("c:\linkname.txt", resolvepath);
sl@0:   
sl@0:  printf("resolvepath: %s", resolvepath);
sl@0:  if(rpath != NULL)
sl@0:     printf("rpath: %s", rpath);
sl@0:   
sl@0:  unlink("c:\tdir\xyz.txt");
sl@0:  rmdir("c:\tdir");
sl@0:    
sl@0:  return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: Output
sl@0: 
sl@0: resolvepath: C:\xyz.txt
sl@0: rpath: C:\xyz.txt
sl@0: resolvepath: c:	dir\xyz.txt
sl@0: rpath: c:	dir\xyz.txt
sl@0: 
sl@0: @endcode
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  setstate(char *state)
sl@0: @param state
sl@0: 
sl@0: Refer to  random() for the documentation
sl@0: @see arc4random()
sl@0: @see rand()
sl@0: @see srand()
sl@0: @see random()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  initstate(unsigned long seed, char *state, long n)
sl@0: @param seed
sl@0: @param state
sl@0: @param n
sl@0: 
sl@0: Refer to  random() for the documentation
sl@0: @see arc4random()
sl@0: @see rand()
sl@0: @see srand()
sl@0: @see random()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @fn  getprogname(void)
sl@0: 
sl@0: Refer to  setprogname() for the documentation
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  reallocf(void *ptr, size_t size)
sl@0: @param ptr
sl@0: @param size
sl@0: 
sl@0: Refer to  malloc() for the documentation
sl@0: @see brk()
sl@0: @see mmap()
sl@0: @see getpagesize()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn setprogname(const char *programname)
sl@0: @param programname
sl@0: 
sl@0: These utility functions get and set the current program's name as used by
sl@0: various error-reporting functions.getprogname() returns the name of the current program.
sl@0: This function is typically useful when generating error messages or other diagnostic out-put.
sl@0: If the program name has not been set, getprogname() will return NULL.
sl@0: setprogname() sets the name of the current program to be the last path-name component of the programname argument.
sl@0: It should be invoked at the start of the program, using the argv[0] passed into the program's main() function.
sl@0: A pointer into the string pointed to by the programname argument is kept as the program name.
sl@0: Therefore, the string pointed to by programname should not be modified during the rest of the program's operation.
sl@0: 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.
sl@0: Therefore, in NetBSD, calling setprogname() from main() has no effect.
sl@0: However, it does serve to increase the portability of the program:
sl@0: on other operating systems, getprogname() and setprogname() may be implemented by a portability library, 
sl@0: and a call to setprogname() allows that library to know the program name without modifications to that system's program start-up code.
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  strtoq(const char *nptr, char **endptr, int base)
sl@0: @param nptr
sl@0: @param endptr
sl@0: @param base
sl@0: 
sl@0: Refer to  strtol() for the documentation
sl@0: @see atof()
sl@0: @see atoi()
sl@0: @see atol()
sl@0: @see strtod()
sl@0: @see strtoul()
sl@0: @see wcstol()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  strtouq(const char *nptr, char **endptr, int base)
sl@0: @param nptr
sl@0: @param endptr
sl@0: @param base
sl@0: 
sl@0: Refer to  strtoul() for the documentation
sl@0: @see strtol()
sl@0: @see wcstoul()
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @struct div_t 
sl@0: 
sl@0: Contains the following members
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var div_t::quot
sl@0: quotient
sl@0: */
sl@0: 
sl@0: /** @var div_t::rem
sl@0: remainder
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @struct ldiv_t 
sl@0: 
sl@0: Contains the following members
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var ldiv_t::quot
sl@0: quotient
sl@0: */
sl@0: 
sl@0: /** @var ldiv_t::rem
sl@0: remainder
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @struct lldiv_t 
sl@0: 
sl@0: Contains the following members
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var lldiv_t::quot
sl@0: quotient
sl@0: */
sl@0: 
sl@0: /** @var lldiv_t::rem
sl@0: remainder
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @def EXIT_FAILURE 
sl@0: 
sl@0: These are arguments for the exit and _exit functions and the return values for the atexit and _onexit functions.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @def EXIT_SUCCESS 
sl@0: 
sl@0: These are arguments for the exit and _exit functions and the return values for the atexit and _onexit functions.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @def  RAND_MAX
sl@0: 
sl@0: The constant RAND_MAX is the maximum value that can be returned by the rand function.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: /** @def MB_CUR_MAX 
sl@0: 
sl@0: The value of MB_CUR_MAX is the maximum number of bytes in a multibyte character for the current locale.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: