---
name: "setcontext"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/getcontext/3"
---

# setcontext(3)

get and set user thread context

Part of [getcontext(3)](/getcontext/3.md).

## NAME

**getcontext**, **getcontextx**, **setcontext** – get and set user thread context

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

**#include \<ucontext.h\>**

*int*\

**getcontext**(*ucontext\_t \*ucp*);

*ucontext\_t* *\**\

**getcontextx**(*void*);

*int*\

**setcontext**(*const ucontext\_t \*ucp*);

## DESCRIPTION

The **getcontext**() function saves the current thread's execution context in the structure pointed to by *ucp*. This saved context may then later be restored by calling **setcontext**().

The **getcontextx**() function saves the current execution context in the newly allocated structure *ucontext\_t*, which is returned on success. If architecture defines additional CPU states that can be stored in extended blocks referenced from the *ucontext\_t*, the memory for them may be allocated and their context also stored. Memory returned by **getcontextx**() function shall be freed using **free**(*3*).

The **setcontext**() function makes a previously saved thread context the current thread context, i.e., the current context is lost and **setcontext**() does not return. Instead, execution continues in the context specified by *ucp*, which must have been previously initialized by a call to **getcontext**(), [makecontext(3)](/makecontext/3.md), or by being passed as an argument to a signal handler (see [sigaction(2)](/sigaction/2.md)).

If *ucp* was initialized by **getcontext**(), then execution continues as if the original **getcontext**() call had just returned (again).

If *ucp* was initialized by [makecontext(3)](/makecontext/3.md), execution continues with the invocation of the function specified to [makecontext(3)](/makecontext/3.md). When that function returns, *ucp-\>uc\_link* determines what happens next: if *ucp-\>uc\_link* is NULL, the process exits; otherwise, **setcontext**(*ucp-\>uc\_link*) is implicitly invoked.

If *ucp* was initialized by the invocation of a signal handler, execution continues at the point the thread was interrupted by the signal.

## RETURN VALUES

If successful, **getcontext**() returns zero and **setcontext**() does not return; otherwise -1 is returned. The **getcontextx**() returns pointer to the allocated and initialized context on success, and *NULL* on failure.

## ERRORS

No errors are defined for **getcontext**() or **setcontext**(). The **getcontextx**() may return the following errors in *errno*:

- \[ENOMEM\]

  No memory was available to allocate for the context or some extended state.

## SEE ALSO

[sigaction(2)](/sigaction/2.md), [sigaltstack(2)](/sigaltstack/2.md), [makecontext(3)](/makecontext/3.md), [ucontext(3)](/ucontext/3.md)

## 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.