1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2015 Joyent, Inc. 13.\" 14.Dd May 11, 2016 15.Dt PLWP_STACK 3PROC 16.Os 17.Sh NAME 18.Nm Plwp_stack , 19.Nm Plwp_alt_stack , 20.Nm Plwp_main_stack , 21.Nm Lstack , 22.Nm Lalt_stack , 23.Nm Lmain_stack 24.Nd get thread stack information 25.Sh SYNOPSIS 26.Lb libproc 27.In libproc.h 28.Ft int 29.Fo Plwp_stack 30.Fa "struct ps_prochandle *P" 31.Fa "lwpid_t lwpid" 32.Fa "stack_t *stkp" 33.Fc 34.Ft int 35.Fo Plwp_alt_stack 36.Fa "struct ps_prochandle *P" 37.Fa "lwpid_t lwpid" 38.Fa "stack_t *stkp" 39.Fc 40.Ft int 41.Fo Plwp_main_stack 42.Fa "struct ps_prochandle *P" 43.Fa "lwpid_t lwpid" 44.Fa "stack_t *stkp" 45.Fc 46.Ft int 47.Fo Lalt_stack 48.Fa "struct ps_lwphandle *L" 49.Fa "stack_t *stkp" 50.Fc 51.Ft int 52.Fo Lmain_stack 53.Fa "struct ps_lwphandle *L" 54.Fa "stack_t *stkp" 55.Fc 56.Ft int 57.Fo Lstack 58.Fa "struct ps_lwphandle *L" 59.Fa "stack_t *stkp" 60.Fc 61.Sh DESCRIPTION 62The 63.Fn Plwp_stack , 64.Fn Plwp_alt_stack , 65and 66.Fn Plwp_main_stack 67functions obtain information about the size and address of the stacks 68for the thread identified by 69.Fa lwpid 70in the process handle 71.Fa P . 72.Pp 73Each thread in a process has its own stack which is used both for 74maintaining function call sequences and the storing of local variables. 75A thread may also configure a different stack to handle specific 76signals. 77This stack is often called the 78.Em alternate stack . 79Whether or not the alternate stack is used may be controlled through the 80.Xr sigaction 2 81and 82.Xr sigaltstack 2 83functions . 84.Pp 85The 86.Fn Plwp_stack 87function fills in 88.Fa stkp 89with the information about the thread's currently executing stack, 90whether the alternate or main one. 91.Pp 92The 93.Fn Plwp_alt_stack 94function fills in 95.Fa stkp 96with the information about the thread's alternate stack, if it's 97configured. 98.Pp 99The 100.Fn Plwp_main_stack 101function fills in 102.Fa stkp 103with the information about the thread's main stack, regardless of if there 104is an alternate stack or it is executing one. 105.Pp 106Process handles that refer to files, obtained through 107.Xr Pgrab_file 3PROC , 108do not have any stack information and these functions will always fail 109on them. 110.Pp 111The 112.Fn Lalt_stack , 113.Fn Lmain_stack , 114and 115.Fn Lstack 116functions are identical to the 117.Fn Plwp_alt_stack , 118.Fn Plwp_main_stack , 119and 120.Fn Plwp_main_stack 121functions, except rather than specifying a thread to operate on, they 122operate on the thread handle 123.Fa L , 124which specifies the thread to operate on. 125.Sh RETURN VALUES 126Upon successful completion, the 127.Fn Plwp_stack , 128.Fn Plwp_alt_stack , 129.Fn Plwp_main_stack , 130.Fn Lalt_stack , 131.Fn Lmain_stack , 132and 133.Fn Lstack 134functions return 135.Sy 0 136and fills in 137.Fa stkp 138with information about the appropriate stack. 139Otherwise, 140.Sy -1 141is returned, 142.Sy errno 143is updated with the error, and 144.Fa stkp 145is not modified. 146.Sh ERRORS 147For a full list of possible errors also see the 148.Sy DIAGNOSTICS 149section in 150.Xr proc 4 . 151.Pp 152The 153.Fn Plwp_stack , 154.Fn Plwp_alt_stack , 155and 156.Fn Plwp_main_stack 157function will fail if: 158.Bl -tag -width Er 159.It Er ENODATA 160The process handle 161.Fa P 162refers to a grabbed file, not an active process or core. 163.It Er EINVAL 164The process handle 165.Fa P 166refers to a core file and the specified thread does not exist. 167.It Er ENOENT 168The process handle 169.Fa P 170refers to an active process and the specified thread does not exist. 171.El 172.Pp 173The 174.Fn Plwp_alt_stack 175and 176.Fn Lalt_stack 177functions will fail if: 178.Bl -tag -width Er 179.It Er ENODATA 180The thread identified by 181.Fa lwpid 182did not have an alternate stack enabled. 183.El 184.Sh INTERFACE STABILITY 185.Sy Uncommitted 186.Sh MT-LEVEL 187See 188.Sy LOCKING 189in 190.Xr libproc 3LIB . 191.Sh SEE ALSO 192.Xr sigaction 2 , 193.Xr sigaltstack 2 , 194.Xr libproc 3LIB , 195.Xr proc 4 196