| mostang.com!davidm | 9eb9f31 | 2003-04-01 07:19:34 +0000 | [diff] [blame] | 1 | '\" t |
| mostang.com!davidm | 031c8bb | 2004-03-31 00:52:17 +0000 | [diff] [blame] | 2 | .\" Manual page created with latex2man on Tue Mar 30 16:50:17 PST 2004 |
| mostang.com!davidm | 9eb9f31 | 2003-04-01 07:19:34 +0000 | [diff] [blame] | 3 | .\" NOTE: This file is generated, DO NOT EDIT. |
| 4 | .de Vb |
| 5 | .ft CW |
| 6 | .nf |
| 7 | .. |
| 8 | .de Ve |
| 9 | .ft R |
| 10 | |
| 11 | .fi |
| 12 | .. |
| mostang.com!davidm | 031c8bb | 2004-03-31 00:52:17 +0000 | [diff] [blame] | 13 | .TH "UNW\\_GETCONTEXT" "3" "30 March 2004" "Programming Library " "Programming Library " |
| mostang.com!davidm | 9eb9f31 | 2003-04-01 07:19:34 +0000 | [diff] [blame] | 14 | .SH NAME |
| 15 | unw_getcontext |
| 16 | \-\- get initial machine\-state |
| 17 | .PP |
| 18 | .SH SYNOPSIS |
| 19 | |
| 20 | .PP |
| 21 | #include <libunwind.h> |
| 22 | .br |
| 23 | .PP |
| 24 | int |
| 25 | unw_getcontext(unw_context_t *ucp); |
| 26 | .br |
| 27 | .PP |
| 28 | .SH DESCRIPTION |
| 29 | |
| 30 | .PP |
| 31 | The unw_getcontext() |
| 32 | routine initializes the context structure |
| 33 | pointed to by ucp |
| 34 | with the machine\-state of the call\-site. The |
| 35 | exact set of registers stored by unw_getcontext() |
| 36 | is |
| 37 | platform\-specific, but, in general, at least all preserved |
| 38 | (``callee\-saved\&'') and all frame\-related registers, such as the |
| 39 | stack\-pointer, will be stored. |
| 40 | .PP |
| mostang.com!davidm | f928eec | 2004-01-21 01:05:07 +0000 | [diff] [blame] | 41 | This routine is normally implemented as a macro and applications |
| 42 | should not attempt to take its address. |
| 43 | .PP |
| mostang.com!davidm | 031c8bb | 2004-03-31 00:52:17 +0000 | [diff] [blame] | 44 | .SH PLATFORM\-SPECIFIC NOTES |
| 45 | |
| 46 | .PP |
| 47 | On IA\-64, unw_context_t |
| 48 | has a layout that is compatible with |
| 49 | that of ucontext_t |
| 50 | and such structures can be initialized with |
| 51 | getcontext() |
| 52 | instead of unw_getcontext(). |
| 53 | However, the |
| 54 | reverse is \fInot\fP |
| 55 | true and it is \fInot\fP |
| 56 | safe to use structures |
| 57 | initialized by unw_getcontext() |
| 58 | in places where a structure |
| 59 | initialized by getcontext() |
| 60 | is expected. The reason for this |
| 61 | asymmetry is that unw_getcontext() |
| 62 | is optimized for maximum |
| 63 | performance and does not, for example, save the signal mask. |
| 64 | .PP |
| mostang.com!davidm | 9eb9f31 | 2003-04-01 07:19:34 +0000 | [diff] [blame] | 65 | .SH RETURN VALUE |
| 66 | |
| 67 | .PP |
| 68 | On successful completion, unw_getcontext() |
| 69 | returns 0. |
| 70 | Otherwise, a value of \-1 is returned. |
| 71 | .PP |
| 72 | .SH THREAD AND SIGNAL SAFETY |
| 73 | |
| 74 | .PP |
| 75 | unw_getcontext() |
| 76 | is thread\-safe as well as safe to use |
| 77 | from a signal handler. |
| 78 | .PP |
| 79 | .SH SEE ALSO |
| 80 | |
| 81 | .PP |
| 82 | libunwind(3), |
| 83 | unw_init_local(3) |
| 84 | .PP |
| 85 | .SH AUTHOR |
| 86 | |
| 87 | .PP |
| 88 | David Mosberger\-Tang |
| 89 | .br |
| 90 | Hewlett\-Packard Labs |
| 91 | .br |
| 92 | Palo\-Alto, CA 94304 |
| 93 | .br |
| 94 | Email: \fBdavidm@hpl.hp.com\fP |
| 95 | .br |
| 96 | WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&. |
| 97 | .\" NOTE: This file is generated, DO NOT EDIT. |