DESCRIPTION
The
libproc 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 (
proc(4)).
The
libproc library provides interfaces that focus on:
-
Creating and attaching to live process, core files, and arbitrary ELF objects.
-
Interrogating the state of a process or core file.
-
Manipulating the current state of a process or thread.
-
Interrogating the state of threads of a process or core file.
-
Running system calls in the context of another process.
-
Various utilities for iterating process and core file file descriptors, mappings, symbols, and more.
-
Various utilities to support debugging tools.
Live Processes
The
libproc library can be used to manipulate running processes and to create new ones. To manipulate an existing process first
grab it with the
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.
Unprivileged users may only grab their own processes. Users with the privilege {
PRIV_PROC_OWNER} may manipulate processes that they do not own; however, additional restrictions as described in
privileges(5) apply.
In addition, the
Pcreate() and
Pxcreate() functions may be used to create processes which are always controlled by the library.
Core Files
The
libproc library has the ability to open and interpret core files produced by processes on the system. Process core dump generation is controlled by the
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.
Not all functions in the
libproc 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.
Use the
Pgrab_core() or
Pfgrab_core() function to open a core file. Use the
Pgrab_file() function to open an ELF object file. This is useful for obtaining information stored in ELF headers and sections.
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 (
ctf(4)) sections, and frame unwinding information based on the use of an ABI defined frame pointer, e.g.
%ebp and
%rbp on x86 systems.
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
.gnu_debuglink and the
.note.gnu.build-id ELF sections.
Iteration Interfaces
The
libproc library provides the ability to iterate over the following aspects of a process or core file:
-
Active threads
-
Active and zombie threads
-
All non-system processes
-
All process mappings
-
All objects in a process
-
The environment
-
The symbol table
-
Stack frames
-
File Descriptors
System Call Injection
The
libproc 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.
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
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.
TYPES
The
libproc library uses many types that come from the /proc file system (
proc(4)) and the ELF format (
elf(3ELF)). However, it also defines the following types:
struct ps_prochandle
The
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
Pcreate(),
Pgrab(), and related functions. When a caller is done with a handle, then it should call one of the
Pfree() and
Prelease() functions to relinquish the handle, release associated resources, and potentially set the process to run again.
struct ps_lwphandle
The
struct ps_lwphandle is analogous to the
struct ps_prochandle, but it represents the control of an individual thread, rather than a process. Consumers obtain pointers to a handle through the
Lgrab() function and relinquish it with the
Lfree() function.
core_content_t
The
core_content_t is a value which describes the various content types of core files. These are used in functions such as
Pcontent(3PROC) and
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
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
coreadm(1M),
proc_content2str(3PROC), and
proc_str2content(3PROC).
-
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 CC_CONTENT_ANON.
-
CC_CONTENT_HEAP ("heap")
-
The contents include the process heap.
-
CC_CONTENT_SHFILE ("shfile")
-
The contents include shared mappings that are backed by files (e.g. mapped through mmap(2) with the MAP_SHARED flag).
-
CC_CONTENT_SHANNON ("shannon")
-
The contents include shared mappings that are backed by anonymous memory (e.g. mapped through mmap(2) with the MAP_SHARED and MAP_ANON flags).
-
CC_CONTENT_RODATA ("rodata")
-
The contents include private read-only file mappings, such as shared library text.
-
CC_CONTENT_ANON ("anon")
-
The contents include private anonymous mappings. This includes the stacks of threads which are not the main thread.
-
CC_CONTENT_SHM ("shm")
-
The contents include system V shared memory.
-
CC_CONTENT_ISM ("ism")
-
The contents include ISM (intimate shared memory) mappings.
-
CC_CONTENT_DISM ("dism")
-
The contents include DISM (dynamic shared memory) mappings.
-
CC_CONTENT_CTF ("ctf")
-
The contents include ctf(4) (Compact C Type Format) information. Note, not all objects in the process may have CTF information available.
-
CC_CONTENT_SYMTAB ("symtab")
-
The contents include the symbol table. Note, not all objects in the process may have a symbol table available.
-
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 CC_CONTENT_ALL should validate all the expected bits are set by an expression such as
(c & CC_CONTENT_ALL) == CC_CONTENT_ALL.
-
CC_CONTENT_NONE ("none")
-
This value indicates that there is no content present.
-
CC_CONTENT_DEFAULT ("default")
-
The content includes the following set of default values: CC_CONTENT_STACK, CC_CONTENT_HEAP, CC_CONTENT_ISM, CC_CONTENT_DISM, CC_CONTENT_SHM, CC_CONTENT_SHANON, CC_CONTENT_TEXT, CC_CONTENT_DATA, CC_CONTENT_RODATA, CC_CONTENT_ANON, CC_CONTENT_CTF, and 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
(c & CC_CONTENT_DEFAULT) == CC_CONTENT_DEFAULT.
-
CC_CONTENT_INVALID
-
This indicates that the contents are invalid.
prfdinfo_t
The
prfdinfo_t structure is used with the
Pfdinfo_iter() function which describes information about a file descriptor. The structure is defined as follows:
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;
The structure has similar information to that found in the
stat structure that's used as part of the stat family of system calls, defined in
stat(2). The member
pr_fd contains the number of the file descriptor of the file. The members
pr_mode,
pr_uid,
pr_gid,
pr_ino, and
pr_size are the same as the members
st_mode,
st_uid,
st_gid,
st_ino, and
st_size in the
stat structure.
The
pr_major and
pr_minor members contain the major and minor numbers of the device containing the directory for this file. This is similar to the
st_dev member of the
stat structure, except that it is broken out into its major and minor components. The
pr_rmajor and
pr_rminor members are similar in spirit to
pr_major and
pr_minor; however, they are equivalent to the
st_rdev member of the
stat structure and thus have meaning for special character and block files.
The
pr_offset member contains the current seek offset of the file descriptor. The
pr_fileflags and
pr_fdflags members contain the flags that would have been returned by a call to
fcntl(2) with the arguments
F_GETXFL and
F_GETFD respectively.
prsyminfo_t
The
prsyminfo_t structure is used with the various symbol look up functions
Pxlookup_by_name(),
Pxlookup_by_addr(), and
Pxlookup_by_addr_resolved() which describes additional information about a symbol. The structure is defined as follows:
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;
The member
prs_object points to a string that contains the name of the object file, if known, that the symbol comes from. The member
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
prs_lmid indicates the link map identifier that the symbol was found on. For more information on link map identifiers refer to the
Linker and Libraries Guide and
dlopen(3C).
The members
prs_id and
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
prs_table is
PR_SYMTAB then it came from the ELF standard symbol table. However, if it is instead
PR_DYNSYM, then that indicates that it comes from the process's dynamic section.
proc_lwp_f
The
proc_lwp_f is a function pointer type that is used with the
Plwp_iter() function. It is defined as
typedef int proc_lwp_f(
void *,
const lwpstatus_t *);. 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
proc(4). For additional information on using this type, see
Plwp_iter(3PROC).
proc_lwp_all_f
The
proc_lwp_all_f is a function pointer type that is used with the
Plwp_iter_all() function. It is defined as
typedef int proc_lwp_all_f(
void *,
const lwpstatus_t *,
const lwpsinfo_t *);. 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
ps(1) information respectively. Both structures are defined in
proc(4). For additional information on using this type, see
Plwp_iter_all(3PROC).
proc_walk_f
The
proc_walk_f is a function pointer type that is used with the
proc_walk() function. It is defined as
typedef int proc_walk_f(
psinfo_t *,
lwpsinfo_t *,
void *);. The first argument contains the process
ps(1) information and the second argument contains the representative thread's
ps(1) information. Both structures are defined in
proc(4). The final argument is a pointer to an argument that the user specifies. For more information on using this, see
proc_walk(3PROC).
proc_map_f
The
proc_map_f is a function pointer type that is used with the
Pmapping_iter(),
Pmapping_iter_resolved(),
Pobject_iter(), and
Pobject_iter_resolved() functions. It is defined as
typedef int proc_map_f(
void *,
const prmap_t *,
const char *);. 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
proc(4). The final argument contains the name of the mapping or object file in question. For additional information on using this type, see
Pmapping_iter(3PROC).
proc_env_f
The
proc_env_f is a function pointer type that is used with the
Penv_iter() function. It is defined as
typedef int proc_env_f(
void *,
struct ps_prochandle *,
uintptr_t,
const char *);. The first argument is a pointer to an argument that the user specifies. The second argument is a pointer to the
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
variable=value. For more information on environment variables see
exec(2) and
environ(5). For additional information on using this type, see
Penv_iter(3PROC).
proc_sym_f
The
proc_sym_f is a function pointer type that is used with the
Psmbol_iter(),
Psymbol_iter_by_addr(),
Psymbol_iter_by_name(), and
Psymbol_iter_by_lmid() functions. It is defined as
typedef int proc_sym_f(
void *,
const GElf_Sym *,
const char *);. 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
elf(3ELF) and
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
Psymbol_iter(3PROC),
Psymbol_iter_by_addr(3PROC),
Psymbol_iter_by_name(3PROC), and
Psymbol_iter_by_lmid(3PROC).
proc_xsym_f
The
proc_xsym_f is a function pointer type that is used with the
Pxsymbol_iter() function. It is defined as
typedef int proc_xsym_f(
void *,
const GElf_Sym *,
const char *,
const prsyminfo_t *);. The first three arguments are identical to those of
proc_sym_f. The final argument contains additional information about the symbol itself. The members of the
prsyminfo_t are defined earlier in this section. For additional information on using this type, see
Pxsymbol_iter(3PROC).
proc_stack_f
The
proc_stack_f is a function pointer type that is used with the
Pstack_iter() function. It is defined as
typedef int proc_stack_f(
void *,
prgregset_t,
uint_t,
const long *);. 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
prgregset_t is defined in
proc(4).
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
Pstack_iter(3PROC).
proc_fdinfo_f
The
proc_fdinfo_f is a function pointer type that is used with the
Pfdinfo_iter() function. It is defined as
typedef int proc_fdinfo_f(
void *,
prfdinfo_t *);. 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
prfdinfo_t are defined earlier in this section. For additional information on using this type, see
Pfdinfo_iter(3PROC).