swapcontext man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

MAKECONTEXT(3C)						       MAKECONTEXT(3C)

NAME
       makecontext, swapcontext - manipulate user contexts

SYNOPSIS
       #include <ucontext.h>

       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	 setcontext(2), execution continues by calling
       the function 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 unde‐
       fined.

       Before  a  call	is  made  to makecontext(), the context being modified
       should have a stack allocated for it. The stack is assigned to the con‐
       text 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 makecontext() returns.   The
       uc_link	member	should	be  initialized	 prior to the call to makecon‐
       text(). If the uc_link member is initialized to NULL, the  thread  exe‐
       cuting 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 struc‐
       ture 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.  Otherwise,	−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 allo‐
       cated using mmap().

	 #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 context switch‐
       ing between multiple threads of control within a	 process  (co-process‐
       ing).  More  effective  multiple	 threads of control can be obtained by
       using native support for multithreading. See threads(5).

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Standard	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ MT-Safe	      │
       └────────────────────┴─────────────────┘

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

NOTES
       The  semantics  of the uc_stack member of the ucontext_t structure have
       changed as they apply to inputs to makecontext(). 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 repre‐
       sents  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
	 +++ 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);

				  Mar 8, 2004		       MAKECONTEXT(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net