wctomb(char *,wchar_t) in P.I.P.S. Open_Environment

Interface status:

externallyDefinedApi

EXIT_FAILURE 1

Description

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

Interface status:

externallyDefinedApi

EXIT_SUCCESS 0

Description

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

Interface status:

externallyDefinedApi

RAND_MAX 0x7fffffff

Description

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

Interface status:

externallyDefinedApi

MB_CUR_MAX 4

Description

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

Interface status:

externallyDefinedApi

IMPORT_C void abort(void);

Description

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:

#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;
}

Output

Error occurred while opening file: No such file or directory

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.

Description

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

Examples:

#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;
}

Output

The absolute value of -4 is 4
The absolute value of -41567 is 41567
The absolute value of -5343546758 is 5343546758

Parameters

int

Return value

int

The abs function returns the absolute value.

Description

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(int)exit(int) is specified explicitly.

Limitation: atexit(void(*)(void))atexit(void(*)(void)) is not supported on emulator.

Examples:

#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 " );
}

Output

Before exiting...
fun4
fun3
fun2
fun1

#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

Parameters

void(*)(void)

Return value

int

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.

Description

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

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

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

Examples:

#include <stdlib.h>
#include <stdio.h>
 
void main( void )
{
 /* Test of atof */
 double d = atof("  86778E-2");
 
 printf( "result of atof: %f
", d );
}

Output
result of atof: 867.78

Implementation notes:

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

Parameters

const char *

Return value

double

The atof function returns the converted value if the value can be represented.

Description

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

 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 );
}

Output
result of atoi: -56957

Implementation notes:

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

Parameters

const char *

Return value

int

The atoi function returns the converted value if the value can be represented.

Description

This description also covers the following functions - atoll(const char *)

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

It is equivalent to:

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

The atoll function converts the initial portion of the string pointed to by nptr to long long integer representation. It is equivalent to:

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

Examples:

#include <stdlib.h>
#include <stdio.h>
 
void main( void )
{
 /* call to atol */
 long l = atol( "-000002344" );
 
 printf( "result of atol: %ld
", l );
}

Output

result of atol: -2344

# 414 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2
# 415 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2
 
void main( void )
{
 /* call to atoll */
 long long l = atoll("454756356bs");
 
 printf( "result of atoll: %ld
", l );
}

Output

result of atoll: 454756356

Parameters

const char *

Note:

Return value

long

The atol and atoll functions return the converted value if the value can be represented.

Description

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:

#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;
}

Output

element found: 7

Parameters

`const void *`
`const void *`
`size_tsize_t`
`size_tsize_t`
`int()(const void , const void *)`

Description

Parameters

`size_tsize_t`
`size_tsize_t`	Refer to `malloc(size_t)malloc(size_t)` for the documentation

Description

The div function computes the value num/denom and returns the quotient and remainder in a structure named div_tdiv_t that contains two int members named quot and rem.

Examples:

#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; 
}

Output

Result->
Quotient = 4
Remainder = -2
Result is same as the expected output

Parameters

`int`
`int`

Return value

div_tdiv_t

The div function returns a structure of type div_tdiv_t that contains two int members named quot (quotient) and rem (remainder).

Description

Parameters

void *

Refer to malloc(size_t)malloc(size_t) for the documentation

Description

This description also covers the following functions - setenv(const char *,const char *,int)setenv(const char *,const char *,int) putenv(const char *)putenv(const char *) unsetenv(const char *)unsetenv(const char *)

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:

#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 !=  0  )
      printf( "new PATH variable is: %s
", psc );
 
  return 0;
}

Output

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

# 709 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2 //setenv, getenv
# 710 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2 //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 !=  0  )
      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 !=  0  )
      printf( "new HOME variable is: %s
", var );
     
   return 0;
}

Output

new HOME variable is: \home
new HOME variable is: \check

Parameters

const char *

Note:

Return value

char *

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.

Interface status:

externallyDefinedApi

IMPORT_C long labs(long);

Description

The labs function returns the absolute value of the long integer j.

Examples:

#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;
}

Output

The absolute value of -4 is 4
The absolute value of -41567 is 41567
The absolute value of -5343546758 is 5343546758

Parameters

long

Return value

long

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

Description

The ldiv function computes the value num / denom and returns the quotient and remainder in a structure named ldiv_tldiv_t that contains two long members named quot and rem.

Examples:

#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;
}

Output

Result->
Quotient = 4
Remainder = -1
Result is same as the expected output

Parameters

`long`
`long`

Return value

ldiv_tldiv_t

The ldiv function returns a structure of type ldiv_tldiv_t that contains two long members named quot (quotient) and rem (remainder).

Description

This description also covers the following functions - calloc(size_t,size_t)calloc(size_t,size_t) realloc(void *,size_t)realloc(void *,size_t) reallocf(void *,size_t)reallocf(void *,size_t) free(void *)free(void *)

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:

#include <stdlib.h>    //malloc
#include <stdio.h>    //printf
  
int main( void )
{
   /* allocate memory */
   char  *pc = (char *)malloc( sizeof(char) * 3);
   
   if( pc ==  0  )
      printf( "memory insufficient
" );
   else
   {
      printf( "memory allocated
" );
      free( pc );
      printf( "memory freed
" );
   }
  
   return 0;
}

Output

memory allocated
memory freed

# 947 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2 //printf
# 948 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2 //calloc
   
int main( void )
{
   int  *pint = (int *)calloc(2, sizeof (int) * 2);
   if( pint !=  0  )
      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;
}

Output

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

# 973 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2 //printf
# 974 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2 //realloc
 
int main( void )
{
 int  *pint = (int *)calloc(2, sizeof (int) * 2);
 if (pint ==  0 )
  {
  printf("calloc failed to allocate memory
");
  return -1;
  }
 else
  {
  printf("calloc allocated memory: 128 bytes
");
  }
 
 pint = (int *)realloc(pint, (sizeof (int) * 6) );
 if (pint ==  0 )
  {
  printf("realloc failed to allocate memory
");
  return -1;
  }
 else
  {
  printf("realloc allocated memory: 192 bytes
");
  }
  
  free( pint );
  return 0;
}

Output

calloc allocated memory: 128 bytes
realloc allocated memory: 192 bytes

Parameters


                                 				size_tsize_t

Note:

Description

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:

#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,  4 );
 if(len == -1)
 {
        wprintf(L"mblen returned error!!
");
 }
 /* return the no of bytes */
 return(len);
}

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.

Parameters

`const char *`
`size_tsize_t`

Return value

int

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.

Description

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:

#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);
}

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.

Parameters

`wchar_twchar_t *`
`const char *`
`size_tsize_t`

Return value

size_tsize_t

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.

Description

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:

#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,  4 );
 /* checking for error */
 if(len < 0)
 {
        wprintf(L"mbtowc returned error!!
");
 }
 /* returning no of bytes consumed */
 return (len;);
}

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.

Parameters

`wchar_twchar_t *`
`const char *`
`size_tsize_t`

Return value

int

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.

Description

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 E. Knuth Ns's Algorithm Q . Quicksort takes O N lg N average time.

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

Examples:

#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;
}

Output

1
2
3
4
5

Parameters

`void *`
`size_tsize_t`
`size_tsize_t`
`int()(const void , const void *)`

Interface status:

externallyDefinedApi

IMPORT_C int rand(void);

Description

Refer to srand(unsigned)srand(unsigned) for the documentation

Return value

int

Interface status:

externallyDefinedApi

IMPORT_C void* realloc(void *, size_t);

Description

Parameters

`void *`
`size_tsize_t`	Refer to `malloc(size_t)malloc(size_t)` for the documentation

Description

This description also covers the following functions - rand(void)rand(void)

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:

#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;
}

#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);
}

Output

Random Value returned is 1599641479

Parameters

unsigned

Note:

Interface status:

externallyDefinedApi

IMPORT_C double strtod(const char *, char **);

Description

This description also covers the following functions - strtof(const char *,char **)strtof(const char *,char **) strtold(const char *,char **)strtold(const char *,char **)

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:

 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.

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:

#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;
}

Output

{Expected: 922171.0} 922171.0
{Expected: "hduitri"} hduitri

Limitations:

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

Parameters

`const char *`
`char **`	Note:

Return value

double

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 .

Description

Parameters

`const char *`
`char **`	Refer to `strtod(const char ,char )strtod(const char ,char **)` for the documentation

Return value

float

Description

This description also covers the following functions - strtoll(const char *,char **,int)strtoll(const char *,char **,int) strtoimax(const char *,char **,int) strtoq(const char *,char **,int)strtoq(const char *,char **,int)

  Function    underflow   overflow 

  strtol        LONG_MIN  LONG_MAX 
  strtoll LLONG_MIN  LLONG_MAX 
  strtoimax   INTMAX_MIN   INTMAX_MAX 
  strtoq  LLONG_MIN LLONG_MAX

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:

#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;
}

Output

{Expected: 4662} 4662
{Expected: "nvbi"} nvbi

Parameters

`const char *`
`char **`
`int`	Note:

Return value

long

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:

Description

Parameters

`const char *`
`char **`	Refer to `strtod(const char ,char )strtod(const char ,char **)` for the documentation

Return value

long double

Description

This description also covers the following functions - strtoull(const char *,char **,int)strtoull(const char *,char **,int) strtoumax(const char *,char **,int) strtouq(const char *,char **,int)strtouq(const char *,char **,int)

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:

#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;
}

Output

{Expected: 1066793} 1066793
{Expected: "hmnb"} hmnb

Parameters

`const char *`
`char **`
`int`	Note:

Return value

unsigned long

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

Description

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:

#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;
}

Output

Calling system()...
system() returned: -1

Parameters

const char *

Return value

int

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.

Description

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:

#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);
}

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.

Parameters

`char *`
`wchar_twchar_t`

Return value

int

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.

Description

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:

#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;);
}

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.

Parameters

`char *`
`const wchar_twchar_t *`
`size_tsize_t`

Return value

size_tsize_t

The wcstombs function returns the number of bytes converted (not including any terminating null), if successful, otherwise it returns ( size_t)(-1) .

Description

The llabs function returns the absolute value of j.

Examples:

#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;
}

Output

The absolute value of -4 is 4
The absolute value of -41567 is 41567
The absolute value of -5343546758 is 5343546758

Parameters

long long

Return value

long long

The llabs function returns the absolue value.

Description

The lldiv_tlldiv_t type is defined as:

typedef struct {
        long long quot; /* Quotient. */
        long long rem;  /* Remainder. */
} lldiv_t;

Examples:

# 1947 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2
# 1948 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2
# 1949 "d:/EPOC/release/9.4/common/generic/openenv/core/include/stdlib.dosc" 2 /* 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;
}

Output

Result->
Quotient = -366503875925
Remainder = -1
Expected output

Parameters

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

Return value

lldiv_tlldiv_t

Description

Parameters

`const char *`
`char **`
`int`	Refer to `strtol(const char ,char ,int)strtol(const char ,char **,int)` for the documentation

Return value

long long

Description

Parameters

`const char *`
`char **`
`int`	Refer to `strtoul(const char ,char ,int)strtoul(const char ,char **,int)` for the documentation

Return value

unsigned long long

Description

Parameters

int

Refer to _exit(int) for the documentation

Interface status:

externallyDefinedApi

IMPORT_C int setenv(const char *, const char *, int);

Description

Parameters

`const char *`
`const char *`
`int`	Refer to `getenv(const char )getenv(const char )` for the documentation

Return value

int

Interface status:

externallyDefinedApi

IMPORT_C void unsetenv(const char *);

Description

Parameters

const char *

Refer to getenv(const char *)getenv(const char *) for the documentation

Interface status:

externallyDefinedApi

IMPORT_C int mkstemp(char *);

Description

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 /tmp/temp.XXXXXX. 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.

Errors:

The mkstemp function may set errno to one of the following values: [ENOTDIR] The pathname portion of the template is not an existing directory. The mkstemp function may also set errno to any value specified by the stat function. The mkstemp function may also set errno to any value specified by the open function.

Examples:

#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;
}

Output

buf read: hello

Limitations:

The template parameter of the mkstemp(char *)mkstemp(char *) function should not exceed 256 characters in length.

Parameters

char *

Return value

int

The mkstemp function returns -1 if no suitable file could be created and an error code is placed in the global variable. errno.

Interface status:

externallyDefinedApi

IMPORT_C int putenv(const char *);

Description

Parameters

const char *

Refer to getenv(const char *)getenv(const char *) for the documentation

Return value

int

Interface status:

externallyDefinedApi

IMPORT_C long random(void);

Description

Note:

This description also covers the following functions - srandom(unsigned)srandom(unsigned) srandomdev() initstate(unsigned,char *,long)initstate(unsigned,char *,long) setstate(char *)setstate(char *)

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:

//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);
}

Output

random number is 1505335290.

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

Return value

long

Description

Parameters

unsigned long

Refer to random(void)random(void) for the documentation

Description

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:

#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;
}

Output

resolvepath: C:\xyz.txt
rpath: C:\xyz.txt
resolvepath: c:    dir\xyz.txt
rpath: c:  dir\xyz.txt

Parameters

`const char *`
`char resolved_path`

Return value

char *

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.

Interface status:

externallyDefinedApi

IMPORT_C char* setstate(char *);

Description

Parameters

char *

Refer to random(void)random(void) for the documentation

Return value

char *

Description

Parameters

`unsigned long`
`char *`
`long`	Refer to `random(void)random(void)` for the documentation

Return value

char *

Description

Refer to setprogname(const char *)setprogname(const char *) for the documentation

Return value

const char *

Interface status:

externallyDefinedApi

IMPORT_C void* reallocf(void *, size_t);

Description

Parameters

`void *`
`size_tsize_t`	Refer to `malloc(size_t)malloc(size_t)` for the documentation

Description

Parameters

const char *

These utility functions get and set the current program's name as used by various error-reporting getprogname(void)getprogname(void) 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(void)getprogname(void) will return NULL. setprogname(const char *)setprogname(const char *) 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(int,char *,char *) 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(int,char *,char *) is called. Therefore, in NetBSD, calling setprogname(const char *)setprogname(const char *) from main(int,char *,char *) has no effect. However, it does serve to increase the portability of the program: on other operating systems, getprogname(void)getprogname(void) and setprogname(const char *)setprogname(const char *) may be implemented by a portability library, and a call to setprogname(const char *)setprogname(const char *) allows that library to know the program name without modifications to that system's program start-up code.

Interface status:

externallyDefinedApi

IMPORT_C __int64_t strtoq(const char *, char **, int);

Description

Parameters

`const char *`
`char **`
`int`	Refer to `strtol(const char ,char ,int)strtol(const char ,char **,int)` for the documentation

Return value

__int64_t

Description

Parameters

`const char *`
`char **`
`int`	Refer to `strtoul(const char ,char ,int)strtoul(const char ,char **,int)` for the documentation

Return value

__uint64_t

EXIT_FAILURE

Description

EXIT_SUCCESS

Description

RAND_MAX

Description

MB_CUR_MAX

Description

abort(void)

Description

See also:

abs(int)

Description

Parameters

Return value

See also:

atexit(void(*)(void))

Description

Parameters

Return value

See also:

atof(const char *)

Description

Parameters

Return value

See also:

atoi(const char *)

Description

Parameters

Return value

See also:

atol(const char *)

Description

Parameters

Return value

See also:

bsearch(const void *,const void *,size_t,size_t,int(*)(const void *, const void *))

Description

Parameters

See also:

calloc(size_t,size_t)

Description

Parameters

See also:

div(int,int)

Description

Parameters

Return value

See also:

free(void *)

Description

Parameters

See also:

getenv(const char *)

Description

Parameters

Return value

labs(long)

Description

Parameters

Return value

See also:

ldiv(long,long)

Description

Parameters

Return value

See also:

malloc(size_t)

Description

Parameters

See also:

mblen(const char *,size_t)

Description

Parameters

Return value

See also:

mbstowcs(wchar_t *,const char *,size_t)

Description

Parameters

Return value

`EXIT_FAILURE`

`EXIT_SUCCESS`

`RAND_MAX`

`MB_CUR_MAX`

`abort(void)`

`abs(int)`

`atexit(void(*)(void))`

`atof(const char *)`

`atoi(const char *)`

`atol(const char *)`

`bsearch(const void ,const void ,size_t,size_t,int()(const void , const void *))`

`calloc(size_t,size_t)`

`div(int,int)`

`free(void *)`

`getenv(const char *)`

`labs(long)`

`ldiv(long,long)`

`malloc(size_t)`

`mblen(const char *,size_t)`

`mbstowcs(wchar_t ,const char ,size_t)`

`mbtowc(wchar_t ,const char ,size_t)`

`qsort(void ,size_t,size_t,int()(const void , const void ))`

`rand(void)`

`realloc(void *,size_t)`

`srand(unsigned)`

`strtod(const char *,char **)`

`strtof(const char *,char **)`

`strtol(const char *,char **,int)`

`strtold(const char *,char **)`

`strtoul(const char *,char **,int)`

`system(const char *)`

`wctomb(char *,wchar_t)`

`wcstombs(char ,const wchar_t ,size_t)`

`llabs(long)`

`lldiv(long,long)`

`strtoll(const char *,char **,int)`