1 LIBPROC(3LIB)                 Interface Libraries                LIBPROC(3LIB)
   2 
   3 NAME
   4      libproc - process control library
   5 
   6 SYNOPSIS
   7      Process Control Library (libproc, -lproc)
   8      #include <libproc.h>
   9 
  10 DESCRIPTION
  11      The libproc library provides consumers a general series of interfaces to
  12      inspect and control both live processes and core files.  It is intended
  13      for introspection tools such as debuggers by providing a high-level
  14      interface to the /proc file system (proc(4)).
  15 
  16      The libproc library provides interfaces that focus on:
  17 
  18            o   Creating and attaching to live process, core files, and
  19                arbitrary ELF objects.
  20 
  21            o   Interrogating the state of a process or core file.
  22 
  23            o   Manipulating the current state of a process or thread.
  24 
  25            o   Interrogating the state of threads of a process or core file.
  26 
  27            o   Running system calls in the context of another process.
  28 
  29            o   Various utilities for iterating process and core file file
  30                descriptors, mappings, symbols, and more.
  31 
  32            o   Various utilities to support debugging tools.
  33 
  34    Live Processes
  35      The libproc library can be used to manipulate running processes and to
  36      create new ones.  To manipulate an existing process first grab it with
  37      the Pgrab function.  A process is generally stopped as a side effect of
  38      grabbing it.  Callers must exercise caution, as if they do not use the
  39      library correctly, or they terminate unexpectedly, a process may remain
  40      stopped.
  41 
  42      Unprivileged users may only grab their own processes.  Users with the
  43      privilege PRIV_PROC_OWNER may manipulate processes that they do not own;
  44      however, additional restrictions as described in privileges(5) apply.
  45 
  46      In addition, the Pcreate() and Pxcreate() functions may be used to create
  47      processes which are always controlled by the library.
  48 
  49    Core Files
  50      The libproc library has the ability to open and interpret core files
  51      produced by processes on the system.  Process core dump generation is
  52      controlled by the coreadm(1M) command.  In addition, the library has the
  53      ability to understand and interpret core dumps generated by Linux kernel
  54      and can provide a subset of its functionality on such core files,
  55      provided the original binary is also present.
  56 
  57      Not all functions in the libproc library are valid for core files.  In
  58      general, none of the commands which manipulate the current state of a
  59      process or thread or that try to force system calls on a victim process
  60      will work.  Furthermore several of the information and iteration
  61      interfaces are limited based on the data that is available in the core
  62      file.  For example, if the core file is of a process that omits the frame
  63      pointer, the ability to iterate the stack will be limited.
  64 
  65      Use the Pgrab_core() or Pfgrab_core() function to open a core file.  Use
  66      the Pgrab_file() function to open an ELF object file.  This is useful for
  67      obtaining information stored in ELF headers and sections.
  68 
  69    Debug Information
  70      Many of the operations in the library rely on debug information being
  71      present in a process and its associated libraries.  The library leverages
  72      symbol table information, CTF data (CTF(4)) sections, and frame unwinding
  73      information based on the use of an ABI defined frame pointer, eg.  %ebp
  74      and %rbp on x86 systems.
  75 
  76      Some software providers strip programs of this information or build their
  77      executables such that the information will not be present in a core dump.
  78      To deal with this fact, the library is able to consume information that
  79      is not present in the core file or the running process.  It can both
  80      consume it from the underlying executable and it also supports finding it
  81      from related ELF objects that are linked to it via the .gnu_debuglink and
  82      the .note.gnu.build-id ELF sections.
  83 
  84    Iteration Interfaces
  85      The libproc library provides the ability to iterate over the following
  86      aspects of a process or core file:
  87 
  88            o   Active threads
  89 
  90            o   Active and zombie threads
  91 
  92            o   All non-system processes
  93 
  94            o   All process mappings
  95 
  96            o   All objects in a process
  97 
  98            o   The environment
  99 
 100            o   The symbol table
 101 
 102            o   Stack frames
 103 
 104            o   File Descriptors
 105 
 106    System Call Injection
 107      The libproc library allows the caller to force system calls to be
 108      executed in the context of the running process.  This can be used both as
 109      a tool for introspection, allowing one to get information outside its
 110      current context as well as performing modifications to a process.
 111 
 112      These functions run in the context of the calling process.  This is often
 113      an easier way of getting non-exported information about a process from
 114      the system.  For example, the pfiles(1) command uses this interface to
 115      get more detailed information about a process's open file descriptors,
 116      which it would not have access to otherwise.
 117 
 118 INTERFACES
 119      The shared object libproc.so.1 provides the public interfaces defined
 120      below.  See Intro(3) for additional information on shared object
 121      interfaces.  Functions are organized into categories that describe their
 122      purpose.  Individual functions are documented in their own manual pages.
 123 
 124    Creation, Grabbing, and Releasing
 125      The following routines are related to creating library handles, grabbing
 126      cores, processes, and threads, and releasing those resources.
 127 
 128            Lfree                         Lgrab
 129            Lgrab_error                   Pcreate
 130            Pcreate_agent                 Pcreate_callback
 131            Pcreate_error                 Pdestroy_agent
 132            Pfgrab_core                   Pfree
 133            Pgrab                         Pgrab_core
 134            Pgrab_error                   Pgrab_file
 135            Pgrab_ops                     Prelease
 136            Preopen                       Pxcreate
 137 
 138    Process interrogation and manipulation
 139      The following routines obtain information about a process and allow
 140      manipulation of the process itself.
 141 
 142            Paddr_to_ctf                  Paddr_to_loadobj
 143            Paddr_to_map                  Paddr_to_text_map
 144            Pasfd                         Pclearfault
 145            Pclearsig                     Pcontent
 146            Pcred                         Pctlfd
 147            Pdelbkpt                      Pdelwapt
 148            Pdstop                        Pexecname
 149            Pfault                        Pfgcore
 150            Pgcore                        Pgetareg
 151            Pgetauxval                    Pgetauxvec
 152            Pgetenv                       Pisprocdir
 153            Pissyscall_prev               Plmid
 154            Plmid_to_loadobj              Plmid_to_map
 155            Plookup_by_addr               Plookup_by_name
 156            Plwp_alt_stack                Plwp_getfpregs
 157            Plwp_getname                  Plwp_getpsinfo
 158            Plwp_getregs                  Plwp_getspymaster
 159            Plwp_main_stack               Plwp_setfpregs
 160            Plwp_setregs                  Plwp_stack
 161            Pname_to_ctf                  Pname_to_loadobj
 162            Pname_to_map                  Pobjname
 163            Pobjname_resolved             Pplatform
 164            Ppltdest                      Ppriv
 165            Ppsinfo                       Pputareg
 166            Prd_agent                     Pread
 167            Pread_string                  Preset_maps
 168            Psetbkpt                      Psecflags
 169            Psetcred                      Psetfault
 170            Psetflags                     Psetpriv
 171            Psetrun                       Psetsignal
 172            Psetsysentry                  Psetsysexit
 173            Psetwapt                      Psetzoneid
 174            Psignal                       Pstate
 175            Pstatus                       Pstop
 176            Pstopstatus                   Psync
 177            Psysentry                     Psysexit
 178            Puname                        Punsetflags
 179            Pupdate_maps                  Pupdate_syms
 180            Pwait                         Pwrite
 181            Pxecbkpt                      Pxecwapt
 182            Pxlookup_by_addr              Pxlookup_by_addr_resolved
 183            Pxlookup_by_name              Pzonename
 184            Pzonepath                     Pzoneroot
 185 
 186    Thread interrogation and manipulation
 187      The following routines obtain information about a thread and allow
 188      manipulation of the thread itself.
 189 
 190            Lalt_stack                    Lclearfault
 191            Lclearsig                     Lctlfd
 192            Ldstop                        Lgetareg
 193            Lmain_stack                   Lprochandle
 194            Lpsinfo                       Lputareg
 195            Lsetrun                       Lstack
 196            Lstate                        Lstatus
 197            Lstop                         Lsync
 198            Lwait                         Lxecbkpt
 199            Lxecwapt
 200 
 201    System Call Injection
 202      The following routines are used to inject specific system calls and have
 203      them run in the context of a process.
 204 
 205            pr_access                     pr_close
 206            pr_creat                      pr_door_info
 207            pr_exit                       pr_fcntl
 208            pr_fstat                      pr_fstat64
 209            pr_fstatvfs                   pr_getitimer
 210            pr_getpeername                pr_getpeerucred
 211            pr_getprojid                  pr_getrctl
 212            pr_getrlimit                  pr_getrlimit64
 213            pr_getsockname                pr_getsockopt
 214            pr_gettaskid                  pr_getzoneid
 215            pr_ioctl                      pr_link
 216            pr_llseek                     pr_lseek
 217            pr_lstat                      pr_lstat64
 218            pr_memcntl                    pr_meminfo
 219            pr_mmap                       pr_munmap
 220            pr_open                       pr_processor_bind
 221            pr_rename                     pr_setitimer
 222            pr_setrctl                    pr_setrlimit
 223            pr_setrlimit64                pr_settaskid
 224            pr_sigaction                  pr_stat
 225            pr_stat64                     pr_statvfs
 226            pr_unlink                     pr_waitid
 227 
 228    Iteration routines
 229      These routines are used to iterate over the contents of a process.
 230 
 231            Penv_iter                     Plwp_iter
 232            Plwp_iter_all                 Pmapping_iter
 233            Pmapping_iter_resolved        Pobject_iter
 234            Pobject_iter_resolved         Pstack_iter
 235            Psymbol_iter                  Psymbol_iter_by_addr
 236            Psymbol_iter_by_lmid          Psymbol_iter_by_name
 237            Pxsymbol_iter                 Pfdinfo_iter
 238 
 239    Utility routines
 240      The following routines are utilities that are useful to consumers of the
 241      library.
 242 
 243            Perror_printf                 proc_arg_grab
 244            proc_arg_psinfo               proc_arg_xgrab
 245            proc_arg_xpsinfo              proc_content2str
 246            proc_finistdio                proc_fltname
 247            proc_fltset2str               proc_flushstdio
 248            proc_get_auxv                 proc_get_cred
 249            proc_get_priv                 proc_get_psinfo
 250            proc_get_status               proc_initstdio
 251            proc_lwp_in_set               proc_lwp_range_valid
 252            proc_signame                  proc_sigset2str
 253            proc_str2content              proc_str2flt
 254            proc_str2fltset               proc_str2sig
 255            proc_str2sigset               proc_str2sys
 256            proc_str2sysset               proc_sysname
 257            proc_sysset2str               proc_unctrl_psinfo
 258            proc_walk
 259 
 260    x86 Specific Routines
 261      The following routines are specific to the x86, 32-bit and 64-bit,
 262      versions of the libproc library.
 263 
 264            Pldt                          proc_get_ldt
 265 
 266    SPARC specific Routines
 267      The following functions are specific to the SPARC, 32-bit and 64-bit,
 268      versions of the libproc library.
 269 
 270            Plwp_getgwindows              Plwp_getxregs
 271            Plwp_setxregs
 272 
 273      The following functions are specific to the 64-bit SPARC version of the
 274      libproc library.
 275 
 276            Plwp_getasrs                  Plwp_setasrs
 277 
 278 PROCESS STATES
 279      Every process handle that exists in libproc has a state.  In some cases,
 280      such as for core files, these states are static.  In other cases, such as
 281      handles that correspond to a running process or a created process, these
 282      states are dynamic and change based on actions taken in the library.  The
 283      state can be obtained with the Pstate(3PROC) function.
 284 
 285      The various states are:
 286 
 287            PS_RUN        An actively running process.  This may be a process
 288                          that was obtained by creating it with functions such
 289                          as Pcreate(3PROC) or by grabbing an existing process
 290                          such as Pgrab(3PROC).
 291 
 292            PS_STOP       An active process that is no longer executing.  A
 293                          process may stop for many reasons such as an explicit
 294                          stop request (through pstop(1) for example) or if a
 295                          tracing event is hit.
 296 
 297                          The reason a process is stopped may be obtained
 298                          through the thread's lwpstatus_t structure read
 299                          directly from /proc or obtained through the
 300                          Lstatus(3PROC) function.
 301 
 302            PS_LOST       Control over the process has been lost.  This may
 303                          happen when the process executes a new image
 304                          requiring a different set of privileges.  To resume
 305                          control call Preopen(3PROC).  For more information on
 306                          losing control of a process, see proc(4).
 307 
 308            DV PS_UNDEAD  A zombie process.  It has terminated, but it has not
 309                          been cleaned up yet by its parent.  For more on the
 310                          conditions of becoming a zombie, see exec(2).
 311 
 312            DV_PS_DEAD    Processes in this state are always core files.  See
 313                          the earlier section Core Files for more information
 314                          on working with core files.
 315 
 316            PS_IDLE       A process that has never been run.  This is always
 317                          the case for handles that refer to files as the files
 318                          cannot be executed.  Those process handles are
 319                          obtained through calling Pgrab_file(3PROC).
 320 
 321      Many functions relating to tracing processes, for example Psignal(3PROC),
 322      Psetsignal(3PROC), Psetfault(3PROC), Psysentry(3PROC), and others,
 323      mention that they only act upon Active Processes.  This specifically
 324      refers to processes whose state are in PS_RUN and PS_STOP.  Process
 325      handles in the other states have no notion of settable tracing flags,
 326      though core files (type PS_DEAD) may have a read-only snapshot of their
 327      tracing settings available.
 328 
 329 TYPES
 330      The libproc library uses many types that come from the /proc file system
 331      (proc(4)) and the ELF format (elf(3ELF)).  However, it also defines the
 332      following types:
 333 
 334      struct ps_prochandle
 335 
 336      The struct ps_prochandle is an opaque handle to the library and the core
 337      element of control for a process.  Consumers obtain pointers to a handle
 338      through the use of the Pcreate(), Pgrab(), and related functions.  When a
 339      caller is done with a handle, then it should call one of the Pfree() and
 340      Prelease() functions to relinquish the handle, release associated
 341      resources, and potentially set the process to run again.
 342 
 343      struct ps_lwphandle
 344 
 345      The struct ps_lwphandle is analogous to the struct ps_prochandle, but it
 346      represents the control of an individual thread, rather than a process.
 347      Consumers obtain pointers to a handle through the Lgrab() function and
 348      relinquish it with the Lfree() function.
 349 
 350      core_content_t
 351 
 352      The core_content_t is a value which describes the various content types
 353      of core files.  These are used in functions such as Pcontent(3PROC) and
 354      Pgcore(3PROC) to describe and control the types of content that get
 355      included.  Various content types may be included together through a
 356      bitwise-inclusive-OR.  The default system core contents are controlled
 357      with the coreadm(1M) tool.  The following table lists the current set of
 358      core contents in the system, though the set may increase over time.  The
 359      string after the macro is the human readable string that corresponds with
 360      the constant and is used by coreadm(1M), proc_content2str(3PROC), and
 361      proc_str2content(3PROC).
 362 
 363            CC_CONTENT_STACK ("stack")
 364                    The contents include the process stack.  Note, this only
 365                    covers the main thread's stack.  The stack of other threads
 366                    is covered by CC_CONTENT_ANON.
 367 
 368            CC_CONTENT_HEAP ("heap")
 369                    The contents include the process heap.
 370 
 371            CC_CONTENT_SHFILE ("shfile")
 372                    The contents include shared mappings that are backed by
 373                    files (e.g.  mapped through mmap(2) with the MAP_SHARED
 374                    flag).
 375 
 376            CC_CONTENT_SHANNON ("shannon")
 377                    The contents include shared mappings that are backed by
 378                    anonymous memory (e.g. mapped through mmap(2) with the
 379                    MAP_SHARED and MAP_ANON flags).
 380 
 381            CC_CONTENT_RODATA ("rodata")
 382                    The contents include private read-only file mappings, such
 383                    as shared library text.
 384 
 385            CC_CONTENT_ANON ("anon")
 386                    The contents include private anonymous mappings.  This
 387                    includes the stacks of threads which are not the main
 388                    thread.
 389 
 390            CC_CONTENT_SHM ("shm")
 391                    The contents include system V shared memory.
 392 
 393            CC_CONTENT_ISM ("ism")
 394                    The contents include ISM (intimate shared memory) mappings.
 395 
 396            CC_CONTENT_DISM ("dism")
 397                    The contents include DISM (dynamic shared memory) mappings.
 398 
 399            CC_CONTENT_CTF ("ctf")
 400                    The contents include ctf(4) (Compact C Type Format)
 401                    information.  Note, not all objects in the process may have
 402                    CTF information available.
 403 
 404            CC_CONTENT_SYMTAB ("symtab")
 405                    The contents include the symbol table.  Note, not all
 406                    objects in the process may have a symbol table available.
 407 
 408            CC_CONTENT_ALL ("all")
 409                    This value indicates that all of the above content values
 410                    are present.  Note that additional values may be added in
 411                    the future, in which case the value of the symbol will be
 412                    updated to include them.  Comparisons with CC_CONTENT_ALL
 413                    should validate all the expected bits are set by an
 414                    expression such as (c & CC_CONTENT_ALL) == CC_CONTENT_ALL.
 415 
 416            CC_CONTENT_NONE ("none")
 417                    This value indicates that there is no content present.
 418 
 419            CC_CONTENT_DEFAULT ("default")
 420                    The content includes the following set of default values:
 421                    CC_CONTENT_STACK, CC_CONTENT_HEAP, CC_CONTENT_ISM,
 422                    CC_CONTENT_DISM, CC_CONTENT_SHM, CC_CONTENT_SHANON,
 423                    CC_CONTENT_TEXT, CC_CONTENT_DATA, CC_CONTENT_RODATA,
 424                    CC_CONTENT_ANON, CC_CONTENT_CTF, and CC_CONTENT_SYMTAB.
 425                    Note that the default may change.  Comparisons with
 426                    CC_CONTENT_DEFAULT should validate that all of the expected
 427                    bits are set with an expression such as
 428                    (c &     CC_CONTENT_DEFAULT) == CC_CONTENT_DEFAULT.
 429 
 430            CC_CONTENT_INVALID
 431                    This indicates that the contents are invalid.
 432 
 433      prfdinfo_t
 434 
 435      The prfdinfo_t structure is used with the Pfdinfo_iter() function which
 436      describes information about a file descriptor.  The structure is defined
 437      as follows:
 438 
 439      typedef struct prfdinfo {
 440              int             pr_fd;
 441              mode_t          pr_mode;
 442              uid_t           pr_uid;
 443              gid_t           pr_gid;
 444              major_t         pr_major;       /* think stat.st_dev */
 445              minor_t         pr_minor;
 446              major_t         pr_rmajor;      /* think stat.st_rdev */
 447              minor_t         pr_rminor;
 448              ino64_t         pr_ino;
 449              off64_t         pr_offset;
 450              off64_t         pr_size;
 451              int             pr_fileflags;   /* fcntl(F_GETXFL), etc */
 452              int             pr_fdflags;     /* fcntl(F_GETFD), etc. */
 453              char            pr_path[MAXPATHLEN];
 454      } prfdinfo_t;
 455 
 456      The structure has similar information to that found in the stat structure
 457      that's used as part of the stat family of system calls, defined in
 458      stat(2).  The member pr_fd contains the number of the file descriptor of
 459      the file.  The members pr_mode, pr_uid, pr_gid, pr_ino, and pr_size are
 460      the same as the members st_mode, st_uid, st_gid, st_ino, and st_size in
 461      the stat structure.
 462 
 463      The pr_major and pr_minor members contain the major and minor numbers of
 464      the device containing the directory for this file.  This is similar to
 465      the st_dev member of the stat structure, except that it is broken out
 466      into its major and minor components.  The pr_rmajor and pr_rminor members
 467      are similar in spirit to pr_major and pr_minor; however, they are
 468      equivalent to the st_rdev member of the stat structure and thus have
 469      meaning for special character and block files.
 470 
 471      The pr_offset member contains the current seek offset of the file
 472      descriptor.  The pr_fileflags and pr_fdflags members contain the flags
 473      that would have been returned by a call to fcntl(2) with the arguments
 474      F_GETXFL and F_GETFD respectively.
 475 
 476      prsyminfo_t
 477 
 478      The prsyminfo_t structure is used with the various symbol look up
 479      functions Pxlookup_by_name(), Pxlookup_by_addr(), and
 480      Pxlookup_by_addr_resolved() which describes additional information about
 481      a symbol.  The structure is defined as follows:
 482 
 483      typedef struct prsyminfo {
 484              const char      *prs_object;            /* object name */
 485              const char      *prs_name;              /* symbol name */
 486              Lmid_t          prs_lmid;               /* link map id */
 487              uint_t          prs_id;                 /* symbol id */
 488              uint_t          prs_table;              /* symbol table id */
 489      } prsyminfo_t;
 490 
 491      The member prs_object points to a string that contains the name of the
 492      object file, if known, that the symbol comes from.  The member prs_name
 493      points to the name of the symbol, if known.  This may be unknown due to a
 494      stripped binary that contains no symbol table.  The member prs_lmid
 495      indicates the link map identifier that the symbol was found on.  For more
 496      information on link map identifiers refer to the Linker and Libraries
 497      Guide and dlopen(3C).
 498 
 499      The members prs_id and prs_table can be used to determine both the symbol
 500      table that the entry came from and which entry in the table it
 501      corresponds to.  If the value of prs_table is PR_SYMTAB then it came from
 502      the ELF standard symbol table.  However, if it is instead PR_DYNSYM, then
 503      that indicates that it comes from the process's dynamic section.
 504 
 505      proc_lwp_f
 506 
 507      The proc_lwp_f is a function pointer type that is used with the
 508      Plwp_iter() function.  It is defined as typedef int proc_lwp_f(void *,
 509      const lwpstatus_t *).  The first argument is a pointer to an argument
 510      that the user specifies, while the second has the thread's status
 511      information and is defined in proc(4).  For additional information on
 512      using this type, see Plwp_iter(3PROC).
 513 
 514      proc_lwp_all_f
 515 
 516      The proc_lwp_all_f is a function pointer type that is used with the
 517      Plwp_iter_all() function.  It is defined as typedef int
 518      proc_lwp_all_f(void *, const lwpstatus_t *, const lwpsinfo_t *).  The
 519      first argument is a pointer to an argument that the user specifies.  The
 520      second and third arguments contain the thread's status and thread-
 521      specific ps(1) information respectively.  Both structures are defined in
 522      proc(4).  For additional information on using this type, see
 523      Plwp_iter_all(3PROC).
 524 
 525      proc_walk_f
 526 
 527      The proc_walk_f is a function pointer type that is used with the
 528      proc_walk() function.  It is defined as typedef int
 529      proc_walk_f(psinfo_t *, lwpsinfo_t *, void *).  The first argument
 530      contains the process ps(1) information and the second argument contains
 531      the representative thread's ps(1) information.  Both structures are
 532      defined in proc(4).  The final argument is a pointer to an argument that
 533      the user specifies.  For more information on using this, see
 534      proc_walk(3PROC).
 535 
 536      proc_map_f
 537 
 538      The proc_map_f is a function pointer type that is used with the
 539      Pmapping_iter(), Pmapping_iter_resolved(), Pobject_iter(), and
 540      Pobject_iter_resolved() functions.  It is defined as typedef int
 541      proc_map_f(void *, const prmap_t *, const char *).  The first argument is
 542      a pointer to an argument that the user specifies.  The second argument is
 543      describes the mapping information and is defined in proc(4).  The final
 544      argument contains the name of the mapping or object file in question.
 545      For additional information on using this type, see Pmapping_iter(3PROC).
 546 
 547      proc_env_f
 548 
 549      The proc_env_f is a function pointer type that is used with the
 550      Penv_iter() function.  It is defined as typedef int proc_env_f(void *,
 551      struct ps_prochandle *, uintptr_t, const char *).  The first argument is
 552      a pointer to an argument that the user specifies.  The second argument is
 553      a pointer to the struct ps_prochandle that the callback was passed to.
 554      The third argument is the address of the environment variable in the
 555      process.  The fourth argument is the environment variable.  Values in the
 556      environment follow the convention of the form variable=value.  For more
 557      information on environment variables see exec(2) and environ(5).  For
 558      additional information on using this type, see Penv_iter(3PROC).
 559 
 560      proc_sym_f
 561 
 562      The proc_sym_f is a function pointer type that is used with the
 563      Psmbol_iter(), Psymbol_iter_by_addr(), Psymbol_iter_by_name(), and
 564      Psymbol_iter_by_lmid() functions.  It is defined as typedef int
 565      proc_sym_f(void *, const GElf_Sym *, const char *).  The first argument
 566      is a pointer to an argument that the user supplies.  The second argument
 567      is a pointer to the ELF symbol information in a 32-bit and 64-bit neutral
 568      form.  See elf(3ELF) and gelf(3ELF) for more information on it.  The
 569      final argument points to a character string that has the name of the
 570      symbol.  For additional information on using this type, see
 571      Psymbol_iter(3PROC), Psymbol_iter_by_addr(3PROC),
 572      Psymbol_iter_by_name(3PROC), and Psymbol_iter_by_lmid(3PROC).
 573 
 574      proc_xsym_f
 575 
 576      The proc_xsym_f is a function pointer type that is used with the
 577      Pxsymbol_iter() function.  It is defined as typedef int
 578      proc_xsym_f(void *, const GElf_Sym *, const char *, const prsyminfo_t *).
 579      The first three arguments are identical to those of proc_sym_f.  The
 580      final argument contains additional information about the symbol itself.
 581      The members of the prsyminfo_t are defined earlier in this section.  For
 582      additional information on using this type, see Pxsymbol_iter(3PROC).
 583 
 584      proc_stack_f
 585 
 586      The proc_stack_f is a function pointer type that is used with the
 587      Pstack_iter() function.  It is defined as typedef int
 588      proc_stack_f(void *, prgregset_t, uint_t, const long *).  The first
 589      argument is a pointer to an argument that the user specifies.  The second
 590      argument's contents are platform specific.  The registers that contain
 591      stack information, usually the stack pointer and frame pointer, will be
 592      filled in to point to an entry.  The prgregset_t is defined in proc(4).
 593 
 594      The third argument contains the number of arguments to the current stack
 595      frame and the fourth argument contains an array of addresses that
 596      correspond to the arguments to that stack function.  The value of the
 597      third argument dictates the number of entries in the fourth argument.
 598      For additional information on using this type, see Pstack_iter(3PROC).
 599 
 600      proc_fdinfo_f
 601 
 602      The proc_fdinfo_f is a function pointer type that is used with the
 603      Pfdinfo_iter() function.  It is defined as typedef int
 604      proc_fdinfo_f(void *, prfdinfo_t *).  The first argument is a pointer to
 605      an argument that the user specifies.  The second argument contains
 606      information about an open file descriptor.  The members of the prfdinfo_t
 607      are defined earlier in this section.  For additional information on using
 608      this type, see Pfdinfo_iter(3PROC).
 609 
 610 PROGRAMMING NOTES
 611      When working with live processes, whether from the Pgrab(3PROC) or
 612      Pcreate(3PROC) family of functions, there are some additional
 613      considerations.  Importantly, if a process calls any of the exec(2) suite
 614      of functions, much of the state information that is obtained,
 615      particularly that about mappings in the process will be invalid.  Callers
 616      must ensure that they call Preset_maps(3PROC) when they hold a process
 617      handle across an exec.  In addition, users of the library should
 618      familiarize themselves with the PROGRAMMING NOTES section of the proc(4)
 619      manual page, which discusses issues of privileges and security.
 620 
 621 DEBUGGING
 622      The library provides a means for obtaining additional debugging
 623      information.  The output itself is not part of the libproc library's
 624      stable interface.  Setting the environment variable LIBPROC_DEBUG to some
 625      value will print information to standard error.  For example,
 626      LIBPROC_DEUBG=please.
 627 
 628 LOCKING
 629      Most functions operate on a handle to a process in the form of a struct
 630      ps_prochandle *.  Unless otherwise indicated, the library does not
 631      provide any synchronization for different routines that are operating on
 632      the same libproc library handle.  It is up to the caller to ensure that
 633      only a single thread is using a handle at any given time.  Multiple
 634      threads may call libproc library routines at the same time as long as
 635      each thread is using a different handle.
 636 
 637      Each individual function notes its MT-Level section.  The MT-Level of a
 638      routine that matches the above description will refer to this manual
 639      page.  If it does not, then it refers to the standard attributes in
 640      attributes(5).
 641 
 642 INTERFACE STABILITY
 643      Uncommitted
 644 
 645      While the library is considered an uncommitted interface, and is still
 646      evolving, changes that break compatibility have been uncommon and this
 647      trend is expected to continue.  It is documented to allow consumers,
 648      whether part of illumos or outside of it, to understand the libarary and
 649      make use of it with the understanding that changes may occur which break
 650      both source and binary compatibility.
 651 
 652 SEE ALSO
 653      gcore(1), mdb(1), proc(1), ps(1), coreadm(1M), exec(2), fcntl(2),
 654      stat(2), Intro(3), dlopen(3C), elf(3ELF), ctf(4), proc(4), attributes(5),
 655      environ(5), privileges(5)
 656 
 657 
 658      Linkers and Libraries Guide.
 659 
 660      Lfree(3PROC), Lgrab(3PROC), Lgrab_error(3PROC), Pcreate(3PROC),
 661      Pcreate_agent(3PROC), Pcreate_callback(3PROC), Pcreate_error(3PROC),
 662      Pdestroy_agent(3PROC), Pfgrab_core(3PROC), Pfree(3PROC), Pgrab(3PROC),
 663      Pgrab_core(3PROC), Pgrab_error(3PROC), Pgrab_file(3PROC),
 664      Pgrab_ops(3PROC), Prelease(3PROC), Preopen(3PROC), Pxcreate(3PROC)
 665 
 666      Paddr_to_ctf(3PROC), Paddr_to_loadobj(3PROC), Paddr_to_map(3PROC),
 667      Paddr_to_text_map(3PROC), Pasfd(3PROC), Pclearfault(3PROC),
 668      Pclearsig(3PROC), Pcontent(3PROC), Pcred(3PROC), Pctlfd(3PROC),
 669      Pdelbkpt(3PROC), Pdelwapt(3PROC), Pdstop(3PROC), Pexecname(3PROC),
 670      Pfault(3PROC), Pfgcore(3PROC), Pgcore(3PROC), Pgetareg(3PROC),
 671      Pgetauxval(3PROC), Pgetauxvec(3PROC), Pgetenv(3PROC), Pisprocdir(3PROC),
 672      Pissyscall_prev(3PROC), Plmid(3PROC), Plmid_to_loadobj(3PROC),
 673      Plmid_to_map(3PROC), Plookup_by_addr(3PROC), Plookup_by_name(3PROC),
 674      Plwp_alt_stack(3PROC), Plwp_getfpregs(3PROC), Plwp_getpsinfo(3PROC),
 675      Plwp_getregs(3PROC), Plwp_getspymaster(3PROC), Plwp_main_stack(3PROC),
 676      Plwp_setfpregs(3PROC), Plwp_setregs(3PROC), Plwp_stack(3PROC),
 677      Pname_to_ctf(3PROC), Pname_to_loadobj(3PROC), Pname_to_map(3PROC),
 678      Pobjname(3PROC), Pobjname_resolved(3PROC), Pplatform(3PROC),
 679      Ppltdest(3PROC), Ppriv(3PROC), Ppsinfo(3PROC), Pputareg(3PROC),
 680      Prd_agent(3PROC), Pread(3PROC), Pread_string(3PROC), Preset_maps(3PROC),
 681      Psecflags(3PROC), Psetbkpt(3PROC), Psetcred(3PROC), Psetfault(3PROC),
 682      Psetflags(3PROC), Psetpriv(3PROC), Psetrun(3PROC), Psetsignal(3PROC),
 683      Psetsysentry(3PROC), Psetsysexit(3PROC), Psetwapt(3PROC),
 684      Psetzoneid(3PROC), Psignal(3PROC), Pstate(3PROC), Pstatus(3PROC),
 685      Pstop(3PROC), Pstopstatus(3PROC), Psync(3PROC), Psysentry(3PROC),
 686      Psysexit(3PROC), Puname(3PROC), Punsetflags(3PROC), Pupdate_maps(3PROC),
 687      Pupdate_syms(3PROC), Pwait(3PROC), Pwrite(3PROC), Pxecbkpt(3PROC),
 688      Pxecwapt(3PROC), Pxlookup_by_addr(3PROC),
 689      Pxlookup_by_addr_resolved(3PROC), Pxlookup_by_name(3PROC),
 690      Pzonename(3PROC), Pzonepath(3PROC), Pzoneroot(3PROC)
 691 
 692      Lalt_stack(3PROC), Lclearfault(3PROC), Lclearsig(3PROC), Lctlfd(3PROC),
 693      Ldstop(3PROC), Lgetareg(3PROC), Lmain_stack(3PROC), Lprochandle(3PROC),
 694      Lpsinfo(3PROC), Lputareg(3PROC), Lsetrun(3PROC), Lstack(3PROC),
 695      Lstate(3PROC), Lstatus(3PROC), Lstop(3PROC), Lsync(3PROC), Lwait(3PROC),
 696      Lxecbkpt(3PROC), Lxecwapt(3PROC)
 697 
 698      pr_access(3PROC), pr_close(3PROC), pr_creat(3PROC), pr_door_info(3PROC),
 699      pr_exit(3PROC), pr_fcntl(3PROC), pr_fstat(3PROC), pr_fstat64(3PROC),
 700      pr_fstatvfs(3PROC), pr_getitimer(3PROC), pr_getpeername(3PROC),
 701      pr_getpeerucred(3PROC), pr_getprojid(3PROC), pr_getrctl(3PROC),
 702      pr_getrlimit(3PROC), pr_getrlimit64(3PROC), pr_getsockname(3PROC),
 703      pr_getsockopt(3PROC), pr_gettaskid(3PROC), pr_getzoneid(3PROC),
 704      pr_ioctl(3PROC), pr_link(3PROC), pr_llseek(3PROC), pr_lseek(3PROC),
 705      pr_lstat(3PROC), pr_lstat64(3PROC), pr_memcntl(3PROC), pr_meminfo(3PROC),
 706      pr_mmap(3PROC), pr_munmap(3PROC), pr_open(3PROC),
 707      pr_processor_bind(3PROC), pr_rename(3PROC), pr_setitimer(3PROC),
 708      pr_setrctl(3PROC), pr_setrlimit(3PROC), pr_setrlimit64(3PROC),
 709      pr_settaskid(3PROC), pr_sigaction(3PROC), pr_stat(3PROC),
 710      pr_stat64(3PROC), pr_statvfs(3PROC), pr_unlink(3PROC), pr_waitid(3PROC),
 711 
 712      Penv_iter(3PROC), Plwp_iter(3PROC), Plwp_iter_all(3PROC),
 713      Pmapping_iter(3PROC), Pmapping_iter_resolved(3PROC), Pobject_iter(3PROC),
 714      Pobject_iter_resolved(3PROC), Pstack_iter(3PROC), Psymbol_iter(3PROC),
 715      Psymbol_iter_by_addr(3PROC), Psymbol_iter_by_lmid(3PROC),
 716      Psymbol_iter_by_name(3PROC), Pxsymbol_iter(3PROC), Pfdinfo_iter(3PROC)
 717 
 718      Perror_printf(3PROC), proc_arg_grab(3PROC), proc_arg_psinfo(3PROC),
 719      proc_arg_xgrab(3PROC), proc_arg_xpsinfo(3PROC), proc_content2str(3PROC),
 720      proc_finistdio(3PROC), proc_fltname(3PROC), proc_fltset2str(3PROC),
 721      proc_flushstdio(3PROC), proc_get_auxv(3PROC), proc_get_cred(3PROC),
 722      proc_get_priv(3PROC), proc_get_psinfo(3PROC), proc_get_status(3PROC),
 723      proc_initstdio(3PROC), proc_lwp_in_set(3PROC),
 724      proc_lwp_range_valid(3PROC), proc_signame(3PROC), proc_sigset2str(3PROC),
 725      proc_str2content(3PROC), proc_str2flt(3PROC), proc_str2fltset(3PROC),
 726      proc_str2sig(3PROC), proc_str2sigset(3PROC), proc_str2sys(3PROC),
 727      proc_str2sysset(3PROC), proc_sysname(3PROC), proc_sysset2str(3PROC),
 728      proc_unctrl_psinfo(3PROC), proc_walk(3PROC)
 729 
 730      Pldt(3PROC), proc_get_ldt(3PROC),
 731 
 732      Plwp_getgwindows(3PROC), Plwp_getxregs(3PROC), Plwp_setxregs(3PROC),
 733 
 734      Plwp_getasrs(3PROC), Plwp_setasrs(3PROC)
 735 
 736 illumos                         August 31, 2018                        illumos