usr/src/man/man3proc/Paddr_to_loadobj.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_LOADOBJ 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Paddr_to_loadobj ,
  19 .Nm Plmid_to_loadobj ,
  20 .Nm Pname_to_loadobj
  21 .Nd lookup loaded object information
  22 .Sh SYNOPSIS
  23 .Lb libproc
  24 .In libproc.h
  25 .Ft "const rd_loadobj_t *"
  26 .Fo Paddr_to_loadobj
  27 .Fa "struct ps_prochandle *P"
  28 .Fa "uintptr_t addr"
  29 .Fc
  30 .Ft "const rd_loadobj_t *"
  31 .Fo Plmid_to_loadobj
  32 .Fa "struct ps_prochandle *P"
  33 .Fa "Lmid_t lmid"
  34 .Fa "const char *name"
  35 .Fc
  36 .Ft "const rd_loadobj_t *"
  37 .Fo Pname_to_loadobj
  38 .Fa "struct ps_prochandle *P"
  39 .Fa "const char *name"
  40 .Fc
  41 .Sh DESCRIPTION
  42 The
  43 .Fn Paddr_to_loadobj ,
  44 .Fn Plmid_to_loadobj ,
  45 and
  46 .Fn Pname_to_loadobj
  47 functions lookup loaded object information from the process handle
  48 .Fa P .
  49 This information is provided by the run-time link-editor,
  50 .Xr ld.so.1 1 ,
  51 and provides information about the loaded object such as the link-map
  52 identifier, the TLS module ID, and the address of various sections.
  53 .Pp
  54 The pointer to the data returned by the library will only be valid for
  55 as long as the handle
  56 .Fa P
  57 is valid.
  58 Any calls to
  59 .Xr Prelease 3PROC
  60 will invalidate the data.
  61 .Pp
  62 The
  63 .Fn Paddr_to_loadobj
  64 function attempts to find the loaded object information, if any, that exists for
  65 the address
  66 .Fa addr .
  67 Not all address correspond to memory regions that were loaded by the
  68 run-time link-editor.
  69 For example, if a user creates a region of anonymous memory through the
  70 .Xr mmap 2
  71 function, then it will not have any corresponding loaded module.
  72 .Pp
  73 The
  74 .Fn Pname_to_loadobj
  75 function looks up the object named
  76 .Fa name
  77 and returns the corresponding loaded object information.
  78 Two special values may be used for name.
  79 The macro
  80 .Dv PR_OBJ_EXEC
  81 refers to the executable object itself and the macro
  82 .Dv PR_OBJ_LDSO refers to the object ld.so.1 .
  83 .Pp
  84 The
  85 .Fn Plmid_to_loadobj
  86 function is similar to
  87 .Fn Pname_to_loadobj .
  88 It allows the use of a link-map identifier,
  89 .Fa lmid ,
  90 which constricts the search of the object named with
  91 .Fa name
  92 to that link-map.
  93 The special value of
  94 .Dv PR_LMID_EVERY
  95 may be passed to indicate that every link-map should be searched, which
  96 is equivalent in behavior to the
  97 .Fn Pname_to_loadobj
  98 function.
  99 .Sh RETURN VALUES
 100 Upon successful completion, the
 101 .Fn Paddr_to_loadobj ,
 102 .Fn Plmid_to_loadobj ,
 103 and
 104 .Fn Pname_to_loadobj
 105 functions return a pointer to the corresponding loadable object
 106 information.
 107 Otherwise, if none exists then
 108 .Dv NULL
 109 is returned.
 110 .Sh INTERFACE STABILITY
 111 .Sy Uncommitted
 112 .Sh MT-LEVEL
 113 See
 114 .Sy LOCKING
 115 in
 116 .Xr libproc 3LIB .
 117 .Sh SEE ALSO
 118 .Xr libproc 3LIB ,
 119 .Xr librtld_db 3LIB ,
 120 .Xr Prelease 3PROC