setcontext(2)

1getcontext(2)                    System Calls                    getcontext(2)
2
3
4

NAME

6       getcontext, setcontext - get and set current user context
7

SYNOPSIS

9       #include <ucontext.h>
10
11       int getcontext(ucontext_t *ucp);
12
13
14       int setcontext(const ucontext_t *ucp);
15
16

DESCRIPTION

18       The  getcontext()  function initializes the structure pointed to by ucp
19       to the current user context of the  calling  process.   The  ucontext_t
20       type  that ucp points to defines the user context and includes the con‐
21       tents of the calling process' machine registers, the signal  mask,  and
22       the current execution stack.
23
24
25       The  setcontext() function restores the user context pointed to by ucp.
26       A successful call to setcontext() does not  return;  program  execution
27       resumes  at  the  point specified by the ucp argument passed to setcon‐
28       text(). The ucp argument should be created either by a  prior  call  to
29       getcontext(), or by being passed as an argument to a signal handler. If
30       the ucp argument was created with getcontext(), program execution  con‐
31       tinues  as if the corresponding call of getcontext() had just returned.
32       If the ucp argument was created with makecontext(3C), program execution
33       continues  with the function passed to makecontext(3C). When that func‐
34       tion returns, the process continues as if after a call to  setcontext()
35       with  the  ucp  argument  that was input to makecontext(3C). If the ucp
36       argument was passed to a signal handler,  program  execution  continues
37       with  the  program instruction following the instruction interrupted by
38       the signal.  If the uc_link member of the ucontext_t structure  pointed
39       to  by  the  ucp  argument is equal to 0, then this context is the main
40       context, and the process will exit  when  this  context  returns.   The
41       effects  of  passing  a ucp argument obtained from any other source are
42       unspecified.
43

RETURN VALUES

45       On successful completion, setcontext() does not return and getcontext()
46       returns 0. Otherwise, −1 is returned.
47

ERRORS

49       No errors are defined.
50

USAGE

52       When  a  signal  handler is executed, the current user context is saved
53       and a new context is created.  If the thread leaves the signal  handler
54       via  longjmp(3UCB),  then  it is unspecified whether the context at the
55       time of the  corresponding  setjmp(3UCB)  call  is  restored  and  thus
56       whether future calls to getcontext() will provide an accurate represen‐
57       tation  of  the  current  context,  since  the  context   restored   by
58       longjmp(3UCB)  may  not  contain  all the information that setcontext()
59       requires.  Signal handlers should use siglongjmp(3C) instead.
60
61
62       Portable applications should not modify or access the uc_mcontext  mem‐
63       ber  of  ucontext_t.  A portable application cannot assume that context
64       includes any process-wide static data, possibly including errno.  Users
65       manipulating  contexts should take care to handle these explicitly when
66       required.
67

ATTRIBUTES

69       See attributes(5) for descriptions of the following attributes:
70
71
72
73
74       ┌─────────────────────────────┬─────────────────────────────┐
75       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
76       ├─────────────────────────────┼─────────────────────────────┤
77       │Interface Stability          │Standard                     │
78       └─────────────────────────────┴─────────────────────────────┘
79