swapcontext(3C)




NAME

     makecontext, swapcontext - manipulate user contexts


SYNOPSIS

     cc -D__MAKECONTEXT_V2_SOURCE [ flag... ] file...  [ library... ]
     #include <ucontext.h>

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

     int swapcontext(ucontext_t *oucp, const ucontext_t *ucp);


DESCRIPTION

     These functions are useful for implementing user-level  con-
     text  switching between multiple threads of control within a
     process.

     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)),  program  execution continues by calling the func-
     tion func, passing it the arguments that follow argc in  the
     makecontext()  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 value of
     argc must match the number of integer  arguments  passed  to
     func, otherwise the behavior is undefined.

     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(3THR).

     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  illegal  address,
     the behavior is undefined and errno may be set to EFAULT.


RETURN VALUES

     Upon 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:

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

     #include <stdio.h>
     #include <ucontext.h>
     #include <sys/mman.h>

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


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(3THR).


ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO

     exit(2), getcontext(2), mmap(2)sigaction(2), sigprocmask(2),
     threads(3THR), ucontext(3HEAD), attributes(5)


NOTES

     The Solaris 9 4/03 release introduced new semantics for  the
     uc_stack member of the ucontext_t structure as they apply to
     inputs to  makecontext().  The  previous  implementation  of
     makecontext()  for SPARC and SPARCv9 was in violation of the
     standard. To access the updated version with  the  corrected
     behavior,  specify  -D__MAKECONTEXT_V2_SOURCE  when invoking
     the compiler. See  the  EXAMPLES  section  for  the  correct
     usage.


Man(1) output converted with man2html