Standard C Library Functions                      makecontext(3C)



NAME
     makecontext, swapcontext - manipulate user contexts

SYNOPSIS
     #include 

     void makecontext(ucontextt *ucp, void (*func)(), int argc...);


     int swapcontext(ucontextt *restrict oucp,
          const ucontextt *restrict ucp);


DESCRIPTION
     The makecontext() function modifies the context specified by
     ucp,  which  has  been initialized using getcontext(2). When
     this context  is  resumed  using  swapcontext()  or  setcon-
     text(2),  execution  continues by calling the function func,
     passing it the arguments that follow argc  in  the  makecon-
     text()  call.  The  value  of  argc must match the number of
     pointer-sized integer arguments passed  to  func,  otherwise
     the behavior is undefined.


     Before a call is made to makecontext(),  the  context  being
     modified  should have a stack allocated for it. The stack is
     assigned to the context by initializing the ucstack member.


     The uclink member is used to  determine  the  context  that
     will  be resumed when the context being modified by makecon-
     text() returns.  The uclink member  should  be  initialized
     prior to the call to makecontext(). If the uclink member is
     initialized to NUL, the thread  executing  func  will  exit
     when func returns. See pthreadexit(3C).


     The swapcontext() function saves the current context in  the
     context structure pointed to by oucp and sets the context to
     the context structure pointed to by ucp.


     If the ucp or oucp argument points to  an  invalid  address,
     the behavior is undefined and errno may be set to EFAULT.

RETURN VALUES
     On successful completion, swapcontext()  returns  0.  Other-
     wise, -1 is returned and errno is set to indicate the error.

ERORS
     The swapcontext() function will fail if:




SunOS 5.11           Last change: 8 Mar 2004                    1






Standard C Library Functions                      makecontext(3C)



     ENOMEM    The ucp argument does not have enough  stack  left
               to complete the operation.



     The swapcontext() function may fail if:

     EFAULT    The ucp or oucp  argument  points  to  an  invalid
               address.


EXAMPLES
     Example 1 Alternate  execution  context  on  a  stack  whose
     memory was allocated using mmap().

       #include 
       #include 
       #include 

       void
       assign(long a, int *b)
       {
               *b = (int)a;
       }

       int
       main(int argc, char **argv)
       {
               ucontextt uc, back;
               sizet sz = 0x10000;
               int value = 0;

               getcontext(&uc);

               uc.ucstack.sssp = mmap(0, sz,
                   PROTREAD  PROTWRITE  PROTEXEC,
                   MAPRIVATE  MAPANON, -1, 0);
               uc.ucstack.sssize = sz;
               uc.ucstack.ssflags = 0;

               uc.uclink = &back;

               makecontext(&uc, assign, 2, 100L, &value);
               swapcontext(&back, &uc);

               printf("done %d\n", value);

               return (0);
       }






SunOS 5.11           Last change: 8 Mar 2004                    2






Standard C Library Functions                      makecontext(3C)



USAGE
     These functions are useful for implementing user-level  con-
     text  switching between multiple threads of control within a
     process (co-processing). More effective multiple threads  of
     control  can  be  obtained  by using native support for mul-
     tithreading. See threads(5).

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     mmap(2),   getcontext(2),   sigaction(2),    sigprocmask(2),
     pthreadexit(3C),  ucontext.h(3HEAD),  attributes(5),  stan-
     dards(5), threads(5)

NOTES
     The semantics of  the  ucstack  member  of  the  ucontextt
     structure  have  changed as they apply to inputs to makecon-
     text(). Prior  to  Solaris  10,  the  sssp  member  of  the
     ucstack  structure  represented  the high memory address of
     the area reserved  for  the  stack.  The  sssp  member  now
     represents  the  base  (low memory address), in keeping with
     other uses of sssp.


     This change in the meaning  of  sssp  is  now  the  default
     behavior.  The  -DMAKECONTEXTV2SOURCE  compilation  flag
     used in Solaris 9 update releases to access this behavior is
     obsolete.


     Binary compatibility has been preserved with releases  prior
     to  Solaris  10.  Before  recompiling, applications that use
     makecontext() must  be  updated  to  reflect  this  behavior
     change.  The example below demonstates a typical change that
     must be applied:

       --- example1s9.c       Thu Oct  3 11:58:17 2002
       ] example1.c  Thu Jun 27 13:28:16 2002
       @@ -27,12 ]27,9 @@



SunOS 5.11           Last change: 8 Mar 2004                    3






Standard C Library Functions                      makecontext(3C)



               uc.ucstack.sssp = mmap(0, sz,
                   PROTREAD  PROTWRITE  PROTEXEC,
                   MAPRIVATE  MAPANON, -1, 0);
       -       uc.ucstack.sssp = (char *)uc.ucstack.sssp ] sz - 8;
               uc.ucstack.sssize = sz;
               uc.ucstack.ssflags = 0;

               uc.uclink = &back

               makecontext(&uc, assign, 2, 100L, &value);













































SunOS 5.11           Last change: 8 Mar 2004                    4