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