share/man/man3proc/Pobjname.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 POBJNAME 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pobjname ,
  19 .Nm Pobjname_resolved
  20 .Nd turn a virtual address into its mapped object
  21 .Sh SYNOPSIS
  22 .Lb libproc
  23 .In libproc.h
  24 .Ft "char *"
  25 .Fo Pobjname
  26 .Fa "struct ps_prochandle *P"
  27 .Fa "uintptr_t addr"
  28 .Fa "char *buffer"
  29 .Fa "size_t bufsize"
  30 .Fc
  31 .Ft char *
  32 .Fo Pobjname_resolved
  33 .Fa "struct ps_prochandle *P"
  34 .Fa "uintptr_t addr"
  35 .Fa "char *buffer"
  36 .Fa "size_t bufsize"
  37 .Fc
  38 .Sh DESCRIPTION
  39 The
  40 .Fn Pobjname
  41 and
  42 .Fn Pobjname_resolved
  43 functions attempt to determine the underlying mapped object that
  44 contains the virtual address
  45 .Fa addr
  46 in the process handle
  47 .Fa P .
  48 .Pp
  49 A program consists of multiple memory mappings.
  50 Some are provided by the system, such as the stack and the heap.
  51 While others are created through explicit calls to
  52 .Xr mmap 2
  53 or brought in by the run-time link-editor due to dependencies
  54 specified in binaries and libraries.
  55 .Pp
  56 If
  57 .Fa addr
  58 is contained in a mapping, then up to
  59 .Fa bufsize
  60 characters, including the null terminator,
  61 of the name of the corresponding object will be written into
  62 .Fa buffer .
  63 The
  64 .Fn Pobjname_resolved
  65 function attempts to resolve the object to a full file system path.
  66 If the full file-system path cannot be determined, then it will fall back
  67 to the name that the run-time link-editor has for that mapping, which is
  68 the behavior of
  69 .Fn Pobjname .
  70 .Sh RETURN VALUES
  71 Upon successful completion, the
  72 .Fn Pobjname
  73 and
  74 .Fn Pobjname_resolved
  75 functions return
  76 .Fa buffer .
  77 Otherwise,
  78 .Dv NULL
  79 is returned to indicate the object name could not be found.
  80 .Sh INTERFACE STABILITY
  81 .Sy Uncommitted
  82 .Sh MT-LEVEL
  83 See
  84 .Sy LOCKING
  85 in
  86 .Xr libproc 3LIB .
  87 .Sh SEE ALSO
  88 .Xr mmap 2 ,
  89 .Xr libproc 3LIB ,
  90 .Xr Pobject_iter 3PROC ,
  91 .Xr proc 4