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