diff options
Diffstat (limited to 'usr/src/man/man3lib/libproc.3lib')
| -rw-r--r-- | usr/src/man/man3lib/libproc.3lib | 330 |
1 files changed, 186 insertions, 144 deletions
diff --git a/usr/src/man/man3lib/libproc.3lib b/usr/src/man/man3lib/libproc.3lib index c45504a7e5..ba71e5f2b9 100644 --- a/usr/src/man/man3lib/libproc.3lib +++ b/usr/src/man/man3lib/libproc.3lib @@ -24,9 +24,9 @@ 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 +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 @@ -54,17 +54,18 @@ Various utilities to support debugging tools. The .Nm library can be used to manipulate running processes and to create new -ones. To manipulate an existing process first +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. +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 +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 @@ -81,37 +82,38 @@ the library. 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 +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. +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. +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 +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 +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. @@ -122,11 +124,11 @@ 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 +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 @@ -160,13 +162,15 @@ File Descriptors 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. +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 +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 @@ -174,11 +178,12 @@ otherwise. .Sh INTERFACES The shared object .Sy libproc.so.1 -provides the public interfaces defined below. See +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. +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. @@ -342,25 +347,26 @@ library. .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 +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 +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 +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 @@ -370,25 +376,28 @@ 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. +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 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 +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 +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 +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 @@ -422,11 +431,12 @@ However, it also defines the following types: 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 +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 +and related functions. +When a caller is done with a handle, then it should call one of the .Fn Pfree and .Fn Prelease @@ -440,7 +450,8 @@ The 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 +process. +Consumers obtain pointers to a handle through the .Fn Lgrab function and relinquish it with the .Fn Lfree @@ -455,22 +466,24 @@ 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. +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 +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 +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. @@ -494,8 +507,8 @@ flags). 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. +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") @@ -505,16 +518,16 @@ 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. +(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. +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 +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 . @@ -535,9 +548,9 @@ The content includes the following set of default values: .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 +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. @@ -549,8 +562,8 @@ 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: +function which describes information about a file descriptor. +The structure is defined as follows: .Bd -literal typedef struct prfdinfo { int pr_fd; @@ -577,7 +590,8 @@ defined in .Xr stat 2 . The member .Sy pr_fd -contains the number of the file descriptor of the file. The members +contains the number of the file descriptor of the file. +The members .Sy pr_mode , .Sy pr_uid , .Sy pr_gid , @@ -600,7 +614,8 @@ The 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 +directory for this file. +This is similar to the .Sy st_dev member of the .Sy stat @@ -621,7 +636,8 @@ 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 +member contains the current seek offset of the file descriptor. +The .Sy pr_fileflags and .Sy pr_fdflags @@ -657,13 +673,15 @@ typedef struct prsyminfo { 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 +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 +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 +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 . @@ -673,11 +691,13 @@ The members 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 +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 +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 @@ -687,7 +707,8 @@ The .Sy proc_lwp_f is a function pointer type that is used with the .Fn Plwp_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_lwp_f @@ -706,7 +727,8 @@ 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 +function. +It is defined as .Sy typedef .Ft int .Fo proc_lwp_all_f @@ -718,7 +740,8 @@ 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 +information respectively. +Both structures are defined in .Xr proc 4 . For additional information on using this type, see .Xr Plwp_iter_all 3PROC . @@ -729,7 +752,8 @@ The .Sy proc_walk_f is a function pointer type that is used with the .Fn proc_walk -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_walk_f @@ -741,7 +765,8 @@ 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 +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 @@ -757,7 +782,8 @@ is a function pointer type that is used with the .Fn Pobject_iter , and .Fn Pobject_iter_resolved -functions. It is defined as +functions. +It is defined as .Sy typedef .Ft int .Fo proc_map_f @@ -770,7 +796,8 @@ 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 +question. +For additional information on using this type, see .Xr Pmapping_iter 3PROC . .Pp .Sy proc_env_f @@ -779,7 +806,8 @@ The .Sy proc_env_f is a function pointer type that is used with the .Fn Penv_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_env_f @@ -791,10 +819,10 @@ function. It is defined as 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 +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 @@ -813,7 +841,8 @@ is a function pointer type that is used with the .Fn Psymbol_iter_by_name , and .Fn Psymbol_iter_by_lmid -functions. It is defined as +functions. +It is defined as .Sy typedef .Ft int .Fo proc_sym_f @@ -823,13 +852,14 @@ functions. It is defined as .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 +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 +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 , @@ -842,7 +872,8 @@ The .Sy proc_xsym_f is a function pointer type that is used with the .Fn Pxsymbol_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_xsym_f @@ -854,10 +885,11 @@ function. It is defined as 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 +itself. +The members of the .Sy prsyminfo_t -are defined earlier in this section. For additional information on using -this type, see +are defined earlier in this section. +For additional information on using this type, see .Xr Pxsymbol_iter 3PROC . .Pp .Sy proc_stack_f @@ -866,7 +898,8 @@ The .Sy proc_stack_f is a function pointer type that is used with the .Fn Pstack_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_stack_f @@ -876,17 +909,19 @@ function. It is defined as .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 +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. +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 @@ -896,7 +931,8 @@ The .Sy proc_fdinfo_f is a function pointer type that is used with the .Fn Pfdinfo_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_fdinfo_f @@ -907,34 +943,37 @@ 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 +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 +.Xr Pgrab 3PROC or -.Xr Pcreate +.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 +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 +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 +information. +The output itself is not part of the .Nm -library's stable interface. Setting the environment variable +library's stable interface. +Setting the environment variable .Ev LIBPROC_DEBUG -to some value will print information to standard error. For example, +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 @@ -943,27 +982,30 @@ 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 +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 +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. +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 , |