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