usr/src/man/man3proc/Paddr_to_ctf.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_CTF 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Paddr_to_ctf ,
  19 .Nm Plmid_to_ctf ,
  20 .Nm Pname_to_ctf
  21 .Nd lookup CTF data
  22 .Sh SYNOPSIS
  23 .Lb libproc
  24 .In libproc.h
  25 .Ft "ctf_file_t *"
  26 .Fo Paddr_to_ctf
  27 .Fa "struct ps_prochandle *P"
  28 .Fa "uintptr_t addr"
  29 .Fc
  30 .Ft "ctf_file_t *"
  31 .Fo Plmid_to_ctf
  32 .Fa "struct ps_prochandle *P"
  33 .Fa "Lmid_t lmid"
  34 .Fa "const char *name"
  35 .Fc
  36 .Ft "ctf_file_t *"
  37 .Fo Pname_to_ctf
  38 .Fa "struct ps_prochandle *P"
  39 .Fa "const char *name"
  40 .Fc
  41 .Sh DESCRIPTION
  42 The
  43 .Fn Paddr_to_ctf ,
  44 .Fn Plmid_to_ctf ,
  45 and
  46 .Fn Pname_to_ctf
  47 functions lookup CTF (Compact C Type Format) data, for use with
  48 .Sy libctf ,
  49 from the process represented by the handle
  50 .Fa P .
  51 In all cases, the CTF sections of both the running executable and its
  52 shared libraries are searched.
  53 .Pp
  54 The CTF container returned is valid as long as the process handle
  55 .Fa P
  56 is valid.
  57 That is, until a call to
  58 .Xr Prelease 3PROC
  59 is made.
  60 Further, consumers must not close the CTF container.
  61 .Pp
  62 The
  63 .Fn Paddr_to_ctf
  64 function attempts to find the CTF section, if any, that exists for the
  65 address
  66 .Fa addr .
  67 Note, not all addresses correspond to memory regions that have CTF
  68 data.
  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 CTF information.
  72 .Pp
  73 The
  74 .Fn Pname_to_ctf
  75 function looks up the object named
  76 .Fa name
  77 and returns the corresponding CTF section, if any exists.
  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_ctf
  86 function is similar to
  87 .Fn Pname_to_ctf .
  88 It allows the passing 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 indicates that every link-map should be searched, which is equivalent
  96 in behavior to the
  97 .Fn Pname_to_ctf
  98 function.
  99 .Sh RETURN VALUES
 100 Upon successful completion, the
 101 .Fn Paddr_to_ctf ,
 102 .Fn Plmid_to_ctf ,
 103 and
 104 .Fn Pname_to_ctf
 105 functions return a pointer to the corresponding CTF container.
 106 Otherwise, if none exists then
 107 .Dv NULL
 108 is returned.
 109 .Sh INTERFACE STABILITY
 110 .Sy Uncommitted
 111 .Sh MT-LEVEL
 112 See
 113 .Sy LOCKING
 114 in
 115 .Xr libproc 3LIB .
 116 .Sh SEE ALSO
 117 .Xr libproc 3LIB ,
 118 .Xr ctf 4