share/man/man3proc/Pmapping_iter.3proc

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