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