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