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 PSTACK_ITER 3PROC 16.Os 17.Sh NAME 18.Nm Pstack_iter 19.Nd iterate process stack frames 20.Sh SYNOPSIS 21.Lb libproc 22.In libproc.h 23.Ft int 24.Fo Pstack_iter 25.Fa "struct ps_prochandle *P" 26.Fa "const prgregset_t regs" 27.Fa "proc_stack_f *func" 28.Fa "void *data" 29.Fc 30.Sh DESCRIPTION 31The 32.Fn Pstack_iter 33function iterates over the stack frames in the process 34.Fa P 35starting at the point defined by 36.Fa regs . 37.Pp 38For each valid stack frame encountered, the callback function 39.Fa func 40is invoked with 41.Fa data 42passed as argument. The full signature of 43.Ft proc_stack_f 44is defined in 45.Xr libproc 3LIB . 46With each callback, a register set, argument set, and argument count 47will be provided. In that register set, only a subset of the registers 48will be valid, which include the frame pointer, program counter, and on 49SPARC systems, the next program counter. These registers can be accessed 50with the constants 51.Sy R_FP , 52.Sy R_PC , 53and 54.Sy R_nPC 55respectively. These correspond to the registers 56.Em %ebp 57and 58.Em %eip 59on i386, 60.Em %rbp 61and 62.Em %rip 63on amd64, 64.Em %fp , 65.Em %pc , 66and 67.Em %npc 68on both SPARC and SPARCv9. 69.Pp 70Callers will receive a callback for the first stack frame indicated by 71.Fa regs 72and then will receive a subsequent callback for each caller of that 73frame until no such frame can be found. Stack frames that logically come 74after the frame indicated by 75.Fa regs 76will not receive callbacks. 77.Pp 78The compiler can either facilitate or stymie the iteration of the 79stack. Programs that have been compiled in such a way as to omit the 80frame pointer will result in truncated stacks. Similarly, if the initial 81set of registers passed in via 82.Fa regs 83is invalid, then the ability to iterate the stack will be limited. 84The return value of 85.Fa func 86controls whether or not iteration continues. If 87.Fa func 88returns 89.Sy 0 90then iteration continues. However, if 91.Fa func 92returns non-zero, then iteration will halt and that value will be used 93as the return value of the 94.Fn Pstack_iter 95function. Because 96.Fn Pstack_iter 97returns 98.Sy -1 99on internal failure it is recommended the callback function not return 100.Sy -1 101to indicate an error. Thus the caller may distinguish between the 102failure of the callback function and the failure of the 103.Fn Pstack_iter 104function. 105.Sh RETURN VALUES 106Upon successful completion, the 107.Fn Pstack_iter 108function returns 109.Sy 0. 110If there was an internal error then 111.Sy -1 112is returned. Otherwise, if the callback function 113.Fa func 114returns non-zero, then its return value will be returned instead. 115.Sh INTERFACE STABILITY 116.Sy Uncommitted 117.Sh MT-LEVEL 118See 119.Sy LOCKING 120in 121.Xr libproc 3LIB . 122.Sh SEE ALSO 123.Xr libproc 3LIB , 124.Xr proc 4 125