6955 libproc should be documented and shipped

6956 libproc cannot leave free() to callers
Reviewed by: Ryan Zezeski <ryan@zinascii.com>
Reviewed by: Cody Mello <cody.mello@joyent.com>
Reviewed by: Joshua M. Clulow <josh@sysmgr.org>
Approved by: Richard Lowe <richlowe@richlowe.net>

2 files changed, 1213 insertions, 0 deletions

diff --git a/usr/src/man/man3lib/Makefile b/usr/src/man/man3lib/Makefile
index 48abd74fd8..220ed2ae3e 100644
--- a/usr/src/man/man3lib/Makefile
+++ b/usr/src/man/man3lib/Makefile
@@ -76,6 +76,7 @@ MANFILES= 	libMPAPI.3lib		\
 	 	libpicltree.3lib	\
 	 	libpkcs11.3lib		\
 	 	libpool.3lib		\
+		libproc.3lib		\
 	 	libproject.3lib		\
 	 	libpthread.3lib		\
 	 	libresolv.3lib		\
diff --git a/usr/src/man/man3lib/libproc.3lib b/usr/src/man/man3lib/libproc.3lib
new file mode 100644
index 0000000000..6803c1512d
--- /dev/null
+++ b/usr/src/man/man3lib/libproc.3lib
@@ -0,0 +1,1212 @@
+.\"
+.\" 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 2015 Joyent, Inc.
+.\"
+.Dd May 08, 2016
+.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 4 ) .
+.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
+.Em 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
+.Sy PRIV_PROC_OWNER
+may manipulate processes that they do not own; however, additional
+restrictions as described in
+.Xr privileges 5
+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 1M
+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
+.Pf ( Xr CTF 4 )
+sections, and frame unwinding information based on the use of an ABI
+defined frame pointer, eg.
+.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 Plwp_alt_stack Ta Sy Plwp_getfpregs
+.It Sy Plwp_getpsinfo Ta Sy Plwp_getregs
+.It Sy Plwp_getspymaster Ta Sy Plwp_main_stack
+.It Sy Plwp_setfpregs Ta Sy Plwp_setregs
+.It Sy Plwp_stack Ta Sy Pname_to_ctf
+.It Sy Pname_to_loadobj Ta Sy Pname_to_map
+.It Sy Pobjname Ta Sy Pobjname_resolved
+.It Sy Pplatform Ta Sy Ppltdest
+.It Sy Ppriv Ta Sy Ppsinfo
+.It Sy Pputareg Ta Sy Prd_agent
+.It Sy Pread Ta Sy Pread_string
+.It Sy Preset_maps Ta Sy Psetbkpt
+.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 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
+.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 Lmain_stack Ta Sy Lprochandle
+.It Sy Lpsinfo Ta Sy Lputareg
+.It Sy Lsetrun 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 ""
+.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_finistdio Ta Sy proc_fltname
+.It Sy proc_fltset2str Ta Sy proc_flushstdio
+.It Sy proc_get_auxv Ta Sy proc_get_cred
+.It Sy proc_get_priv Ta Sy proc_get_psinfo
+.It Sy proc_get_status Ta Sy proc_initstdio
+.It Sy proc_lwp_in_set Ta Sy proc_lwp_range_valid
+.It Sy proc_signame Ta Sy proc_sigset2str
+.It Sy proc_str2content Ta Sy proc_str2flt
+.It Sy proc_str2fltset Ta Sy proc_str2sig
+.It Sy proc_str2sigset Ta Sy proc_str2sys
+.It Sy proc_str2sysset Ta Sy proc_sysname
+.It Sy proc_sysset2str Ta Sy proc_unctrl_psinfo
+.It Sy proc_walk Ta ""
+.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 Plwp_getxregs
+.It Sy Plwp_setxregs 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
+.Sy 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 4 .
+.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 Psetentry 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
+.Pf ( 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
+.Pf ( Xr proc 4 )
+and the ELF format
+.Pf ( Xr elf 3ELF ) .
+However, it also defines the following types:
+.Pp
+.Sy struct ps_prochandle
+.Pp
+The
+.Sy 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
+.Sy struct ps_lwphandle
+.Pp
+The
+.Sy struct ps_lwphandle
+is analogous to the
+.Sy 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
+.Sy core_content_t
+.Pp
+The
+.Sy 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 1M
+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 1M ,
+.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 4
+(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
+.Sy prfdinfo_t
+.Pp
+The
+.Sy prfdinfo_t
+structure is used with the
+.Fn Pfdinfo_iter
+function which describes information about a file descriptor. The
+structure is defined as follows:
+.Bd -literal
+typedef struct prfdinfo {
+	int		pr_fd;
+	mode_t		pr_mode;
+	uid_t		pr_uid;
+	gid_t		pr_gid;
+	major_t		pr_major;	/* think stat.st_dev */
+	minor_t		pr_minor;
+	major_t		pr_rmajor;	/* think stat.st_rdev */
+	minor_t		pr_rminor;
+	ino64_t		pr_ino;
+	off64_t		pr_offset;
+	off64_t		pr_size;
+	int		pr_fileflags;	/* fcntl(F_GETXFL), etc */
+	int		pr_fdflags;	/* fcntl(F_GETFD), etc. */
+	char		pr_path[MAXPATHLEN];
+} 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
+.Sy pr_mode ,
+.Sy pr_uid ,
+.Sy pr_gid ,
+.Sy pr_ino ,
+and
+.Sy pr_size
+are the same as the members
+.Sy st_mode ,
+.Sy st_uid ,
+.Sy st_gid ,
+.Sy st_ino ,
+and
+.Sy st_size
+in the
+.Sy stat
+structure.
+.Pp
+The
+.Sy pr_major
+and
+.Sy pr_minor
+members contain the major and minor numbers of the device containing the
+directory for this file. This is similar to the
+.Sy st_dev
+member of the
+.Sy stat
+structure, except that it is broken out into its major and minor components.
+The
+.Sy pr_rmajor
+and
+.Sy pr_rminor
+members are similar in spirit to
+.Sy pr_major
+and
+.Sy pr_minor ;
+however, they are equivalent to the
+.Sy st_rdev
+member of the
+.Sy stat
+structure and thus have meaning for special character and block files.
+.Pp
+The
+.Sy pr_offset
+member contains the current seek offset of the file descriptor. The
+.Sy pr_fileflags
+and
+.Sy 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
+.Sy prsyminfo_t
+.Pp
+The
+.Sy 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
+.Sy prs_object
+points to a string that contains the name of the object file, if known,
+that the symbol comes from. The member
+.Sy 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
+.Sy prs_lmid
+indicates the link map identifier that the symbol was found on. For more
+information on link map identifiers refer to the
+.Em Linker and Libraries Guide
+and
+.Xr dlopen 3C .
+.Pp
+The members
+.Sy prs_id
+and
+.Sy 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
+.Sy 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
+.Sy proc_lwp_f
+.Pp
+The
+.Sy 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 4 .
+For additional information on using this type, see
+.Xr Plwp_iter 3PROC .
+.Pp
+.Sy proc_lwp_all_f
+.Pp
+The
+.Sy 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 4 .
+For additional information on using this type, see
+.Xr Plwp_iter_all 3PROC .
+.Pp
+.Sy proc_walk_f
+.Pp
+The
+.Sy 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 4 .
+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
+.Sy proc_map_f
+.Pp
+The
+.Sy 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 4 .
+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
+.Sy proc_env_f
+.Pp
+The
+.Sy 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
+.Sy 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 5 .
+For additional information on using this type, see
+.Xr Penv_iter 3PROC .
+.Pp
+.Sy proc_sym_f
+.Pp
+The
+.Sy 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
+.Sy proc_xsym_f
+.Pp
+The
+.Sy 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
+.Sy proc_sym_f .
+The final argument contains additional information about the symbol
+itself. The members of the
+.Sy prsyminfo_t
+are defined earlier in this section. For additional information on using
+this type, see
+.Xr Pxsymbol_iter 3PROC .
+.Pp
+.Sy proc_stack_f
+.Pp
+The
+.Sy 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
+.Sy prgregset_t
+is defined in
+.Xr proc 4 .
+.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
+.Sy proc_fdinfo_f
+.Pp
+The
+.Sy 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
+.Sy 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
+or
+.Xr Pcreate
+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 4
+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_DEUBG 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 5 .
+.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 libarary 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 coreadm 1M ,
+.Xr exec 2 ,
+.Xr fcntl 2 ,
+.Xr stat 2 ,
+.Xr Intro 3 ,
+.Xr dlopen 3C ,
+.Xr elf 3ELF ,
+.Xr ctf 4 ,
+.Xr proc 4 ,
+.Xr attributes 5 ,
+.Xr environ 5 ,
+.Xr privileges 5
+.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 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 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_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_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_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