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