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. 43The full signature of 44.Ft proc_stack_f 45is defined in 46.Xr libproc 3LIB . 47With each callback, a register set, argument set, and argument count 48will be provided. 49In that register set, only a subset of the registers will be valid, which 50include the frame pointer, program counter, and on SPARC systems, the next 51program counter. 52These registers can be accessed with the constants 53.Sy R_FP , 54.Sy R_PC , 55and 56.Sy R_nPC 57respectively. 58These correspond to the registers 59.Em %ebp 60and 61.Em %eip 62on i386, 63.Em %rbp 64and 65.Em %rip 66on amd64, 67.Em %fp , 68.Em %pc , 69and 70.Em %npc 71on both SPARC and SPARCv9. 72.Pp 73Callers will receive a callback for the first stack frame indicated by 74.Fa regs 75and then will receive a subsequent callback for each caller of that 76frame until no such frame can be found. 77Stack frames that logically come after the frame indicated by 78.Fa regs 79will not receive callbacks. 80.Pp 81The compiler can either facilitate or stymie the iteration of the stack. 82Programs that have been compiled in such a way as to omit the frame pointer will 83result in truncated stacks. 84Similarly, if the initial set of registers passed in via 85.Fa regs 86is invalid, then the ability to iterate the stack will be limited. 87The return value of 88.Fa func 89controls whether or not iteration continues. 90If 91.Fa func 92returns 93.Sy 0 94then iteration continues. 95However, if 96.Fa func 97returns non-zero, then iteration will halt and that value will be used 98as the return value of the 99.Fn Pstack_iter 100function. 101Because 102.Fn Pstack_iter 103returns 104.Sy -1 105on internal failure it is recommended the callback function not return 106.Sy -1 107to indicate an error. 108Thus the caller may distinguish between the failure of the callback function and 109the failure of the 110.Fn Pstack_iter 111function. 112.Sh RETURN VALUES 113Upon successful completion, the 114.Fn Pstack_iter 115function returns 116.Sy 0. 117If there was an internal error then 118.Sy -1 119is returned. 120Otherwise, if the callback function 121.Fa func 122returns non-zero, then its return value will be returned instead. 123.Sh INTERFACE STABILITY 124.Sy Uncommitted 125.Sh MT-LEVEL 126See 127.Sy LOCKING 128in 129.Xr libproc 3LIB . 130.Sh SEE ALSO 131.Xr libproc 3LIB , 132.Xr proc 4 133