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 PMAPPING_ITER 3PROC 16.Os 17.Sh NAME 18.Nm Pmapping_iter , 19.Nm Pmapping_iter_resolved , 20.Nm Pobject_iter , 21.Nm Pobject_iter_resolved 22.Nd iterate over process mappings and objects 23.Sh LIBRARY 24.Lb libproc 25.Sh SYNOPSIS 26.In libproc.h 27.Ft int 28.Fo Pmapping_iter 29.Fa "struct ps_prochandle *P" 30.Fa "proc_map_f *func" 31.Fa "void *data" 32.Fc 33.Ft int 34.Fo Pmapping_iter_resolved 35.Fa "struct ps_prochandle *P" 36.Fa "proc_map_f *func" 37.Fa "void *data" 38.Fc 39.Ft int 40.Fo Pobject_iter 41.Fa "struct ps_prochandle *P" 42.Fa "proc_map_f *func" 43.Fa "void *data" 44.Fc 45.Ft int 46.Fo Pobject_iter_resolved 47.Fa "struct ps_prochandle *P" 48.Fa "proc_map_f *func" 49.Fa "void *data" 50.Fc 51.Sh DESCRIPTION 52The 53.Fn Pmapping_iter 54and 55.Fn Pmapping_iter_resolved 56functions iterate over the memory mappings in the process represented by 57.Fa P. 58.Pp 59For each memory mapping, the callback function 60.Fa func 61will be invoked and it will be passed the 62.Fa data 63argument, 64the 65.Sy prmap_t 66structure defined from 67.Xr proc 5 , 68and a name of the mapping. 69The way that the name is obtained varies based on whether one calls 70.Fn Pmapping_iter 71or 72.Fn Pmapping_iter_resolved . 73In both cases, the dynamic linker is consulted to determine the file 74name for the mapping, if it's known. 75If the name is unknown, for example an anonymous mapping, then the 76.Dv NULL 77pointer is passed in for the name. 78In the case of the 79.Fn Pmapping_iter_resolved 80function the system tries to resolve it to a complete file system path. 81If that fails, it falls back to the information from the dynamic linker, 82before returning 83.Dv NULL 84in the case of not being able to find any name. 85For more information on the 86signature of the 87.Ft proc_map_f , 88see 89.Xr libproc 3LIB . 90.Pp 91The return value of 92.Fa func 93controls whether or not iteration continues. 94If 95.Fa func 96returns 97.Sy 0 98then iteration continues. 99If 100.Fa func 101returns non-zero then iteration will halt and the value will be 102returned to the caller. 103Because 104.Sy -1 105indicates internal failure, it is recommended that the callback function not 106return 107.Sy -1 108to indicate an error itself. 109This allows the caller to distinguish between failure of the callback function 110versus failure of the 111.Fn Pmapping_iter 112and 113.Fn Pmapping_iter_resolved 114functions. 115.Pp 116The 117.Fn Pobject_iter 118and 119.Fn Pobject_iter_resolved 120functions are similar to the 121.Fn Pmapping_iter 122and 123.Fn Pmapping_iter_resolved 124functions. 125Except, rather than iterating over every mapping, they iterate over the objects 126that the process has loaded by the dynamic linker. 127For example, an anonymous mapping will show up when iterating mappings, but will 128not show up when iterating objects. 129Further, while most dynamic shared objects have multiple mappings for the text 130and data sections, there will only be a single object that is iterated over. 131.Pp 132The distinction between the 133.Fn Pobject_iter 134and 135.Fn Pobject_iter_resolved 136functions is identical to the difference in name resolution between the 137.Fn Pmapping_iter 138and 139.Fn Pmapping_iter_resolved 140functions. 141.Sh RETURN VALUES 142Upon successful completion, the 143.Fn Pmapping_iter , 144.Fn Pmapping_iter_resolved 145.Fn Pobject_iter , 146and 147.Fn Pobject_iter_resolved 148functions return 149.Sy 0. 150Otherwise, if there was an internal error then 151.Sy -1 152is returned. 153Otherwise, if the callback function 154.Fa func 155returns non-zero, then its return value will be returned instead. 156.Sh INTERFACE STABILITY 157.Sy Uncommitted 158.Sh MT-LEVEL 159See 160.Sy LOCKING 161in 162.Xr libproc 3LIB . 163.Sh SEE ALSO 164.Xr libproc 3LIB , 165.Xr proc 5 166