1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/os/ossrv/genericopenlibs/openenvcore/include/setjmp.dosc	Fri Jun 15 03:10:57 2012 +0200
     1.3 @@ -0,0 +1,122 @@
     1.4 +/** @file  ../include/setjmp.h
     1.5 +@internalComponent
     1.6 +*/
     1.7 +
     1.8 +/** @fn  longjmp(jmp_buf __jmpb, int __retval)
     1.9 +@param __jmpb
    1.10 +@param __retval
    1.11 +
    1.12 +Refer to  setjmp() for the documentation
    1.13 +
    1.14 +
    1.15 + 
    1.16 +
    1.17 +@publishedAll
    1.18 +@externallyDefinedApi
    1.19 +*/
    1.20 +
    1.21 +/** @fn  setjmp(jmp_buf __jmpb)
    1.22 +@param __jmpb
    1.23 +
    1.24 +Note: This description also covers the following functions -
    1.25 + longjmp()  _setjmp()  _longjmp() 
    1.26 +
    1.27 +@return   If the return is from a direct invocation, the setjmp function returns 0. If the return is from a call to longjmp(),
    1.28 +setjmp() returns a non-zero value.
    1.29 +After the longjmp is completed, program execution continues as if
    1.30 +the corresponding invocation of setjmp() had just returned the
    1.31 +value specified by __retval. If __retval is 0, setjmp() returns 1.
    1.32 +
    1.33 +  The setjmp, and _setjmp functions save their calling environment in __jmpb. Each of these functions returns 0.
    1.34 +
    1.35 + The corresponding longjmp functions restore the environment saved by their most recent respective
    1.36 +invocations
    1.37 +of the setjmp function.
    1.38 +They then return so that program execution continues as if the corresponding
    1.39 +invocation of the setjmp call had just returned the value specified by __retval, instead of 0.
    1.40 +
    1.41 + The longjmp routines may not be called after the routine which called the setjmp routines returns.
    1.42 +
    1.43 + All accessible objects have values as of the time longjmp routine was called, except that the values of objects of automatic storage
    1.44 +invocation duration that do not have the volatile
    1.45 +type and have been changed between the setjmp invocation and longjmp call are indeterminate.
    1.46 +
    1.47 + The setjmp / longjmp pairs save and restore the signal mask while _setjmp / _longjmp pairs save and restore only the register set and the stack.
    1.48 +
    1.49 +Examples:
    1.50 +@code
    1.51 +#include <setjmp.h>
    1.52 +#include <stdio.h>
    1.53 +#include <stdlib.h>
    1.54 +  
    1.55 +static void f1( int, int, int );
    1.56 +static void f2( void );
    1.57 +static jmp_buf jmpbuffer;
    1.58 +  
    1.59 +int main()
    1.60 +{
    1.61 +        int count;
    1.62 +        register int val;
    1.63 +        volatile int sum;
    1.64 +  
    1.65 +        count = 2; val = 3; sum = 4;
    1.66 +  
    1.67 +        if ( setjmp( jmpbuffer ) != 0 )
    1.68 +        {
    1.69 +    printf("in main: count = %d, val = %d, sum = %d
    1.70 +", count, val, sum );
    1.71 +    exit(0);
    1.72 +  }
    1.73 +  
    1.74 +        f1(97, 98, 99 );
    1.75 +  
    1.76 +        return 0;
    1.77 +}
    1.78 +   
    1.79 +static void f1 (int i, int j, int k )
    1.80 +{
    1.81 +          printf("in f1: count = %d, val = %d, sum = %d
    1.82 +", i, j , k );
    1.83 +    f2();
    1.84 +}
    1.85 +   
    1.86 +static void f2( void )
    1.87 +{
    1.88 +    longjmp( jmpbuffer, 1 );
    1.89 +}
    1.90 +
    1.91 +@endcode
    1.92 + Output
    1.93 +@code
    1.94 +in f1: count = 97, val = 98, sum = 99
    1.95 +in main: count = 2, val = 3, sum = 4
    1.96 +
    1.97 +@endcode
    1.98 +
    1.99 +Limitations: 
   1.100 +
   1.101 +The signal related functionalities aren't applicable to the Symbian 
   1.102 +OS implementation as there is no support for signals. This means that the setjmp and _setjmp routines have the same functionality and so do longjmp and _longjmp . 
   1.103 +
   1.104 + 
   1.105 +
   1.106 +@publishedAll
   1.107 +@externallyDefinedApi
   1.108 +*/
   1.109 +
   1.110 +
   1.111 +/** @def	_setjmp
   1.112 +
   1.113 +The _longjmp() and _setjmp() functions shall be equivalent to longjmp() and setjmp(), respectively, with the additional restriction that _longjmp() and _setjmp() shall not manipulate the signal mask.
   1.114 +
   1.115 +@publishedAll
   1.116 +@externallyDefinedApi
   1.117 +*/
   1.118 +
   1.119 +/** @def	_longjmp
   1.120 +
   1.121 +The _longjmp() and _setjmp() functions shall be equivalent to longjmp() and setjmp(), respectively, with the additional restriction that _longjmp() and _setjmp() shall not manipulate the signal mask.
   1.122 +
   1.123 +@publishedAll
   1.124 +@externallyDefinedApi
   1.125 +*/