Manual Pages for UNIX Operating System command usage for man makecontext

Standard C Library Functions                      makecontext(3C)



NAME
     makecontext, swapcontext - manipulate user contexts

SYNOPSIS
     #include 

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


     int swapcontext(ucontext_t *restrict oucp,
          const ucontext_t *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 uc_stack member.


     The uc_link member is used to  determine  the  context  that
     will  be resumed when the context being modified by makecon-
     text() returns.  The uc_link member  should  be  initialized
     prior to the call to makecontext(). If the uc_link member is
     initialized to NULL, the thread  executing  func  will  exit
     when func returns. See pthread_exit(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.

ERRORS
     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)
       {
               ucontext_t uc, back;
               size_t sz = 0x10000;
               int value = 0;

               getcontext(&uc);

               uc.uc_stack.ss_sp = mmap(0, sz,
                   PROT_READ | PROT_WRITE | PROT_EXEC,
                   MAP_PRIVATE | MAP_ANON, -1, 0);
               uc.uc_stack.ss_size = sz;
               uc.uc_stack.ss_flags = 0;

               uc.uc_link = &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).

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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


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

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


     This change in the meaning  of  ss_sp  is  now  the  default
     behavior.  The  -D__MAKECONTEXT_V2_SOURCE  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:

       --- example1_s9.c       Thu Oct  3 11:58:17 2002



SunOS 5.11           Last change: 8 Mar 2004                    3






Standard C Library Functions                      makecontext(3C)



       +++ example1.c  Thu Jun 27 13:28:16 2002
       @@ -27,12 +27,9 @@
               uc.uc_stack.ss_sp = mmap(0, sz,
                   PROT_READ | PROT_WRITE | PROT_EXEC,
                   MAP_PRIVATE | MAP_ANON, -1, 0);
       -       uc.uc_stack.ss_sp = (char *)uc.uc_stack.ss_sp + sz - 8;
               uc.uc_stack.ss_size = sz;
               uc.uc_stack.ss_flags = 0;

               uc.uc_link = &back

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











































SunOS 5.11           Last change: 8 Mar 2004                    4