xref: /illumos-gate/usr/src/man/man3lib/libproc.3lib (revision a7d7cafe)

.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2018 Joyent, Inc.
.\" Copyright (c) 2019 Carlos Neira <cneirabustos@gmail.com>
.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
.\" Copyright 2023 Oxide Computer Company
.\"
.Dd December 2, 2023
.Dt LIBPROC 3LIB
.Os
.Sh NAME
.Nm libproc
.Nd process control library
.Sh SYNOPSIS
.Lb libproc
.In libproc.h
.Sh DESCRIPTION
The
.Nm
library provides consumers a general series of interfaces to inspect
and control both live processes and core files.
It is intended for introspection tools such as debuggers by providing a
high-level interface to the /proc file system
.Pf ( Xr proc 5 ) .
.Pp
The
.Nm
library provides interfaces that focus on:
.Bl -bullet -offset indent
.It
Creating and attaching to live process, core files, and arbitrary ELF
objects.
.It
Interrogating the state of a process or core file.
.It
Manipulating the current state of a process or thread.
.It
Interrogating the state of threads of a process or core file.
.It
Running system calls in the context of another process.
.It
Various utilities for iterating process and core file file descriptors,
mappings, symbols, and more.
.It
Various utilities to support debugging tools.
.El
.Ss Live Processes
The
.Nm
library can be used to manipulate running processes and to create new
ones.
To manipulate an existing process first
.Em grab
it with the
.Fn Pgrab
function.
A process is generally stopped as a side effect of grabbing it.
Callers must exercise caution, as if they do not use the library correctly, or
they terminate unexpectedly, a process may remain stopped.
.Pp
Unprivileged users may only grab their own processes.
Users with the privilege
.Brq Sy PRIV_PROC_OWNER
may manipulate processes that they do not own; however, additional
restrictions as described in
.Xr privileges 7
apply.
.Pp
In addition, the
.Fn Pcreate
and
.Fn Pxcreate
functions may be used to create processes which are always controlled by
the library.
.Ss Core Files
The
.Nm
library has the ability to open and interpret core files produced by
processes on the system.
Process core dump generation is controlled by the
.Xr coreadm 8
command.
In addition, the library has the ability to understand and interpret core dumps
generated by Linux kernel and can provide a subset of its functionality on such
core files, provided the original binary is also present.
.Pp
Not all functions in the
.Nm
library are valid for core files.
In general, none of the commands which manipulate the current state of a process
or thread or that try to force system calls on a victim process will work.
Furthermore several of the information and iteration interfaces are limited
based on the data that is available in the core file.
For example, if the core file is of a process that omits the frame pointer, the
ability to iterate the stack will be limited.
.Pp
Use the
.Fn Pgrab_core
or
.Fn Pfgrab_core
function to open a core file.
Use the
.Fn Pgrab_file
function to open an ELF object file.
This is useful for obtaining information stored in ELF headers and
sections.
.Ss Debug Information
Many of the operations in the library rely on debug information being
present in a process and its associated libraries.
The library leverages symbol table information, CTF data
.Pq Xr ctf 5
sections, and frame unwinding information based on the use of an ABI
defined frame pointer, e\&.g\&.
.Sy %ebp
and
.Sy %rbp
on x86 systems.
.Pp
Some software providers strip programs of this information or build
their executables such that the information will not be present in a
core dump.
To deal with this fact, the library is able to consume information that is not
present in the core file or the running process.
It can both consume it from the underlying executable and it also supports
finding it from related ELF objects that are linked to it via the
.Sy .gnu_debuglink
and the
.Sy .note.gnu.build-id
ELF sections.
.Ss Iteration Interfaces
The
.Nm
library provides the ability to iterate over the following aspects of a
process or core file:
.Bl -bullet -offset indent
.It
Active threads
.It
Active and zombie threads
.It
All non-system processes
.It
All process mappings
.It
All objects in a process
.It
The environment
.It
The symbol table
.It
Stack frames
.It
File Descriptors
.El
.Ss System Call Injection
The
.Nm
library allows the caller to force system calls to be executed in the
context of the running process.
This can be used both as a tool for introspection, allowing one to get
information outside its current context as well as performing modifications to a
process.
.Pp
These functions run in the context of the calling process.
This is often an easier way of getting non-exported information about a
process from the system.
For example, the
.Xr pfiles 1
command uses this interface to get more detailed information about a
process's open file descriptors, which it would not have access to
otherwise.
.Sh INTERFACES
The shared object
.Sy libproc.so.1
provides the public interfaces defined below.
See
.Xr Intro 3
for additional information on shared object interfaces.
Functions are organized into categories that describe their purpose.
Individual functions are documented in their own manual pages.
.Ss Creation, Grabbing, and Releasing
The following routines are related to creating library handles,
grabbing cores, processes, and threads, and releasing those resources.
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy Lfree Ta Sy Lgrab
.It Sy Lgrab_error Ta Sy Pcreate
.It Sy Pcreate_agent Ta Sy Pcreate_callback
.It Sy Pcreate_error Ta Sy Pdestroy_agent
.It Sy Pfgrab_core Ta Sy Pfree
.It Sy Pgrab Ta Sy Pgrab_core
.It Sy Pgrab_error Ta Sy Pgrab_file
.It Sy Pgrab_ops Ta Sy Prelease
.It Sy Preopen Ta Sy Pxcreate
.El
.Ss Process interrogation and manipulation
The following routines obtain information about a process and allow
manipulation of the process itself.
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy Paddr_to_ctf Ta Sy Paddr_to_loadobj
.It Sy Paddr_to_map Ta Sy Paddr_to_text_map
.It Sy Pasfd Ta Sy Pclearfault
.It Sy Pclearsig Ta Sy Pcontent
.It Sy Pcred Ta Sy Pctlfd
.It Sy Pdelbkpt Ta Sy Pdelwapt
.It Sy Pdstop Ta Sy Pexecname
.It Sy Pfault Ta Sy Pfgcore
.It Sy Pgcore Ta Sy Pgetareg
.It Sy Pgetauxval Ta Sy Pgetauxvec
.It Sy Pgetenv Ta Sy Pisprocdir
.It Sy Pissyscall_prev Ta Sy Plmid
.It Sy Plmid_to_loadobj Ta Sy Plmid_to_map
.It Sy Plookup_by_addr Ta Sy Plookup_by_name
.It Sy Pname_to_ctf Ta Sy Pname_to_loadobj
.It Sy Pname_to_map Ta Sy Pobjname
.It Sy Pobjname_resolved Ta Sy Pplatform
.It Sy Ppltdest Ta Sy Ppriv
.It Sy Ppsinfo Ta Sy Pputareg
.It Sy Prd_agent Ta Sy Pread
.It Sy Pread_string Ta Sy Preset_maps
.It Sy Psetbkpt Ta Sy Psecflags
.It Sy Psetcred Ta Sy Psetfault
.It Sy Psetflags Ta Sy Psetpriv
.It Sy Psetrun Ta Sy Psetsignal
.It Sy Psetsysentry Ta Sy Psetsysexit
.It Sy Psetwapt Ta Sy Psetzoneid
.It Sy Psignal Ta Sy Pstate
.It Sy Pstatus Ta Sy Pstop
.It Sy Pstopstatus Ta Sy Psync
.It Sy Psysentry Ta Sy Psysexit
.It Sy Puname Ta Sy Pupanic
.It Sy Pupanic_free Ta Sy Punsetflags
.It Sy Pupdate_maps Ta Sy Pupdate_syms
.It Sy Pwait Ta Sy Pwrite
.It Sy Pxecbkpt Ta Sy Pxecwapt
.It Sy Pxlookup_by_addr Ta Sy Pxlookup_by_addr_resolved
.It Sy Pxlookup_by_name Ta Sy Pzonename
.It Sy Pzonepath Ta Sy Pzoneroot Ta
.El
.Ss Thread interrogation and manipulation
The following routines obtain information about a thread and allow
manipulation of the thread itself.
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy Lalt_stack Ta Sy Lclearfault
.It Sy Lclearsig Ta Sy Lctlfd
.It Sy Ldstop Ta Sy Lgetareg
.It Sy Lgetfpregs Ta Sy Lgetregs
.It Sy Lgetxregs Ta Sy Lmain_stack
.It Sy Lprochandle Ta Sy Lpsinfo
.It Sy Lputareg Ta Sy Lsetrun
.It Sy Lsetfpregs Ta Sy Lsetregs
.It Sy Lsetxregs Ta Sy Lstack
.It Sy Lstate Ta Sy Lstatus
.It Sy Lstop Ta Sy Lsync
.It Sy Lwait Ta Sy Lxecbkpt
.It Sy Lxecwapt Ta Sy ""
.El
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy Plwp_alt_stack Ta Sy Plwp_freexregs
.It Sy Plwp_getfpregs Ta Sy Plwp_getname
.It Sy Plwp_getpsinfo Ta Sy Plwp_getregs
.It Sy Plwp_getspymaster Ta Sy Plwp_main_stack
.It Sy Plwp_getxregs Ta Sy Plwp_setfpregs
.It Sy Plwp_setregs Ta Sy Plwp_setxregs
.It Sy Plwp_stack Ta Sy ""
.El
.Ss System Call Injection
The following routines are used to inject specific system calls and have
them run in the context of a process.
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy pr_access Ta Sy pr_close
.It Sy pr_creat Ta Sy pr_door_info
.It Sy pr_exit Ta Sy pr_fcntl
.It Sy pr_fstat Ta Sy pr_fstat64
.It Sy pr_fstatvfs Ta Sy pr_getitimer
.It Sy pr_getpeername Ta Sy pr_getpeerucred
.It Sy pr_getprojid Ta Sy pr_getrctl
.It Sy pr_getrlimit Ta Sy pr_getrlimit64
.It Sy pr_getsockname Ta Sy pr_getsockopt
.It Sy pr_gettaskid Ta Sy pr_getzoneid
.It Sy pr_ioctl Ta Sy pr_link
.It Sy pr_llseek Ta Sy pr_lseek
.It Sy pr_lstat Ta Sy pr_lstat64
.It Sy pr_memcntl Ta Sy pr_meminfo
.It Sy pr_mmap Ta Sy pr_munmap
.It Sy pr_open Ta Sy pr_processor_bind
.It Sy pr_rename Ta Sy pr_setitimer
.It Sy pr_setrctl Ta Sy pr_setrlimit
.It Sy pr_setrlimit64 Ta Sy pr_settaskid
.It Sy pr_sigaction Ta Sy pr_stat
.It Sy pr_stat64 Ta Sy pr_statvfs
.It Sy pr_unlink Ta Sy pr_waitid
.El
.Ss Iteration routines
These routines are used to iterate over the contents of a process.
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy Penv_iter Ta Sy Plwp_iter
.It Sy Plwp_iter_all Ta Sy Pmapping_iter
.It Sy Pmapping_iter_resolved Ta Sy Pobject_iter
.It Sy Pobject_iter_resolved Ta Sy Pstack_iter
.It Sy Psymbol_iter Ta Sy Psymbol_iter_by_addr
.It Sy Psymbol_iter_by_lmid Ta Sy Psymbol_iter_by_name
.It Sy Pxsymbol_iter Ta Sy Pfdinfo_iter
.El
.Ss Utility routines
The following routines are utilities that are useful to consumers of the
library.
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy Perror_printf Ta Sy proc_arg_grab
.It Sy proc_arg_psinfo Ta Sy proc_arg_xgrab
.It Sy proc_arg_xpsinfo Ta Sy proc_content2str
.It Sy proc_dmodelname Ta Sy proc_finistdio
.It Sy proc_fltname Ta Sy proc_fltset2str
.It Sy proc_flushstdio Ta Sy proc_get_auxv
.It Sy proc_fdinfo_misc Ta Sy proc_get_cred
.It Sy proc_get_fdinfo Ta Sy proc_get_lwpsinfo
.It Sy proc_get_lwpstatus Ta Sy proc_get_priv
.It Sy proc_get_psinfo Ta Sy proc_get_status
.It Sy proc_get_initstdio Ta Sy proc_lwp_in_set
.It Sy proc_lwp_range_valid Ta Sy proc_signame
.It Sy proc_sigset2str Ta Sy proc_str2content
.It Sy proc_str2flt Ta Sy proc_str2fltset
.It Sy proc_str2sig Ta Sy proc_str2sigset
.It Sy proc_str2sys Ta Sy proc_str2sysset
.It Sy proc_sysname Ta Sy proc_sysset2str
.It Sy proc_unctrl_psinfo Ta Sy ""
.El
.Ss x86 Specific Routines
The following routines are specific to the x86, 32-bit and 64-bit,
versions of the
.Nm
library.
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy Pldt Ta Sy proc_get_ldt
.El
.Ss SPARC specific Routines
The following functions are specific to the SPARC, 32-bit and 64-bit,
versions of the
.Nm
library.
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy Plwp_getgwindows Ta Sy ""
.El
.Pp
The following functions are specific to the 64-bit SPARC version of the
.Nm
library.
.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
.It Sy Plwp_getasrs Ta Sy Plwp_setasrs
.El
.Sh PROCESS STATES
Every process handle that exists in
.Nm
has a state.
In some cases, such as for core files, these states are static.
In other cases, such as handles that correspond to a running process or a
created process, these states are dynamic and change based on actions taken in
the library.
The state can be obtained with the
.Xr Pstate 3PROC
function.
.Pp
The various states are:
.Bl -tag -width Dv -offset indent
.It Dv PS_RUN
An actively running process.
This may be a process that was obtained by creating it with functions such as
.Xr Pcreate 3PROC
or by grabbing an existing process such as
.Xr Pgrab 3PROC .
.It Dv PS_STOP
An active process that is no longer executing.
A process may stop for many reasons such as an explicit stop request (through
.Xr pstop 1
for example) or if a tracing event is hit.
.Pp
The reason a process is stopped may be obtained through the thread's
.Vt lwpstatus_t
structure read directly from /proc or obtained through the
.Xr Lstatus 3PROC
function.
.It Dv PS_LOST
Control over the process has been lost.
This may happen when the process executes a new image requiring a different set
of privileges.
To resume control call
.Xr Preopen 3PROC .
For more information on losing control of a process, see
.Xr proc 5 .
.It Dv PS_UNDEAD
A zombie process.
It has terminated, but it has not been cleaned up yet by its parent.
For more on the conditions of becoming a zombie, see
.Xr exec 2 .
.It Dv PS_DEAD
Processes in this state are always core files.
See the earlier section
.Sx Core Files
for more information on working with core files.
.It Dv PS_IDLE
A process that has never been run.
This is always the case for handles that refer to files as the files cannot be
executed.
Those process handles are obtained through calling
.Xr Pgrab_file 3PROC .
.El
.Pp
Many functions relating to tracing processes, for example
.Xr Psignal 3PROC ,
.Xr Psetsignal 3PROC ,
.Xr Psetfault 3PROC ,
.Xr Psysentry 3PROC ,
and others, mention that they only act upon
.Em Active Processes .
This specifically refers to processes whose state are in
.Dv PS_RUN
and
.Dv PS_STOP .
Process handles in the other states have no notion of settable tracing
flags, though core files
.Pq type Dv PS_DEAD
may have a read-only snapshot of their tracing settings available.
.Sh TYPES
The
.Nm
library uses many types that come from the /proc file system
.Pq Xr proc 5
and the ELF format
.Pq Xr elf 3ELF .
However, it also defines the following types:
.Pp
.Vt struct ps_prochandle
.Pp
The
.Vt struct ps_prochandle
is an opaque handle to the library and the core element of control for a
process.
Consumers obtain pointers to a handle through the use of the
.Fn Pcreate ,
.Fn Pgrab ,
and related functions.
When a caller is done with a handle, then it should call one of the
.Fn Pfree
and
.Fn Prelease
functions to relinquish the handle, release associated resources, and
potentially set the process to run again.
.Pp
.Vt struct ps_lwphandle
.Pp
The
.Vt struct ps_lwphandle
is analogous to the
.Vt struct ps_prochandle ,
but it represents the control of an individual thread, rather than a
process.
Consumers obtain pointers to a handle through the
.Fn Lgrab
function and relinquish it with the
.Fn Lfree
function.
.Pp
.Vt core_content_t
.Pp
The
.Vt core_content_t
is a value which describes the various content types of core files.
These are used in functions such as
.Xr Pcontent 3PROC
and
.Xr Pgcore 3PROC
to describe and control the types of content that get included.
Various content types may be included together through a bitwise-inclusive-OR.
The default system core contents are controlled with the
.Xr coreadm 8
tool.
The following table lists the current set of core contents in the system, though
the set may increase over time.
The string after the macro is the human readable string that corresponds with
the constant and is used by
.Xr coreadm 8 ,
.Xr proc_content2str 3PROC ,
and
.Xr proc_str2content 3PROC .
.Bl -tag -offset indent -width indent
.It Dv CC_CONTENT_STACK ("stack")
The contents include the process stack.
Note, this only covers the main thread's stack.
The stack of other threads is covered by
.Dv CC_CONTENT_ANON .
.It Dv CC_CONTENT_HEAP ("heap")
The contents include the process heap.
.It Dv CC_CONTENT_SHFILE ("shfile")
The contents include shared mappings that are backed by files (e.g.
mapped through
.Xr mmap 2
with the
.Dv MAP_SHARED
flag).
.It Dv CC_CONTENT_SHANNON ("shannon")
The contents include shared mappings that are backed by anonymous memory
(e.g. mapped through
.Xr mmap 2
with the
.Dv MAP_SHARED
and
.Dv MAP_ANON
flags).
.It Dv CC_CONTENT_RODATA ("rodata")
The contents include private read-only file mappings, such as shared
library text.
.It Dv CC_CONTENT_ANON ("anon")
The contents include private anonymous mappings.
This includes the stacks of threads which are not the main thread.
.It Dv CC_CONTENT_SHM ("shm")
The contents include system V shared memory.
.It Dv CC_CONTENT_ISM ("ism")
The contents include ISM (intimate shared memory) mappings.
.It Dv CC_CONTENT_DISM ("dism")
The contents include DISM (dynamic shared memory) mappings.
.It Dv CC_CONTENT_CTF ("ctf")
The contents include
.Xr ctf 5
(Compact C Type Format) information.
Note, not all objects in the process may have CTF information available.
.It Dv CC_CONTENT_SYMTAB ("symtab")
The contents include the symbol table.
Note, not all objects in the process may have a symbol table available.
.It Dv CC_CONTENT_ALL ("all")
This value indicates that all of the above content values are present.
Note that additional values may be added in the future, in which case
the value of the symbol will be updated to include them.
Comparisons with
.Dv CC_CONTENT_ALL
should validate all the expected bits are set by an expression such as
.Li (c & CC_CONTENT_ALL) == CC_CONTENT_ALL .
.It Dv CC_CONTENT_NONE ("none")
This value indicates that there is no content present.
.It Dv CC_CONTENT_DEFAULT ("default")
The content includes the following set of default values:
.Dv CC_CONTENT_STACK ,
.Dv CC_CONTENT_HEAP ,
.Dv CC_CONTENT_ISM ,
.Dv CC_CONTENT_DISM ,
.Dv CC_CONTENT_SHM ,
.Dv CC_CONTENT_SHANON ,
.Dv CC_CONTENT_TEXT ,
.Dv CC_CONTENT_DATA ,
.Dv CC_CONTENT_RODATA ,
.Dv CC_CONTENT_ANON ,
.Dv CC_CONTENT_CTF ,
and
.Dv CC_CONTENT_SYMTAB .
Note that the default may change.
Comparisons with CC_CONTENT_DEFAULT should validate that all of the expected
bits are set with an expression such as
.Li (c\ &\ CC_CONTENT_DEFAULT)\ ==\ CC_CONTENT_DEFAULT .
.It Dv CC_CONTENT_INVALID
This indicates that the contents are invalid.
.El
.Pp
.Vt prfdinfo_t
.Pp
The
.Vt prfdinfo_t
structure is used with the
.Fn Pfdinfo_iter ,
.Fn proc_fdwalk ,
.Fn proc_fdinfowalk
and
.Fn proc_get_fdinfo
functions and describes information about a file descriptor.
The structure is defined as follows:
.Bd -literal
typedef struct prfdinfo {
    int		pr_fd;		/* file descriptor number */
    mode_t	pr_mode;	/* (see st_mode in stat(2)) */
    ino64_t	pr_ino;		/* inode number */
    off64_t	pr_size;	/* file size */
    off64_t	pr_offset;	/* current offset */
    uid_t	pr_uid;		/* owner's user id */
    gid_t	pr_gid;		/* owner's group id */
    major_t	pr_major;	/* major number of device */
    minor_t	pr_minor;	/* minor number of device */
    major_t	pr_rmajor;	/* major number (if special file) */
    minor_t	pr_rminor;	/* minor number (if special file) */
    int		pr_fileflags;	/* (see F_GETXFL in fcntl(2)) */
    int		pr_fdflags;	/* (see F_GETFD in fcntl(2)) */
    short	pr_locktype;	/* (see F_GETLK in fcntl(2)) */
    pid_t	pr_lockpid;	/* process holding file lock */
    int		pr_locksysid;	/* sysid of locking process */
    pid_t	pr_peerpid;	/* peer process (socket, door) */
    int		pr_filler[25];	/* reserved for future use */
    char	pr_peername[PRFNSZ];	/* peer process name */
#if    __STDC_VERSION__ >= 199901L
    uint8_t	pr_misc[];	/* self describing structures */
else
    uint8_t	pr_misc[1];	/* self describing structures */
#endif
} prfdinfo_t;
.Ed
.Pp
The structure has similar information to that found in the
.Sy stat
structure that's used as part of the stat family of system calls,
defined in
.Xr stat 2 .
The member
.Sy pr_fd
contains the number of the file descriptor of the file.
The members
.Fa pr_mode ,
.Fa pr_uid ,
.Fa pr_gid ,
.Fa pr_ino ,
and
.Fa pr_size
are the same as the members
.Fa st_mode ,
.Fa st_uid ,
.Fa st_gid ,
.Fa st_ino ,
and
.Fa st_size
in the
.Fa stat
structure.
.Pp
The
.Fa pr_major
and
.Fa pr_minor
members contain the major and minor numbers of the device containing the
directory for this file.
This is similar to the
.Fa st_dev
member of the
.Vt stat
structure, except that it is broken out into its major and minor components.
The
.Fa pr_rmajor
and
.Fa pr_rminor
members are similar in spirit to
.Fa pr_major
and
.Fa pr_minor ;
however, they are equivalent to the
.Fa st_rdev
member of the
.Vt stat
structure and thus have meaning for special character and block files.
.Pp
The
.Fa pr_offset
member contains the current seek offset of the file descriptor.
The
.Fa pr_fileflags
and
.Fa pr_fdflags
members contain the flags that would have been returned by a call to
.Xr fcntl 2
with the arguments
.Dv F_GETXFL
and
.Dv F_GETFD
respectively.
.Pp
The
.Fa pr_locktype ,
.Fa pr_lockpid ,
and
.Fa pr_locksysid
contain the information that would have been returned by a call to
.Xr fcntl 2
with an argument of
.Dv F_GETLK .
.Pp
The
.Fa pr_peerpid
and
.Fa pr_peername
members contain the process ID and name of any peer endpoint of a
connection-oriented socket or stream fd.
This information is the same as that which would be returned by a call to
.Xr getpeerucred 3C
.Pp
The
.Fa pr_misc
member contains miscellaneous additional data relating to the file descriptor.
The format of these data is described in
.Xr proc 5 .
.Pp
.Vt prsyminfo_t
.Pp
The
.Vt prsyminfo_t
structure is used with the various symbol look up functions
.Fn Pxlookup_by_name ,
.Fn Pxlookup_by_addr ,
and
.Fn Pxlookup_by_addr_resolved
which describes additional information about a symbol.
The structure is defined as follows:
.Bd -literal
typedef struct prsyminfo {
        const char      *prs_object;            /* object name */
        const char      *prs_name;              /* symbol name */
        Lmid_t          prs_lmid;               /* link map id */
        uint_t          prs_id;                 /* symbol id */
        uint_t          prs_table;              /* symbol table id */
} prsyminfo_t;
.Ed
.Pp
The member
.Fa prs_object
points to a string that contains the name of the object file, if known,
that the symbol comes from.
The member
.Fa prs_name
points to the name of the symbol, if known.
This may be unknown due to a stripped binary that contains no symbol table.
The member
.Fa prs_lmid
indicates the link map identifier that the symbol was found on.
For more information on link map identifiers refer to the
.%B Linker and Libraries Guide
and
.Xr dlopen 3C .
.Pp
The members
.Fa prs_id
and
.Fa prs_table
can be used to determine both the symbol table that the entry came from
and which entry in the table it corresponds to.
If the value of
.Fa prs_table
is
.Dv PR_SYMTAB
then it came from the ELF standard symbol table.
However, if it is instead
.Dv PR_DYNSYM ,
then that indicates that it comes from the process's dynamic section.
.Pp
.Vt proc_lwp_f
.Pp
The
.Vt proc_lwp_f
is a function pointer type that is used with the
.Fn Plwp_iter
function.
It is defined as
.Sy typedef
.Ft int
.Fo proc_lwp_f
.Fa "void *"
.Fa "const lwpstatus_t *"
.Fc .
The first argument is a pointer to an argument that the user specifies,
while the second has the thread's status information and is defined in
.Xr proc 5 .
For additional information on using this type, see
.Xr Plwp_iter 3PROC .
.Pp
.Vt proc_lwp_all_f
.Pp
The
.Vt proc_lwp_all_f
is a function pointer type that is used with the
.Fn Plwp_iter_all
function.
It is defined as
.Sy typedef
.Ft int
.Fo proc_lwp_all_f
.Fa "void *"
.Fa "const lwpstatus_t *"
.Fa "const lwpsinfo_t *"
.Fc .
The first argument is a pointer to an argument that the user specifies.
The second and third arguments contain the thread's status and
thread-specific
.Xr ps 1
information respectively.
Both structures are defined in
.Xr proc 5 .
For additional information on using this type, see
.Xr Plwp_iter_all 3PROC .
.Pp
.Vt proc_fdinfowalk_f
.Pp
The
.Vt proc_fdinfowalk_f
is a function pointer type that is used with the
.Fn proc_fdinfowalk
function to walk the miscellaneous data items contained within a
.Vt prfdinfo_t
structure.
It is defined as
.Sy typedef
.Ft int
.Fo proc_fdinfowalk_f
.Fa "uint_t"
.Fa "const void *"
.Fa "size_t"
.Fa "void *"
.Fc .
The first argument contains the type of the miscellaneous information being
presented, the second and third provide a pointer to the associated data and
the length of that data.
The final argument is a pointer to an argument that the user specifies.
For more information on using this, see
.Xr proc_fdinfowalk 3PROC .
.Pp
.Vt proc_fdwalk_f
.Pp
The
.Vt proc_fdwalk_f
is a function pointer type that is used with the
.Fn proc_fdwalk
function.
It is defined as
.Sy typedef
.Ft int
.Fo proc_fdwalk_f
.Fa "const prfdinfo_t *"
.Fa "void *"
.Fc .
The first argument contains the file descriptor information.
The
.Sy prfdinfo_t
structure is defined in
.Xr proc 5 .
The final argument is a pointer to an argument that the user specifies.
For more information on using this, see
.Xr proc_fdwalk 3PROC .
.Pp
.Vt proc_walk_f
.Pp
The
.Vt proc_walk_f
is a function pointer type that is used with the
.Fn proc_walk
function.
It is defined as
.Sy typedef
.Ft int
.Fo proc_walk_f
.Fa "psinfo_t *"
.Fa "lwpsinfo_t *"
.Fa "void *"
.Fc .
The first argument contains the process
.Xr ps 1
information and the second argument contains the representative thread's
.Xr ps 1
information.
Both structures are defined in
.Xr proc 5 .
The final argument is a pointer to an argument that the user specifies.
For more information on using this, see
.Xr proc_walk 3PROC .
.Pp
.Vt proc_map_f
.Pp
The
.Vt proc_map_f
is a function pointer type that is used with the
.Fn Pmapping_iter ,
.Fn Pmapping_iter_resolved ,
.Fn Pobject_iter ,
and
.Fn Pobject_iter_resolved
functions.
It is defined as
.Sy typedef
.Ft int
.Fo proc_map_f
.Fa "void *"
.Fa "const prmap_t *"
.Fa "const char *"
.Fc .
The first argument is a pointer to an argument that the user specifies.
The second argument is describes the mapping information and is defined
in
.Xr proc 5 .
The final argument contains the name of the mapping or object file in
question.
For additional information on using this type, see
.Xr Pmapping_iter 3PROC .
.Pp
.Vt proc_env_f
.Pp
The
.Vt proc_env_f
is a function pointer type that is used with the
.Fn Penv_iter
function.
It is defined as
.Sy typedef
.Ft int
.Fo proc_env_f
.Fa "void *"
.Fa "struct ps_prochandle *"
.Fa "uintptr_t"
.Fa "const char *"
.Fc .
The first argument is a pointer to an argument that the user specifies.
The second argument is a pointer to the
.Vt struct ps_prochandle
that the callback was passed to.
The third argument is the address of the environment variable in the process.
The fourth argument is the environment variable.
Values in the environment follow the convention of the form
.Em variable=value .
For more information on environment variables see
.Xr exec 2
and
.Xr environ 7 .
For additional information on using this type, see
.Xr Penv_iter 3PROC .
.Pp
.Vt proc_sym_f
.Pp
The
.Vt proc_sym_f
is a function pointer type that is used with the
.Fn Psmbol_iter ,
.Fn Psymbol_iter_by_addr ,
.Fn Psymbol_iter_by_name ,
and
.Fn Psymbol_iter_by_lmid
functions.
It is defined as
.Sy typedef
.Ft int
.Fo proc_sym_f
.Fa "void *"
.Fa "const GElf_Sym *"
.Fa "const char *"
.Fc .
The first argument is a pointer to an argument that the user supplies.
The second argument is a pointer to the ELF symbol information in a
32-bit and 64-bit neutral form.
See
.Xr elf 3ELF
and
.Xr gelf 3ELF
for more information on it.
The final argument points to a character string that has the name of the symbol.
For additional information on using this type, see
.Xr Psymbol_iter 3PROC ,
.Xr Psymbol_iter_by_addr 3PROC ,
.Xr Psymbol_iter_by_name 3PROC ,
and
.Xr Psymbol_iter_by_lmid 3PROC .
.Pp
.Vt proc_xsym_f
.Pp
The
.Vt proc_xsym_f
is a function pointer type that is used with the
.Fn Pxsymbol_iter
function.
It is defined as
.Sy typedef
.Ft int
.Fo proc_xsym_f
.Fa "void *"
.Fa "const GElf_Sym *"
.Fa "const char *"
.Fa "const prsyminfo_t *"
.Fc .
The first three arguments are identical to those of
.Vt proc_sym_f .
The final argument contains additional information about the symbol
itself.
The members of the
.Vt prsyminfo_t
are defined earlier in this section.
For additional information on using this type, see
.Xr Pxsymbol_iter 3PROC .
.Pp
.Vt proc_stack_f
.Pp
The
.Vt proc_stack_f
is a function pointer type that is used with the
.Fn Pstack_iter
function.
It is defined as
.Sy typedef
.Ft int
.Fo proc_stack_f
.Fa "void *"
.Fa "prgregset_t"
.Fa "uint_t"
.Fa "const long *"
.Fc .
The first argument is a pointer to an argument that the user specifies.
The second argument's contents are platform specific.
The registers that contain stack information, usually the stack pointer and
frame pointer, will be filled in to point to an entry.
The
.Vt prgregset_t
is defined in
.Xr proc 5 .
.Pp
The third argument contains the number of arguments to the current stack
frame and the fourth argument contains an array of addresses that
correspond to the arguments to that stack function.
The value of the third argument dictates the number of entries in the fourth
argument.
For additional information on using this type, see
.Xr Pstack_iter 3PROC .
.Pp
.Vt proc_fdinfo_f
.Pp
The
.Vt proc_fdinfo_f
is a function pointer type that is used with the
.Fn Pfdinfo_iter
function.
It is defined as
.Sy typedef
.Ft int
.Fo proc_fdinfo_f
.Fa "void *"
.Fa "prfdinfo_t *"
.Fc .
The first argument is a pointer to an argument that the user specifies.
The second argument contains information about an open file descriptor.
The members of the
.Vt prfdinfo_t
are defined earlier in this section.
For additional information on using this type, see
.Xr Pfdinfo_iter 3PROC .
.Sh PROGRAMMING NOTES
When working with live processes, whether from the
.Xr Pgrab 3PROC
or
.Xr Pcreate 3PROC
family of functions, there are some additional considerations.
Importantly, if a process calls any of the
.Xr exec 2
suite of functions, much of the state information that is obtained,
particularly that about mappings in the process will be invalid.
Callers must ensure that they call
.Xr Preset_maps 3PROC
when they hold a process handle across an exec.
In addition, users of the library should familiarize themselves with the
.Sy PROGRAMMING NOTES
section of the
.Xr proc 5
manual page, which discusses issues of privileges and security.
.Sh DEBUGGING
The library provides a means for obtaining additional debugging
information.
The output itself is not part of the
.Nm
library's stable interface.
Setting the environment variable
.Ev LIBPROC_DEBUG
to some value will print information to standard error.
For example,
.Ev LIBPROC_DEBUG Ns = Ns Em please .
.Sh LOCKING
Most functions operate on a handle to a process in the form of a
.Vt "struct ps_prochandle *" .
Unless otherwise indicated, the library does not provide any
synchronization for different routines that are operating on the
.Sy same
.Nm
library handle.
It is up to the caller to ensure that only a single thread is using a handle at
any given time.
Multiple threads may call
.Nm
library routines at the same time as long as each thread is using a
different handle.
.Pp
Each individual function notes its
.Sy MT-Level
section.
The MT-Level of a routine that matches the above description will refer to this
manual page.
If it does not, then it refers to the standard attributes in
.Xr attributes 7 .
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Pp
While the library is considered an uncommitted interface, and is still
evolving, changes that break compatibility have been uncommon and this
trend is expected to continue.
It is documented to allow consumers, whether part of illumos or outside of it,
to understand the library and make use of it with the understanding that
changes may occur which break both source and binary compatibility.
.Sh SEE ALSO
.Xr gcore 1 ,
.Xr mdb 1 ,
.Xr proc 1 ,
.Xr ps 1 ,
.Xr exec 2 ,
.Xr fcntl 2 ,
.Xr stat 2 ,
.Xr Intro 3 ,
.Xr dlopen 3C ,
.Xr elf 3ELF ,
.Xr ctf 5 ,
.Xr proc 5 ,
.Xr attributes 7 ,
.Xr environ 7 ,
.Xr privileges 7 ,
.Xr coreadm 8
.Pp
.Rs
.%T Linkers and Libraries Guide
.Re
.Pp
.Xr Lfree 3PROC ,
.Xr Lgrab 3PROC ,
.Xr Lgrab_error 3PROC ,
.Xr Pcreate 3PROC ,
.Xr Pcreate_agent 3PROC ,
.Xr Pcreate_callback 3PROC ,
.Xr Pcreate_error 3PROC ,
.Xr Pdestroy_agent 3PROC ,
.Xr Pfgrab_core 3PROC ,
.Xr Pfree 3PROC ,
.Xr Pgrab 3PROC ,
.Xr Pgrab_core 3PROC ,
.Xr Pgrab_error 3PROC ,
.Xr Pgrab_file 3PROC ,
.Xr Pgrab_ops 3PROC ,
.Xr Prelease 3PROC ,
.Xr Preopen 3PROC ,
.Xr Pxcreate 3PROC
.Pp
.Xr Paddr_to_ctf 3PROC ,
.Xr Paddr_to_loadobj 3PROC ,
.Xr Paddr_to_map 3PROC ,
.Xr Paddr_to_text_map 3PROC ,
.Xr Pasfd 3PROC ,
.Xr Pclearfault 3PROC ,
.Xr Pclearsig 3PROC ,
.Xr Pcontent 3PROC ,
.Xr Pcred 3PROC ,
.Xr Pctlfd 3PROC ,
.Xr Pdelbkpt 3PROC ,
.Xr Pdelwapt 3PROC ,
.Xr Pdstop 3PROC ,
.Xr Pexecname 3PROC ,
.Xr Pfault 3PROC ,
.Xr Pfgcore 3PROC ,
.Xr Pgcore 3PROC ,
.Xr Pgetareg 3PROC ,
.Xr Pgetauxval 3PROC ,
.Xr Pgetauxvec 3PROC ,
.Xr Pgetenv 3PROC ,
.Xr Pisprocdir 3PROC ,
.Xr Pissyscall_prev 3PROC ,
.Xr Plmid 3PROC ,
.Xr Plmid_to_loadobj 3PROC ,
.Xr Plmid_to_map 3PROC ,
.Xr Plookup_by_addr 3PROC ,
.Xr Plookup_by_name 3PROC ,
.Xr Plwp_alt_stack 3PROC ,
.Xr Plwp_getfpregs 3PROC ,
.Xr Plwp_getpsinfo 3PROC ,
.Xr Plwp_getregs 3PROC ,
.Xr Plwp_getspymaster 3PROC ,
.Xr Plwp_main_stack 3PROC ,
.Xr Plwp_setfpregs 3PROC ,
.Xr Plwp_setregs 3PROC ,
.Xr Plwp_stack 3PROC ,
.Xr Pname_to_ctf 3PROC ,
.Xr Pname_to_loadobj 3PROC ,
.Xr Pname_to_map 3PROC ,
.Xr Pobjname 3PROC ,
.Xr Pobjname_resolved 3PROC ,
.Xr Pplatform 3PROC ,
.Xr Ppltdest 3PROC ,
.Xr Ppriv 3PROC ,
.Xr Ppsinfo 3PROC ,
.Xr Pputareg 3PROC ,
.Xr Prd_agent 3PROC ,
.Xr Pread 3PROC ,
.Xr Pread_string 3PROC ,
.Xr Preset_maps 3PROC ,
.Xr Psecflags 3PROC ,
.Xr Psetbkpt 3PROC ,
.Xr Psetcred 3PROC ,
.Xr Psetfault 3PROC ,
.Xr Psetflags 3PROC ,
.Xr Psetpriv 3PROC ,
.Xr Psetrun 3PROC ,
.Xr Psetsignal 3PROC ,
.Xr Psetsysentry 3PROC ,
.Xr Psetsysexit 3PROC ,
.Xr Psetwapt 3PROC ,
.Xr Psetzoneid 3PROC ,
.Xr Psignal 3PROC ,
.Xr Pstate 3PROC ,
.Xr Pstatus 3PROC ,
.Xr Pstop 3PROC ,
.Xr Pstopstatus 3PROC ,
.Xr Psync 3PROC ,
.Xr Psysentry 3PROC ,
.Xr Psysexit 3PROC ,
.Xr Puname 3PROC ,
.Xr Pupanic 3PROC ,
.Xr Pupanic_free 3PROC ,
.Xr Punsetflags 3PROC ,
.Xr Pupdate_maps 3PROC ,
.Xr Pupdate_syms 3PROC ,
.Xr Pwait 3PROC ,
.Xr Pwrite 3PROC ,
.Xr Pxecbkpt 3PROC ,
.Xr Pxecwapt 3PROC ,
.Xr Pxlookup_by_addr 3PROC ,
.Xr Pxlookup_by_addr_resolved 3PROC ,
.Xr Pxlookup_by_name 3PROC ,
.Xr Pzonename 3PROC ,
.Xr Pzonepath 3PROC ,
.Xr Pzoneroot 3PROC
.Pp
.Xr Lalt_stack 3PROC ,
.Xr Lclearfault 3PROC ,
.Xr Lclearsig 3PROC ,
.Xr Lctlfd 3PROC ,
.Xr Ldstop 3PROC ,
.Xr Lgetareg 3PROC ,
.Xr Lmain_stack 3PROC ,
.Xr Lprochandle 3PROC ,
.Xr Lpsinfo 3PROC ,
.Xr Lputareg 3PROC ,
.Xr Lsetrun 3PROC ,
.Xr Lstack 3PROC ,
.Xr Lstate 3PROC ,
.Xr Lstatus 3PROC ,
.Xr Lstop 3PROC ,
.Xr Lsync 3PROC ,
.Xr Lwait 3PROC ,
.Xr Lxecbkpt 3PROC ,
.Xr Lxecwapt 3PROC
.Pp
.Xr pr_access 3PROC ,
.Xr pr_close 3PROC ,
.Xr pr_creat 3PROC ,
.Xr pr_door_info 3PROC ,
.Xr pr_exit 3PROC ,
.Xr pr_fcntl 3PROC ,
.Xr pr_fstat 3PROC ,
.Xr pr_fstat64 3PROC ,
.Xr pr_fstatvfs 3PROC ,
.Xr pr_getitimer 3PROC ,
.Xr pr_getpeername 3PROC ,
.Xr pr_getpeerucred 3PROC ,
.Xr pr_getprojid 3PROC ,
.Xr pr_getrctl 3PROC ,
.Xr pr_getrlimit 3PROC ,
.Xr pr_getrlimit64 3PROC ,
.Xr pr_getsockname 3PROC ,
.Xr pr_getsockopt 3PROC ,
.Xr pr_gettaskid 3PROC ,
.Xr pr_getzoneid 3PROC ,
.Xr pr_ioctl 3PROC ,
.Xr pr_link 3PROC ,
.Xr pr_llseek 3PROC ,
.Xr pr_lseek 3PROC ,
.Xr pr_lstat 3PROC ,
.Xr pr_lstat64 3PROC ,
.Xr pr_memcntl 3PROC ,
.Xr pr_meminfo 3PROC ,
.Xr pr_mmap 3PROC ,
.Xr pr_munmap 3PROC ,
.Xr pr_open 3PROC ,
.Xr pr_processor_bind 3PROC ,
.Xr pr_rename 3PROC ,
.Xr pr_setitimer 3PROC ,
.Xr pr_setrctl 3PROC ,
.Xr pr_setrlimit 3PROC ,
.Xr pr_setrlimit64 3PROC ,
.Xr pr_settaskid 3PROC ,
.Xr pr_sigaction 3PROC ,
.Xr pr_stat 3PROC ,
.Xr pr_stat64 3PROC ,
.Xr pr_statvfs 3PROC ,
.Xr pr_unlink 3PROC ,
.Xr pr_waitid 3PROC ,
.Pp
.Xr Penv_iter 3PROC ,
.Xr Plwp_iter 3PROC ,
.Xr Plwp_iter_all 3PROC ,
.Xr Pmapping_iter 3PROC ,
.Xr Pmapping_iter_resolved 3PROC ,
.Xr Pobject_iter 3PROC ,
.Xr Pobject_iter_resolved 3PROC ,
.Xr Pstack_iter 3PROC ,
.Xr Psymbol_iter 3PROC ,
.Xr Psymbol_iter_by_addr 3PROC ,
.Xr Psymbol_iter_by_lmid 3PROC ,
.Xr Psymbol_iter_by_name 3PROC ,
.Xr Pxsymbol_iter 3PROC ,
.Xr Pfdinfo_iter 3PROC
.Pp
.Xr Perror_printf 3PROC ,
.Xr proc_arg_grab 3PROC ,
.Xr proc_arg_psinfo 3PROC ,
.Xr proc_arg_xgrab 3PROC ,
.Xr proc_arg_xpsinfo 3PROC ,
.Xr proc_content2str 3PROC ,
.Xr proc_dmodelname 3PROC ,
.Xr proc_finistdio 3PROC ,
.Xr proc_fltname 3PROC ,
.Xr proc_fltset2str 3PROC ,
.Xr proc_flushstdio 3PROC ,
.Xr proc_get_auxv 3PROC ,
.Xr proc_get_cred 3PROC ,
.Xr proc_get_fdinfo 3PROC ,
.Xr proc_get_lwpsinfo 3PROC ,
.Xr proc_get_lwpstatus 3PROC ,
.Xr proc_get_priv 3PROC ,
.Xr proc_get_psinfo 3PROC ,
.Xr proc_get_status 3PROC ,
.Xr proc_initstdio 3PROC ,
.Xr proc_lwp_in_set 3PROC ,
.Xr proc_lwp_range_valid 3PROC ,
.Xr proc_signame 3PROC ,
.Xr proc_sigset2str 3PROC ,
.Xr proc_str2content 3PROC ,
.Xr proc_str2flt 3PROC ,
.Xr proc_str2fltset 3PROC ,
.Xr proc_str2sig 3PROC ,
.Xr proc_str2sigset 3PROC ,
.Xr proc_str2sys 3PROC ,
.Xr proc_str2sysset 3PROC ,
.Xr proc_sysname 3PROC ,
.Xr proc_sysset2str 3PROC ,
.Xr proc_unctrl_psinfo 3PROC ,
.Xr proc_fdinfowalk 3PROC ,
.Xr proc_fdwalk 3PROC ,
.Xr proc_walk 3PROC
.Pp
.Xr Pldt 3PROC ,
.Xr proc_get_ldt 3PROC ,
.Pp
.Xr Plwp_getgwindows 3PROC ,
.Xr Plwp_getxregs 3PROC ,
.Xr Plwp_setxregs 3PROC ,
.Pp
.Xr Plwp_getasrs 3PROC ,
.Xr Plwp_setasrs 3PROC