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. This stack is often called the 77.Em alternate stack . 78Whether or not the alternate stack is used may be controlled through the 79.Xr sigaction 2 80and 81.Xr sigaltstack 2 82functions . 83.Pp 84The 85.Fn Plwp_stack 86function fills in 87.Fa stkp 88with the information about the thread's currently executing stack, 89whether the alternate or main one. 90.Pp 91The 92.Fn Plwp_alt_stack 93function fills in 94.Fa stkp 95with the information about the thread's alternate stack, if it's 96configured. 97.Pp 98The 99.Fn Plwp_main_stack 100function fills in 101.Fa stkp 102with the information about the thread's main stack, regardless of if there 103is an alternate stack or it is executing one. 104.Pp 105Process handles that refer to files, obtained through 106.Xr Pgrab_file 3PROC , 107do not have any stack information and these functions will always fail 108on them. 109.Pp 110The 111.Fn Lalt_stack , 112.Fn Lmain_stack , 113and 114.Fn Lstack 115functions are identical to the 116.Fn Plwp_alt_stack , 117.Fn Plwp_main_stack , 118and 119.Fn Plwp_main_stack 120functions, except rather than specifying a thread to operate on, they 121operate on the thread handle 122.Fa L , 123which specifies the thread to operate on. 124.Sh RETURN VALUES 125Upon successful completion, the 126.Fn Plwp_stack , 127.Fn Plwp_alt_stack , 128.Fn Plwp_main_stack , 129.Fn Lalt_stack , 130.Fn Lmain_stack , 131and 132.Fn Lstack 133functions return 134.Sy 0 135and fills in 136.Fa stkp 137with information about the appropriate stack. Otherwise, 138.Sy -1 139is returned, 140.Sy errno 141is updated with the error, and 142.Fa stkp 143is not modified. 144.Sh ERRORS 145For a full list of possible errors also see the 146.Sy DIAGNOSTICS 147section in 148.Xr proc 4 . 149.Pp 150The 151.Fn Plwp_stack , 152.Fn Plwp_alt_stack , 153and 154.Fn Plwp_main_stack 155function will fail if: 156.Bl -tag -width Er 157.It Er ENODATA 158The process handle 159.Fa P 160refers to a grabbed file, not an active process or core. 161.It Er EINVAL 162The process handle 163.Fa P 164refers to a core file and the specified thread does not exist. 165.It Er ENOENT 166The process handle 167.Fa P 168refers to an active process and the specified thread does not exist. 169.El 170.Pp 171The 172.Fn Plwp_alt_stack 173and 174.Fn Lalt_stack 175functions will fail if: 176.Bl -tag -width Er 177.It Er ENODATA 178The thread identified by 179.Fa lwpid 180did not have an alternate stack enabled. 181.El 182.Sh INTERFACE STABILITY 183.Sy Uncommitted 184.Sh MT-LEVEL 185See 186.Sy LOCKING 187in 188.Xr libproc 3LIB . 189.Sh SEE ALSO 190.Xr sigaction 2 , 191.Xr sigaltstack 2 , 192.Xr libproc 3LIB , 193.Xr proc 4 194