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

     2 @internalComponent

     3 */

     4 

     5 /** @fn  abort(void)

     6 

     7 @return   The abort function

     8 never returns.

     9 

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

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

    12 

    13  Any open streams are flushed and closed.

    14 

    15 Examples:

    16 @code

    17 #include  <stdio.h>

    18 #include  <stdlib.h>

    19  

    20 int main( void )

    21 {

    22    FILE *stream;

    23  

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

    25    {

    26       perror( "Error occurred while opening file" );

    27       abort();

    28    }

    29    else

    30       fclose( stream );

    31    return 0;

    32 }

    33 

    34 @endcode

    35 

    36  Output

    37 @code

    38 Error occurred while opening file: No such file or directory

    39 

    40 @endcode

    41   

    42 Implementation notes: 

    43   

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

    45 

    46 Limitations:

    47 

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

    49 as there is no support for signals from Symbian OS.

    50 

    51 @see exit()

    52  

    53 

    54 @publishedAll

    55 @externallyDefinedApi

    56 */

    57 

    58 /** @fn  abs(int j)

    59 @param j

    60 @return   The abs function

    61 returns

    62 the absolute value.

    63 

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

    65 

    66 

    67 

    68 Examples:

    69 @code

    70 #include  <stdio.h>

    71 #include  <stdlib.h>

    72  

    73 int main( void )

    74 {

    75    int    ix = -4, iy;

    76    long   lx = -41567L, ly;

    77    long long llx = -5343546758, lly;

    78  

    79    iy = abs( ix );

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

    81 ", ix, iy);

    82  

    83    ly = labs( lx );

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

    85 ", lx, ly);

    86  

    87    lly = llabs( llx );

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

    89 ", llx, lly );

    90  

    91    return 0;

    92 }

    93 

    94 @endcode

    95  

    96 @code

    97 Output

    98 

    99 The absolute value of -4 is 4

   100 The absolute value of -41567 is 41567

   101 The absolute value of -5343546758 is 5343546758

   102 

   103 @endcode

   104 @see fabs()

   105 @see floor()

   106 @see hypot()

   107 @see labs()

   108 @see llabs()

   109 @see math()

   110  

   111 

   112 @publishedAll

   113 @externallyDefinedApi

   114 */

   115 

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

   117 @param func

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

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

   120 

   121   The atexit function

   122 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;

   123 no arguments are passed.

   124 

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

   126   function, the _exit function should be used. Alternatively, 

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

   128 

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

   130   as sufficient memory can be allocated.

   131 

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

   133 

   134 Limitation:

   135 atexit() is not supported on emulator.

   136 

   137 Examples:

   138 @code

   139 #include <stdlib.h>

   140 #include <stdio.h>

   141  

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

   143  

   144 int main( void )

   145 {

   146    atexit( fun1 );

   147    atexit( fun2 );

   148    atexit( fun3 );

   149    atexit( fun4 );

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

   151 }

   152  

   153 void fun1()

   154 {

   155    printf( " fun1 " );

   156 }

   157  

   158 void fun2()

   159 {

   160    printf( " fun2" );

   161 }

   162  

   163 void fun3()

   164 {

   165    printf( " fun3 " );

   166 }

   167  

   168 void fun4()

   169 {

   170    printf( " fun4 " );

   171 }

   172 

   173 @endcode

   174 @code

   175 Output

   176 

   177 Before exiting...

   178 fun4

   179 fun3

   180 fun2

   181 fun1

   182 

   183 @endcode

   184 

   185 @code

   186 #include <stdlib.h>

   187 #include <stdio.h>

   188 #include <e32base.h>

   189 

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

   191 

   192 LOCAL_C int MainL()

   193 	{

   194 	atexit( fun1 );

   195    	atexit( fun2 );

   196    	atexit( fun3 );

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

   198   	getchar();

   199 	exit();

   200 	}

   201 

   202 

   203 void fun1()

   204 {

   205 printf( " fun1\n " );

   206 getchar();

   207 }

   208  

   209 void fun2()

   210 {

   211 printf( " fun2\n " );

   212 getchar();

   213 }

   214  

   215 void fun3()

   216 {

   217 printf( " fun3\n " );

   218 getchar();

   219 }

   220 

   221 

   222 GLDEF_C TInt E32Main()

   223 	{

   224 	__UHEAP_MARK;

   225 	CTrapCleanup* cleanup = CTrapCleanup::New();

   226 	if(cleanup == NULL)

   227 		{

   228 		return KErrNoMemory;

   229 		}

   230 	TInt ret;

   231 	TRAPD(err,ret = MainL());

   232 

   233 	delete cleanup;

   234 	__UHEAP_MARKEND;

   235 	return KErrNone;

   236    	}

   237 

   238 @encode

   239 

   240 @code

   241 Output

   242 

   243 Before exiting...

   244 

   245 fun3

   246 fun2

   247 fun1

   248 

   249 @endcode

   250 

   251 @see exit()

   252  

   253 

   254 @publishedAll

   255 @externallyDefinedApi

   256 */

   257 

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

   259 @param nptr

   260 @return   The atof function

   261 returns

   262 the converted value if the value can be represented.

   263 

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

   265 representation.

   266 

   267 @code

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

   269 

   270 The decimal point

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

   272 @endcode

   273 

   274 

   275 Examples:

   276 @code

   277 #include <stdlib.h>

   278 #include <stdio.h>

   279  

   280 void main( void )

   281 {

   282  /* Test of atof */

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

   284  

   285  printf( "result of atof: %f

   286 ", d );

   287 }

   288 

   289 @endcode

   290 

   291 @code

   292 Output

   293 result of atof: 867.78

   294 

   295 @endcode

   296 

   297 Implementation notes:

   298   

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

   300 

   301 @see atoi()

   302 @see atol()

   303 @see strtod()

   304 @see strtol()

   305 @see strtoul()

   306  

   307 

   308 @publishedAll

   309 @externallyDefinedApi

   310 */

   311 

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

   313 @param nptr

   314 @return   The atoi function

   315 returns

   316 the converted value if the value can be represented.

   317 

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

   319 representation.

   320 

   321 @code

   322 

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

   324 @endocde

   325 

   326 

   327 Examples:

   328 @code

   329 #include <stdlib.h>

   330 #include <stdio.h>

   331  

   332 void main( void )

   333 {

   334   /* call to atoi */

   335   char *str = "  -56957jdhfjk";    

   336   int i = atoi( str );

   337   printf( "result of atoi: %d

   338 ", i );

   339 }

   340 

   341 @endcode

   342 

   343 @code

   344 Output

   345 result of atoi: -56957

   346 

   347 @endcode

   348 

   349 Implementation notes:

   350   

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

   352 

   353 @see atof()

   354 @see atol()

   355 @see strtod()

   356 @see strtol()

   357 @see strtoul()

   358  

   359 

   360 @publishedAll

   361 @externallyDefinedApi

   362 */

   363 

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

   365 @param nptr

   366 

   367 Note: 

   368 

   369 This description also covers the following functions -

   370  atoll() 

   371 

   372 @return   The atol and atoll functions

   373 return

   374 the converted value if the value can be represented.

   375 

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

   377 integer

   378 representation.

   379 

   380  It is equivalent to:

   381 

   382 @code

   383 

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

   385 @endcode

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

   387 integer representation. It is equivalent to:    

   388 @code

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

   390 @endcode

   391 

   392 Examples:

   393 @code

   394 #include <stdlib.h>

   395 #include <stdio.h>

   396  

   397 void main( void )

   398 {

   399  /* call to atol */

   400  long l = atol( "-000002344" );

   401  

   402  printf( "result of atol: %ld

   403 ", l );

   404 }

   405 @endcode

   406 

   407 @code

   408 Output

   409 

   410 result of atol: -2344

   411 

   412 @endcode

   413 @code

   414 #include <stdlib.h>

   415 #include <stdio.h>

   416  

   417 void main( void )

   418 {

   419  /* call to atoll */

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

   421  

   422  printf( "result of atoll: %ld

   423 ", l );

   424 }

   425 

   426 @endcode

   427 

   428 @code

   429 Output

   430 

   431 result of atoll: 454756356

   432 

   433 @endcode

   434 @see atof()

   435 @see atoi()

   436 @see strtod()

   437 @see strtol()

   438 @see strtoul()

   439  

   440 

   441 @publishedAll

   442 @externallyDefinedApi

   443 */

   444 

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

   446 @param key

   447 @param base

   448 @param nmemb

   449 @param size

   450 @param compar

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

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

   453 the result is unspecified.

   454 

   455   The bsearch function searches an array of nmemb objects, the initial member of which is

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

   457 

   458  The contents of the array should be in ascending sorted order according to 

   459   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 

   460   less than, equal to, or greater than zero if the key object is found, respectively, to be less than, to match, or be 

   461   greater than the array member.

   462 

   463 Examples:

   464 @code

   465 #include<stdlib.h>

   466 #include<stdio.h>

   467  

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

   469 {

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

   471 }

   472  

   473 int main()

   474 {

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

   476 int key = 7;

   477 int i = 5;

   478  

   479 int *ele;

   480  

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

   482  

   483 if (ele != NULL)

   484         printf("

   485 element found: %d", *ele);

   486 else

   487         printf("

   488 element not found");

   489 return 0;

   490 }

   491 

   492 @endcode

   493 @code

   494 Output

   495 

   496 element found: 7

   497 

   498 @endcode

   499 @see qsort()

   500  

   501 

   502 @publishedAll

   503 @externallyDefinedApi

   504 */

   505 

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

   507 @param number

   508 @param size

   509 

   510 Refer to  malloc() for the documentation

   511 @see brk()

   512 @see mmap()

   513 @see getpagesize()

   514  

   515 

   516 @publishedAll

   517 @externallyDefinedApi

   518 */

   519 

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

   521 @param num

   522 @param denom

   523 @return   The div function

   524 returns a structure of type div_t that contains two int

   525 members named quot (quotient)

   526 and rem (remainder).

   527 

   528   The div function

   529 computes the value num/denom and returns the quotient and remainder in a structure named div_t that contains two int

   530 members named quot and rem.

   531 

   532 Examples:

   533 @code

   534 #include <stdlib.h>

   535 #include <stdio.h>

   536  

   537 void main( void )

   538 {

   539  int numer = -14;

   540  int denom = -3;

   541  int exp_numer = 0;

   542     

   543  /* call to div */

   544  div_t x = div(numer, denom);

   545  

   546  printf("Result->

   547  Quotient = %d

   548  Remainder = %d

   549 ", x.quot, x.rem);

   550                 

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

   552  

   553  if( exp_numer == (numer) )

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

   555  else

   556     printf("Unexpected output");

   557     

   558  return 0; 

   559 }

   560 

   561 @endcode

   562 @code

   563 Output

   564 

   565 Result->

   566 Quotient = 4

   567 Remainder = -2

   568 Result is same as the expected output

   569 

   570 @endcode

   571 @see ldiv()

   572 @see lldiv()

   573  

   574 

   575 @publishedAll

   576 @externallyDefinedApi

   577 */

   578 

   579 /** @fn  exit(int status)

   580 @param status

   581 

   582 Note: 

   583 

   584 This description also covers the following functions -

   585  _Exit() 

   586 

   587 @return   The exit and _Exit functions

   588 never return.

   589 

   590  The  exit and  _Exit functions terminate a process.

   591 

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

   593 

   594 @code

   595 

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

   597    2. Flush all open output streams.

   598    3. Close all open streams.

   599    4. Unlink all files created with the tmpfile function. 

   600 @endcode

   601 

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

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

   604 

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

   606 Cooperating processes may use other values.

   607 

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

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

   610 

   611 Examples:

   612 @code

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

   614 #include <stdlib.h>

   615  

   616 void main()

   617 {

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

   619 }

   620 

   621 @endcode

   622 @see _exit()

   623 @see wait()

   624 @see atexit()

   625 @see tmpfile()

   626  

   627 

   628 @publishedAll

   629 @externallyDefinedApi

   630 */

   631 

   632 /** @fn  free(void *p)

   633 @param p

   634 

   635 Refer to  malloc() for the documentation

   636 @see brk()

   637 @see mmap()

   638 @see getpagesize()

   639  

   640 

   641 @publishedAll

   642 @externallyDefinedApi

   643 */

   644 

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

   646 @param name

   647 

   648 Note: 

   649 

   650 This description also covers the following functions -

   651  setenv()  putenv()  unsetenv() 

   652 

   653 @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 

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

   655 

   656 These functions set, unset and fetch environment variables from the

   657 host environment list.

   658 For compatibility with differing environment conventions,

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

   660 respectively,

   661 with an equal sign "="

   662 

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

   664 

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

   666 If the variable name does not exist in the list,

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

   668 zero, the

   669 variable is not reset, otherwise it is reset

   670 to the given value.

   671 

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

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

   674 

   675  The unsetenv function

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

   677 

   678 Examples:

   679 @code

   680 #include <stdlib.h> //getenv

   681 #include <stdio.h> //printf

   682  

   683 int main( void )

   684 {

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

   686  

   687   if( iret == -1)

   688      printf( "putenv() failed!!

   689 " );

   690  

   691    /* fetch new value. */

   692   char *psc = getenv("PATH");

   693  

   694   if( psc != NULL )

   695       printf( "new PATH variable is: %s

   696 ", psc );

   697  

   698   return 0;

   699 }

   700 

   701 @endcode

   702 @code

   703 Output

   704 

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

   706 

   707 @endcode

   708 @code

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

   710 #include <stdio.h> //printf

   711  

   712 int main( void )

   713 {

   714    char *var;

   715  

   716    /* Unset the value of the HOME environment variable

   717     * to make sure that it is non-existing.

   718     */

   719    unsetenv( "HOME" );

   720  

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

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

   723     

   724    if(iret == -1)

   725       printf( "Setenv failed!!" );

   726     

   727    /* Get new value. */

   728    var = getenv( "HOME" );

   729  

   730    if( var != NULL )

   731       printf( "new HOME variable is: %s

   732 ", var );

   733     

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

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

   736     

   737    /* Get new value. */

   738    var = getenv( "HOME" );

   739  

   740    if( var != NULL )

   741       printf( "new HOME variable is: %s

   742 ", var );

   743      

   744    return 0;

   745 }

   746 

   747 @endcode

   748 @code

   749 Output

   750 

   751 new HOME variable is: \home

   752 new HOME variable is: \check

   753 

   754 @endcode

   755  

   756 

   757 @publishedAll

   758 @externallyDefinedApi

   759 */

   760 

   761 /** @fn  labs(long j)

   762 @param j

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

   764 

   765  The labs function

   766 returns the absolute value of the long integer j.

   767 

   768 

   769 

   770 Examples:

   771 @code

   772 #include  <stdio.h>

   773 #include  <stdlib.h>

   774  

   775 int main( void )

   776 {

   777    int    ix = -4, iy;

   778    long   lx = -41567L, ly;

   779    long long llx = -5343546758, lly;

   780  

   781    iy = abs( ix );

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

   783 ", ix, iy);

   784  

   785    ly = labs( lx );

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

   787 ", lx, ly);

   788  

   789    lly = llabs( llx );

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

   791 ", llx, lly );

   792  

   793    return 0;

   794 }

   795 

   796 @endcode

   797 @code

   798 Output

   799 

   800 The absolute value of -4 is 4

   801 The absolute value of -41567 is 41567

   802 The absolute value of -5343546758 is 5343546758

   803 

   804 @endcode

   805 @see abs()

   806 @see floor()

   807 @see llabs()

   808 @see math()

   809  

   810 

   811 @publishedAll

   812 @externallyDefinedApi

   813 */

   814 

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

   816 @param num

   817 @param denom

   818 @return   The ldiv function

   819 returns a structure of type ldiv_t that contains two long

   820 members named quot (quotient)

   821 and rem (remainder).

   822 

   823   The ldiv function

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

   825 that contains two long

   826 members named quot and rem.

   827 

   828 Examples:

   829 @code

   830 #include <stdlib.h>

   831 #include <stdio.h>

   832  

   833 int main( void )

   834 {

   835  long numer = 13;

   836  long denom = -3;

   837  

   838  /* call to ldiv */

   839  ldiv_t x = ldiv(numer, denom);

   840  

   841  printf("Result-> 

   842 Quotient = %ld 

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

   844                  

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

   846   

   847  if( exp_numer == (numer) )

   848     printf("

   849 Result is same as the expected output");  

   850  else

   851     printf("

   852 Unexpected output");

   853  

   854  return 0;

   855 }

   856 

   857 @endcode

   858 @code

   859 Output

   860 

   861 Result->

   862 Quotient = 4

   863 Remainder = -1

   864 Result is same as the expected output

   865 

   866 @endcode

   867 @see div()

   868 @see lldiv()

   869  

   870 

   871 @publishedAll

   872 @externallyDefinedApi

   873 */

   874 

   875 /** @fn  malloc(size_t nbytes)

   876 @param nbytes

   877 

   878 Note: 

   879 

   880 This description also covers the following functions -

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

   882 

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

   884 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 

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

   886 

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

   888 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 

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

   890 

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

   892 

   893  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 

   894   initialized to zero bytes.

   895 

   896  The realloc function changes the size of the previously allocated memory 

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

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

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

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

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

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

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

   904 

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

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

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

   908 for realloc causing memory leaks in libraries.

   909 

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

   911 If ptr is NULL, no action occurs.

   912 

   913 Examples:

   914 @code

   915 #include <stdlib.h>    //malloc

   916 #include <stdio.h>    //printf

   917   

   918 int main( void )

   919 {

   920    /* allocate memory */

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

   922    

   923    if( pc == NULL )

   924       printf( "memory insufficient

   925 " );

   926    else

   927    {

   928       printf( "memory allocated

   929 " );

   930       free( pc );

   931       printf( "memory freed

   932 " );

   933    }

   934   

   935    return 0;

   936 }

   937 

   938 @endcode

   939 @code

   940 Output

   941 

   942 memory allocated

   943 memory freed

   944 

   945 @endcode

   946 @code

   947 #include <stdio.h> //printf

   948 #include <stdlib.h> //calloc

   949    

   950 int main( void )

   951 {

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

   953    if( pint != NULL )

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

   955                twice the size of an integer

   956 " );

   957    else

   958       printf( "can't allocate memory

   959 " );

   960    free( pint );

   961   

   962    return 0;

   963 }

   964 

   965 @endcode

   966 @code

   967 Output

   968 

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

   970 

   971 @endcode

   972 @code

   973 #include <stdio.h> //printf

   974 #include <stdlib.h> //realloc

   975  

   976 int main( void )

   977 {

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

   979  if (pint == NULL)

   980   {

   981   printf("calloc failed to allocate memory

   982 ");

   983   return -1;

   984   }

   985  else

   986   {

   987   printf("calloc allocated memory: 128 bytes

   988 ");

   989   }

   990  

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

   992  if (pint == NULL)

   993   {

   994   printf("realloc failed to allocate memory

   995 ");

   996   return -1;

   997   }

   998  else

   999   {

  1000   printf("realloc allocated memory: 192 bytes

  1001 ");

  1002   }

  1003   

  1004   free( pint );

  1005   return 0;

  1006 }

  1007 

  1008 @endcode

  1009 @code

  1010 Output

  1011 

  1012 calloc allocated memory: 128 bytes

  1013 realloc allocated memory: 192 bytes

  1014 

  1015 @endcode

  1016 @see brk()

  1017 @see mmap()

  1018 @see getpagesize()

  1019  

  1020 

  1021 @publishedAll

  1022 @externallyDefinedApi

  1023 */

  1024 

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

  1026 @param s

  1027 @param n

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

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

  1030 

  1031   The mblen function computes the length in bytes

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

  1033 Up to n bytes are examined.

  1034 

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

  1036 zero otherwise;

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

  1038 

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

  1040 

  1041 Examples:

  1042 @code

  1043 #include <stdlib.h>

  1044 #include <wchar.h>

  1045 /* Illustrates how to use mblen API */

  1046 int example_mblen(wchar_t wc)

  1047 {

  1048  int len;

  1049  

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

  1051  len = mblen(wc, MB_CUR_MAX);

  1052  if(len == -1)

  1053  {

  1054         wprintf(L"mblen returned error!!

  1055 ");

  1056  }

  1057  /* return the no of bytes */

  1058  return(len);

  1059 }

  1060 

  1061 @endcode

  1062 

  1063 Limitations:   

  1064 

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

  1066 It works only for UTF8 character set.

  1067 

  1068 @see mbrlen()

  1069 @see mbtowc()

  1070  

  1071 

  1072 @publishedAll

  1073 @externallyDefinedApi

  1074 */

  1075 

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

  1077 @param pwcs

  1078 @param s

  1079 @param n

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

  1081 not counting any terminating null wide character, or -1

  1082 if an invalid multibyte character was encountered.

  1083 

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

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

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

  1087 

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

  1089 

  1090 

  1091 

  1092 Examples:

  1093 @code

  1094 #include <stdio.h>

  1095 #include <stdlib.h>

  1096 #include <wchar.h>

  1097 /* Illustrates how to use mbstowcs API */

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

  1099 {

  1100  size_t len;

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

  1102  len = mbstowcs(wc, s, n);

  1103  /* checking for error */

  1104  if(len < 0)

  1105  {

  1106         wprintf(L"mbstowcs returned error!!

  1107 ");

  1108  }

  1109  /* returning no of bytes consumed */

  1110  return (len);

  1111 }

  1112 

  1113 @endcode

  1114 

  1115 Limitations:   

  1116 

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

  1118 It works only for UTF8 character set.

  1119 

  1120 @see mbsrtowcs()

  1121 @see mbtowc()

  1122  

  1123 

  1124 @publishedAll

  1125 @externallyDefinedApi

  1126 */

  1127 

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

  1129 @param pwc

  1130 @param s

  1131 @param n

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

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

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

  1135 could be recognized or converted.