share/man/man3proc/Paddr_to_map.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 PADDR_TO_MAP 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Paddr_to_map ,
  19 .Nm Paddr_to_text_map ,
  20 .Nm Plmid_to_map ,
  21 .Nm Pname_to_map
  22 .Nd lookup memory map information
  23 .Sh SYNOPSIS
  24 .Lb libproc
  25 .In libproc.h
  26 .Ft "const prmap_t *"
  27 .Fo Paddr_to_map
  28 .Fa "struct ps_prochandle *P"
  29 .Fa "uintptr_t addr"
  30 .Fc
  31 .Ft "const prmap_t *"
  32 .Fo Paddr_to_text_map
  33 .Fa "struct ps_prochandle *P"
  34 .Fa "uintptr_t addr"
  35 .Fc
  36 .Ft "const prmap_t *"
  37 .Fo Plmid_to_map
  38 .Fa "struct ps_prochandle *P"
  39 .Fa "Lmid_t lmid"
  40 .Fa "const char *name"
  41 .Fc
  42 .Ft "const prmap_t *"
  43 .Fo Pname_to_map
  44 .Fa "struct ps_prochandle *P"
  45 .Fa "const char *name"
  46 .Fc
  47 .Sh DESCRIPTION
  48 The
  49 .Fn Paddr_to_map ,
  50 .Fn Paddr_to_text_map ,
  51 .Fn Plmid_to_map ,
  52 and
  53 .Fn Pname_to_map
  54 functions lookup memory map information in the process handle
  55 .Fa P .
  56 The
  57 .Sy prmap_t
  58 structure provides information such as the size, offset, and object of
  59 the mapping and is defined in
  60 .Xr proc 4 .
  61 .Pp
  62 The pointer to the data returned by the library will only be valid for
  63 as long as the handle
  64 .Fa P
  65 is valid.
  66 Any calls to
  67 .Xr Prelease 3PROC
  68 will invalidate the data.
  69 .Pp
  70 The
  71 .Fn Paddr_to_map
  72 function attempts to find the mapping information corresponding to the
  73 address
  74 .Fa addr .
  75 .Pp
  76 The
  77 .Fn Paddr_to_text_map
  78 function is similar to the
  79 .Fn Paddr_to_map
  80 function; however, it only returns successfully if the specified address
  81 corresponds to a text mapping as identified by the run-time link-editor.
  82 One use of this is to ensure that a mapping is actually a text-mapping
  83 before inserting a breakpoint in it.
  84 .Pp
  85 The
  86 .Fn Pname_to_map
  87 function looks up the object named
  88 .Fa name
  89 and returns the corresponding mapping information.
  90 Two special values may be used for name.
  91 The macro
  92 .Dv PR_OBJ_EXEC
  93 refers to the executable object itself and the macro
  94 .Dv PR_OBJ_LDSO refers to the object ld.so.1 .
  95 .Pp
  96 The
  97 .Fn Plmid_to_map
  98 function is similar to
  99 .Fn Pname_to_map .
 100 It allows passing a link-map identifier,
 101 .Fa lmid ,
 102 which constricts the search of the object named with
 103 .Fa name
 104 to that link-map.
 105 The special value of
 106 .Dv PR_LMID_EVERY
 107 may be passed to indicate that every link-map should be searched, which
 108 is equivalent in behavior to the
 109 .Fn Pname_to_map
 110 function.
 111 .Sh RETURN VALUES
 112 Upon successful completion, the
 113 .Fn Paddr_to_map ,
 114 .Fn Paddr_to_text_map ,
 115 .Fn Plmid_to_map ,
 116 and
 117 .Fn Pname_to_map
 118 functions return a pointer to the corresponding mapping information.
 119 If none exists then
 120 .Dv NULL
 121 is returned.
 122 .Sh INTERFACE STABILITY
 123 .Sy Uncommitted
 124 .Sh MT-LEVEL
 125 See
 126 .Sy LOCKING
 127 in
 128 .Xr libproc 3LIB .
 129 .Sh SEE ALSO
 130 .Xr libproc 3LIB ,
 131 .Xr Prelease 3PROC ,
 132 .Xr proc 4