GETCONTEXT(2)

GETCONTEXT(2) | System Calls Manual | GETCONTEXT(2)

# NAME

`getcontext`, `setcontext` — get and set current user context

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <ucontext.h>`

int
`getcontext`(ucontext_t *ucp);

int
`setcontext`(const ucontext_t *ucp);

# DESCRIPTION

The `getcontext`() function initializes the object pointed to by ucp to the current user context of the calling thread. The user context defines a thread's execution environment and includes the contents of its machine registers, its signal mask, and its current execution stack.

The `setcontext`() function restores the user context defined in the object pointed to by ucp as most recently initialized by a previous call to either `getcontext`() or makecontext(3). If successful, execution of the program resumes as defined in the ucp argument, and `setcontext`() will not return. If ucp was initialized by the `getcontext`() function, program execution continues as if the corresponding invocation of `getcontext`() had just returned (successfully). If ucp was initialized by the makecontext(3) function, program execution continues with the function (and function arguments) passed to makecontext(3).

# RETURN VALUES

On successful completion, `getcontext`() returns 0 and `setcontext`() does not return. Otherwise a value of -1 is returned and errno is set to indicate the error.

# ERRORS

The `getcontext`() and `setcontext`() functions will fail if:

[`EFAULT`]
  The ucp argument points to an invalid address.

The `setcontext`() function will fail if:

[`EINVAL`]
  The contents of the datum pointed to by ucp are invalid.

# SEE ALSO

sigprocmask(2), longjmp(3), makecontext(3), setjmp(3), swapcontext(3)

# STANDARDS

The `getcontext`() and `setcontext`() functions conform to X/Open System Interfaces and Headers Issue 5 (“XSH5”) and IEEE Std 1003.1-2001 (“POSIX.1”). The errno indications are an extension to the standard.

The IEEE Std 1003.1-2004 (“POSIX.1”) revision marked the functions `getcontext`() and `setcontext`() 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.

# HISTORY

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

April 28, 2010 | NetBSD 11.0