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