MAKECONTEXT(3)

MAKECONTEXT(3) | Library Functions Manual | MAKECONTEXT(3)

# NAME

`makecontext`, `swapcontext` — manipulate user contexts

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <ucontext.h>`

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

int
`swapcontext`(ucontext_t * restrict oucp, ucontext_t * restrict ucp);

# DESCRIPTION

The `makecontext`() function modifies the object pointed to by ucp, which has been initialized using getcontext(2). When this context is resumed using `swapcontext`() or setcontext(2), program execution continues as if func had been called with the arguments specified after argc in the call of `makecontext`(). The value of argc must be equal to the number of integer arguments following it, and must be equal to the number of integer arguments expected by func; otherwise, the behavior is undefined.

Before being modified using `makecontext`(), a stack must be allocated for the context (in the uc_stack member), and a context to resume after func has returned must be determined (pointed to by the uc_link member); otherwise, the behavior is undefined. If uc_link is a null pointer, then the context is the main context, and the process will exit with an exit status of 0 upon return.

The `swapcontext`() function saves the current context in the object pointed to by oucp, sets the current context to that specified in the object pointed to by ucp, and resumes execution. When a context saved by `swapcontext`() is restored using setcontext(2), execution will resume as if the corresponding invocation of `swapcontext`() had just returned (successfully).

# RETURN VALUES

The `makecontext`() function returns no value.

On success, `swapcontext`() returns a value of 0, Otherwise, -1 is returned and errno is set to indicate the error.

# ERRORS

The `swapcontext`() function will fail if:

[`EFAULT`]
  The oucp argument or the ucp argument points to an invalid address.
[`EINVAL`]
  The contents of the datum pointed to by ucp are invalid.

# SEE ALSO

_exit(2), getcontext(2), setcontext(2), ucontext(2)

# STANDARDS

The `makecontext`() and `swapcontext`() functions conform to X/Open System Interfaces and Headers Issue 5 (“XSH5”) and IEEE Std 1003.1-2001 (“POSIX.1”).

The IEEE Std 1003.1-2004 (“POSIX.1”) revision marked the functions `makecontext`() and `swapcontext`() as obsolete, citing portability issues and recommending the use of POSIX threads instead. The IEEE Std 1003.1-2008 (“POSIX.1”) revision removed the functions from the specification.

The standard does not clearly define the type of integer arguments passed to func via `makecontext`(); portable applications should not rely on the implementation detail that it may be possible to pass pointer arguments to functions.
This may be clarified in a future revision of the standard.

# HISTORY

The `makecontext`() and `swapcontext`() functions first appeared in AT&T System V Release 4 UNIX.

May 4, 2012 | NetBSD 11.0