Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
makecontext(3C)		 Standard C Library Functions	       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  re-
       sumed  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 re-
       turned 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 al-
       located 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 context  switch-
       ing  between  multiple threads of control within	a process (co-process-
       ing). More effective multiple threads of	control	can be obtained	by us-
       ing 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 re-
       leases 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 up-
       dated  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);

SunOS 5.10			  8 Mar	2004		       makecontext(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | USAGE | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=makecontext&sektion=3c&manpath=SunOS+5.10>

home | help