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