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