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. The way that the name is obtained varies 68based 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. If the name is unknown, for example 74an anonymous mapping, then the 75.Dv NULL 76pointer is passed in for the name. In the case of the 77.Fn Pmapping_iter_resolved 78function the system tries to resolve it to a complete file system path. 79If that fails, it falls back to the information from the dynamic linker, 80before returning 81.Dv NULL 82in the case of not being able to find any name. 83For more information on the 84signature of the 85.Ft proc_map_f , 86see 87.Xr libproc 3LIB . 88.Pp 89The return value of 90.Fa func 91controls whether or not iteration continues. If 92.Fa func 93returns 94.Sy 0 95then iteration continues. If 96.Fa func 97returns non-zero then iteration will halt and the value will be 98returned to the caller. Because 99.Sy -1 100indicates internal failure, it is recommended that the callback 101function not return 102.Sy -1 103to indicate an error itself. This allows the caller to distinguish 104between failure of the callback function versus failure of the 105.Fn Pmapping_iter 106and 107.Fn Pmapping_iter_resolved 108functions. 109.Pp 110The 111.Fn Pobject_iter 112and 113.Fn Pobject_iter_resolved 114functions are similar to the 115.Fn Pmapping_iter 116and 117.Fn Pmapping_iter_resolved 118functions. Except, rather than iterating over every mapping, they 119iterate over the objects that the process has loaded by the dynamic 120linker. For example, an anonymous mapping will show up when iterating 121mappings, but will not show up when iterating objects. Further, while 122most dynamic shared objects have multiple mappings for the text and 123data sections, there will only be a single object that is iterated 124over. 125.Pp 126The distinction between the 127.Fn Pobject_iter 128and 129.Fn Pobject_iter_resolved 130functions is identical to the difference in name resolution between the 131.Fn Pmapping_iter 132and 133.Fn Pmapping_iter_resolved 134functions. 135.Sh RETURN VALUES 136Upon successful completion, the 137.Fn Pmapping_iter , 138.Fn Pmapping_iter_resolved 139.Fn Pobject_iter , 140and 141.Fn Pobject_iter_resolved 142functions return 143.Sy 0. 144Otherwise, if there was an internal error then 145.Sy -1 146is returned. Otherwise, if the callback function 147.Fa func 148returns non-zero, then its return value will be returned instead. 149.Sh INTERFACE STABILITY 150.Sy Uncommitted 151.Sh MT-LEVEL 152See 153.Sy LOCKING 154in 155.Xr libproc 3LIB . 156.Sh SEE ALSO 157.Xr libproc 3LIB , 158.Xr proc 4 159