share/man/man3proc/Plwp_stack.3proc

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