LIBPROC(3LIB) Interface Libraries LIBPROC(3LIB) NNAAMMEE lliibbpprroocc - process control library SSYYNNOOPPSSIISS Process Control Library (libproc, -lproc) ##iinncclluuddee <> DDEESSCCRRIIPPTTIIOONN The lliibbpprroocc 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 lliibbpprroocc library provides interfaces that focus on: ++oo Creating and attaching to live process, core files, and arbitrary ELF objects. ++oo Interrogating the state of a process or core file. ++oo Manipulating the current state of a process or thread. ++oo Interrogating the state of threads of a process or core file. ++oo Running system calls in the context of another process. ++oo Various utilities for iterating process and core file file descriptors, mappings, symbols, and more. ++oo Various utilities to support debugging tools. LLiivvee PPrroocceesssseess The lliibbpprroocc library can be used to manipulate running processes and to create new ones. To manipulate an existing process first _g_r_a_b it with the _P_g_r_a_b 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 PPRRIIVV__PPRROOCC__OOWWNNEERR may manipulate processes that they do not own; however, additional restrictions as described in privileges(5) apply. In addition, the PPccrreeaattee() and PPxxccrreeaattee() functions may be used to create processes which are always controlled by the library. CCoorree FFiilleess The lliibbpprroocc 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 lliibbpprroocc 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 PPggrraabb__ccoorree() or PPffggrraabb__ccoorree() function to open a core file. Use the PPggrraabb__ffiillee() function to open an ELF object file. This is useful for obtaining information stored in ELF headers and sections. DDeebbuugg IInnffoorrmmaattiioonn 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, eg. %%eebbpp and %%rrbbpp 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 ..ggnnuu__ddeebbuugglliinnkk and the ..nnoottee..ggnnuu..bbuuiilldd--iidd ELF sections. IItteerraattiioonn IInntteerrffaacceess The lliibbpprroocc library provides the ability to iterate over the following aspects of a process or core file: ++oo Active threads ++oo Active and zombie threads ++oo All non-system processes ++oo All process mappings ++oo All objects in a process ++oo The environment ++oo The symbol table ++oo Stack frames ++oo File Descriptors SSyysstteemm CCaallll IInnjjeeccttiioonn The lliibbpprroocc 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. IINNTTEERRFFAACCEESS The shared object lliibbpprroocc..ssoo..11 provides the public interfaces defined below. See 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. CCrreeaattiioonn,, GGrraabbbbiinngg,, aanndd RReelleeaassiinngg The following routines are related to creating library handles, grabbing cores, processes, and threads, and releasing those resources. LLffrreeee LLggrraabb LLggrraabb__eerrrroorr PPccrreeaattee PPccrreeaattee__aaggeenntt PPccrreeaattee__ccaallllbbaacckk PPccrreeaattee__eerrrroorr PPddeessttrrooyy__aaggeenntt PPffggrraabb__ccoorree PPffrreeee PPggrraabb PPggrraabb__ccoorree PPggrraabb__eerrrroorr PPggrraabb__ffiillee PPggrraabb__ooppss PPrreelleeaassee PPrreeooppeenn PPxxccrreeaattee PPrroocceessss iinntteerrrrooggaattiioonn aanndd mmaanniippuullaattiioonn The following routines obtain information about a process and allow manipulation of the process itself. PPaaddddrr__ttoo__ccttff PPaaddddrr__ttoo__llooaaddoobbjj PPaaddddrr__ttoo__mmaapp PPaaddddrr__ttoo__tteexxtt__mmaapp PPaassffdd PPcclleeaarrffaauulltt PPcclleeaarrssiigg PPccoonntteenntt PPccrreedd PPccttllffdd PPddeellbbkkpptt PPddeellwwaapptt PPddssttoopp PPeexxeeccnnaammee PPffaauulltt PPffggccoorree PPggccoorree PPggeettaarreegg PPggeettaauuxxvvaall PPggeettaauuxxvveecc PPggeetteennvv PPiisspprrooccddiirr PPiissssyyssccaallll__pprreevv PPllmmiidd PPllmmiidd__ttoo__llooaaddoobbjj PPllmmiidd__ttoo__mmaapp PPllooookkuupp__bbyy__aaddddrr PPllooookkuupp__bbyy__nnaammee PPllwwpp__aalltt__ssttaacckk PPllwwpp__ggeettffpprreeggss PPllwwpp__ggeettnnaammee PPllwwpp__ggeettppssiinnffoo PPllwwpp__ggeettrreeggss PPllwwpp__ggeettssppyymmaasstteerr PPllwwpp__mmaaiinn__ssttaacckk PPllwwpp__sseettffpprreeggss PPllwwpp__sseettrreeggss PPllwwpp__ssttaacckk PPnnaammee__ttoo__ccttff PPnnaammee__ttoo__llooaaddoobbjj PPnnaammee__ttoo__mmaapp PPoobbjjnnaammee PPoobbjjnnaammee__rreessoollvveedd PPppllaattffoorrmm PPppllttddeesstt PPpprriivv PPppssiinnffoo PPppuuttaarreegg PPrrdd__aaggeenntt PPrreeaadd PPrreeaadd__ssttrriinngg PPrreesseett__mmaappss PPsseettbbkkpptt PPsseeccffllaaggss PPsseettccrreedd PPsseettffaauulltt PPsseettffllaaggss PPsseettpprriivv PPsseettrruunn PPsseettssiiggnnaall PPsseettssyysseennttrryy PPsseettssyysseexxiitt PPsseettwwaapptt PPsseettzzoonneeiidd PPssiiggnnaall PPssttaattee PPssttaattuuss PPssttoopp PPssttooppssttaattuuss PPssyynncc PPssyysseennttrryy PPssyysseexxiitt PPuunnaammee PPuunnsseettffllaaggss PPuuppddaattee__mmaappss PPuuppddaattee__ssyymmss PPwwaaiitt PPwwrriittee PPxxeeccbbkkpptt PPxxeeccwwaapptt PPxxllooookkuupp__bbyy__aaddddrr PPxxllooookkuupp__bbyy__aaddddrr__rreessoollvveedd PPxxllooookkuupp__bbyy__nnaammee PPzzoonneennaammee PPzzoonneeppaatthh PPzzoonneerroooott TThhrreeaadd iinntteerrrrooggaattiioonn aanndd mmaanniippuullaattiioonn The following routines obtain information about a thread and allow manipulation of the thread itself. LLaalltt__ssttaacckk LLcclleeaarrffaauulltt LLcclleeaarrssiigg LLccttllffdd LLddssttoopp LLggeettaarreegg LLmmaaiinn__ssttaacckk LLpprroocchhaannddllee LLppssiinnffoo LLppuuttaarreegg LLsseettrruunn LLssttaacckk LLssttaattee LLssttaattuuss LLssttoopp LLssyynncc LLwwaaiitt LLxxeeccbbkkpptt LLxxeeccwwaapptt SSyysstteemm CCaallll IInnjjeeccttiioonn The following routines are used to inject specific system calls and have them run in the context of a process. pprr__aacccceessss pprr__cclloossee pprr__ccrreeaatt pprr__ddoooorr__iinnffoo pprr__eexxiitt pprr__ffccnnttll pprr__ffssttaatt pprr__ffssttaatt6644 pprr__ffssttaattvvffss pprr__ggeettiittiimmeerr pprr__ggeettppeeeerrnnaammee pprr__ggeettppeeeerruuccrreedd pprr__ggeettpprroojjiidd pprr__ggeettrrccttll pprr__ggeettrrlliimmiitt pprr__ggeettrrlliimmiitt6644 pprr__ggeettssoocckknnaammee pprr__ggeettssoocckkoopptt pprr__ggeettttaasskkiidd pprr__ggeettzzoonneeiidd pprr__iiooccttll pprr__lliinnkk pprr__llllsseeeekk pprr__llsseeeekk pprr__llssttaatt pprr__llssttaatt6644 pprr__mmeemmccnnttll pprr__mmeemmiinnffoo pprr__mmmmaapp pprr__mmuunnmmaapp pprr__ooppeenn pprr__pprroocceessssoorr__bbiinndd pprr__rreennaammee pprr__sseettiittiimmeerr pprr__sseettrrccttll pprr__sseettrrlliimmiitt pprr__sseettrrlliimmiitt6644 pprr__sseettttaasskkiidd pprr__ssiiggaaccttiioonn pprr__ssttaatt pprr__ssttaatt6644 pprr__ssttaattvvffss pprr__uunnlliinnkk pprr__wwaaiittiidd IItteerraattiioonn rroouuttiinneess These routines are used to iterate over the contents of a process. PPeennvv__iitteerr PPllwwpp__iitteerr PPllwwpp__iitteerr__aallll PPmmaappppiinngg__iitteerr PPmmaappppiinngg__iitteerr__rreessoollvveedd PPoobbjjeecctt__iitteerr PPoobbjjeecctt__iitteerr__rreessoollvveedd PPssttaacckk__iitteerr PPssyymmbbooll__iitteerr PPssyymmbbooll__iitteerr__bbyy__aaddddrr PPssyymmbbooll__iitteerr__bbyy__llmmiidd PPssyymmbbooll__iitteerr__bbyy__nnaammee PPxxssyymmbbooll__iitteerr PPffddiinnffoo__iitteerr UUttiilliittyy rroouuttiinneess The following routines are utilities that are useful to consumers of the library. PPeerrrroorr__pprriinnttff pprroocc__aarrgg__ggrraabb pprroocc__aarrgg__ppssiinnffoo pprroocc__aarrgg__xxggrraabb pprroocc__aarrgg__xxppssiinnffoo pprroocc__ccoonntteenntt22ssttrr pprroocc__ffiinniissttddiioo pprroocc__ffllttnnaammee pprroocc__ffllttsseett22ssttrr pprroocc__fflluusshhssttddiioo pprroocc__ggeett__aauuxxvv pprroocc__ggeett__ccrreedd pprroocc__ggeett__pprriivv pprroocc__ggeett__ppssiinnffoo pprroocc__ggeett__ssttaattuuss pprroocc__iinniittssttddiioo pprroocc__llwwpp__iinn__sseett pprroocc__llwwpp__rraannggee__vvaalliidd pprroocc__ssiiggnnaammee pprroocc__ssiiggsseett22ssttrr pprroocc__ssttrr22ccoonntteenntt pprroocc__ssttrr22fflltt pprroocc__ssttrr22ffllttsseett pprroocc__ssttrr22ssiigg pprroocc__ssttrr22ssiiggsseett pprroocc__ssttrr22ssyyss pprroocc__ssttrr22ssyysssseett pprroocc__ssyyssnnaammee pprroocc__ssyysssseett22ssttrr pprroocc__uunnccttrrll__ppssiinnffoo pprroocc__wwaallkk xx8866 SSppeecciiffiicc RRoouuttiinneess The following routines are specific to the x86, 32-bit and 64-bit, versions of the lliibbpprroocc library. PPllddtt pprroocc__ggeett__llddtt SSPPAARRCC ssppeecciiffiicc RRoouuttiinneess The following functions are specific to the SPARC, 32-bit and 64-bit, versions of the lliibbpprroocc library. PPllwwpp__ggeettggwwiinnddoowwss PPllwwpp__ggeettxxrreeggss PPllwwpp__sseettxxrreeggss The following functions are specific to the 64-bit SPARC version of the lliibbpprroocc library. PPllwwpp__ggeettaassrrss PPllwwpp__sseettaassrrss PPRROOCCEESSSS SSTTAATTEESS Every process handle that exists in lliibbpprroocc 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 Pstate(3PROC) function. The various states are: PS_RUN An actively running process. This may be a process that was obtained by creating it with functions such as Pcreate(3PROC) or by grabbing an existing process such as Pgrab(3PROC). PS_STOP An active process that is no longer executing. A process may stop for many reasons such as an explicit stop request (through pstop(1) for example) or if a tracing event is hit. The reason a process is stopped may be obtained through the thread's llwwppssttaattuuss__tt structure read directly from /proc or obtained through the Lstatus(3PROC) function. 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 Preopen(3PROC). For more information on losing control of a process, see proc(4). 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 exec(2). DV_PS_DEAD Processes in this state are always core files. See the earlier section _C_o_r_e _F_i_l_e_s for more information on working with core files. 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 Pgrab_file(3PROC). Many functions relating to tracing processes, for example Psignal(3PROC), Psetsignal(3PROC), Psetfault(3PROC), Psysentry(3PROC), and others, mention that they only act upon _A_c_t_i_v_e _P_r_o_c_e_s_s_e_s. This specifically refers to processes whose state are in PS_RUN and PS_STOP. Process handles in the other states have no notion of settable tracing flags, though core files (type PS_DEAD) may have a read-only snapshot of their tracing settings available. TTYYPPEESS The lliibbpprroocc 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: ssttrruucctt ppss__pprroocchhaannddllee The ssttrruucctt ppss__pprroocchhaannddllee 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 PPccrreeaattee(), PPggrraabb(), and related functions. When a caller is done with a handle, then it should call one of the PPffrreeee() and PPrreelleeaassee() functions to relinquish the handle, release associated resources, and potentially set the process to run again. ssttrruucctt ppss__llwwpphhaannddllee The ssttrruucctt ppss__llwwpphhaannddllee is analogous to the ssttrruucctt ppss__pprroocchhaannddllee, but it represents the control of an individual thread, rather than a process. Consumers obtain pointers to a handle through the LLggrraabb() function and relinquish it with the LLffrreeee() function. ccoorree__ccoonntteenntt__tt The ccoorree__ccoonntteenntt__tt 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. pprrffddiinnffoo__tt The pprrffddiinnffoo__tt structure is used with the PPffddiinnffoo__iitteerr() 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 ssttaatt structure that's used as part of the stat family of system calls, defined in stat(2). The member pprr__ffdd contains the number of the file descriptor of the file. The members pprr__mmooddee, pprr__uuiidd, pprr__ggiidd, pprr__iinnoo, and pprr__ssiizzee are the same as the members sstt__mmooddee, sstt__uuiidd, sstt__ggiidd, sstt__iinnoo, and sstt__ssiizzee in the ssttaatt structure. The pprr__mmaajjoorr and pprr__mmiinnoorr members contain the major and minor numbers of the device containing the directory for this file. This is similar to the sstt__ddeevv member of the ssttaatt structure, except that it is broken out into its major and minor components. The pprr__rrmmaajjoorr and pprr__rrmmiinnoorr members are similar in spirit to pprr__mmaajjoorr and pprr__mmiinnoorr; however, they are equivalent to the sstt__rrddeevv member of the ssttaatt structure and thus have meaning for special character and block files. The pprr__ooffffsseett member contains the current seek offset of the file descriptor. The pprr__ffiilleeffllaaggss and pprr__ffddffllaaggss members contain the flags that would have been returned by a call to fcntl(2) with the arguments F_GETXFL and F_GETFD respectively. pprrssyymmiinnffoo__tt The pprrssyymmiinnffoo__tt structure is used with the various symbol look up functions PPxxllooookkuupp__bbyy__nnaammee(), PPxxllooookkuupp__bbyy__aaddddrr(), and PPxxllooookkuupp__bbyy__aaddddrr__rreessoollvveedd() 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 pprrss__oobbjjeecctt points to a string that contains the name of the object file, if known, that the symbol comes from. The member pprrss__nnaammee 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 pprrss__llmmiidd indicates the link map identifier that the symbol was found on. For more information on link map identifiers refer to the _L_i_n_k_e_r _a_n_d _L_i_b_r_a_r_i_e_s _G_u_i_d_e and dlopen(3C). The members pprrss__iidd and pprrss__ttaabbllee 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 pprrss__ttaabbllee 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. pprroocc__llwwpp__ff The pprroocc__llwwpp__ff is a function pointer type that is used with the PPllwwpp__iitteerr() function. It is defined as ttyyppeeddeeff _i_n_t pprroocc__llwwpp__ff(_v_o_i_d _*, _c_o_n_s_t _l_w_p_s_t_a_t_u_s___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). pprroocc__llwwpp__aallll__ff The pprroocc__llwwpp__aallll__ff is a function pointer type that is used with the PPllwwpp__iitteerr__aallll() function. It is defined as ttyyppeeddeeff _i_n_t pprroocc__llwwpp__aallll__ff(_v_o_i_d _*, _c_o_n_s_t _l_w_p_s_t_a_t_u_s___t _*, _c_o_n_s_t _l_w_p_s_i_n_f_o___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). pprroocc__wwaallkk__ff The pprroocc__wwaallkk__ff is a function pointer type that is used with the pprroocc__wwaallkk() function. It is defined as ttyyppeeddeeff _i_n_t pprroocc__wwaallkk__ff(_p_s_i_n_f_o___t _*, _l_w_p_s_i_n_f_o___t _*, _v_o_i_d _*). 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). pprroocc__mmaapp__ff The pprroocc__mmaapp__ff is a function pointer type that is used with the PPmmaappppiinngg__iitteerr(), PPmmaappppiinngg__iitteerr__rreessoollvveedd(), PPoobbjjeecctt__iitteerr(), and PPoobbjjeecctt__iitteerr__rreessoollvveedd() functions. It is defined as ttyyppeeddeeff _i_n_t pprroocc__mmaapp__ff(_v_o_i_d _*, _c_o_n_s_t _p_r_m_a_p___t _*, _c_o_n_s_t _c_h_a_r _*). 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). pprroocc__eennvv__ff The pprroocc__eennvv__ff is a function pointer type that is used with the PPeennvv__iitteerr() function. It is defined as ttyyppeeddeeff _i_n_t pprroocc__eennvv__ff(_v_o_i_d _*, _s_t_r_u_c_t _p_s___p_r_o_c_h_a_n_d_l_e _*, _u_i_n_t_p_t_r___t, _c_o_n_s_t _c_h_a_r _*). The first argument is a pointer to an argument that the user specifies. The second argument is a pointer to the ssttrruucctt ppss__pprroocchhaannddllee 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 _v_a_r_i_a_b_l_e_=_v_a_l_u_e. For more information on environment variables see exec(2) and environ(5). For additional information on using this type, see Penv_iter(3PROC). pprroocc__ssyymm__ff The pprroocc__ssyymm__ff is a function pointer type that is used with the PPssmmbbooll__iitteerr(), PPssyymmbbooll__iitteerr__bbyy__aaddddrr(), PPssyymmbbooll__iitteerr__bbyy__nnaammee(), and PPssyymmbbooll__iitteerr__bbyy__llmmiidd() functions. It is defined as ttyyppeeddeeff _i_n_t pprroocc__ssyymm__ff(_v_o_i_d _*, _c_o_n_s_t _G_E_l_f___S_y_m _*, _c_o_n_s_t _c_h_a_r _*). 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). pprroocc__xxssyymm__ff The pprroocc__xxssyymm__ff is a function pointer type that is used with the PPxxssyymmbbooll__iitteerr() function. It is defined as ttyyppeeddeeff _i_n_t pprroocc__xxssyymm__ff(_v_o_i_d _*, _c_o_n_s_t _G_E_l_f___S_y_m _*, _c_o_n_s_t _c_h_a_r _*, _c_o_n_s_t _p_r_s_y_m_i_n_f_o___t _*). The first three arguments are identical to those of pprroocc__ssyymm__ff. The final argument contains additional information about the symbol itself. The members of the pprrssyymmiinnffoo__tt are defined earlier in this section. For additional information on using this type, see Pxsymbol_iter(3PROC). pprroocc__ssttaacckk__ff The pprroocc__ssttaacckk__ff is a function pointer type that is used with the PPssttaacckk__iitteerr() function. It is defined as ttyyppeeddeeff _i_n_t pprroocc__ssttaacckk__ff(_v_o_i_d _*, _p_r_g_r_e_g_s_e_t___t, _u_i_n_t___t, _c_o_n_s_t _l_o_n_g _*). 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 pprrggrreeggsseett__tt 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). pprroocc__ffddiinnffoo__ff The pprroocc__ffddiinnffoo__ff is a function pointer type that is used with the PPffddiinnffoo__iitteerr() function. It is defined as ttyyppeeddeeff _i_n_t pprroocc__ffddiinnffoo__ff(_v_o_i_d _*, _p_r_f_d_i_n_f_o___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 pprrffddiinnffoo__tt are defined earlier in this section. For additional information on using this type, see Pfdinfo_iter(3PROC). PPRROOGGRRAAMMMMIINNGG NNOOTTEESS When working with live processes, whether from the Pgrab(3PROC) or Pcreate(3PROC) family of functions, there are some additional considerations. Importantly, if a process calls any of the 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 Preset_maps(3PROC) when they hold a process handle across an exec. In addition, users of the library should familiarize themselves with the PPRROOGGRRAAMMMMIINNGG NNOOTTEESS section of the proc(4) manual page, which discusses issues of privileges and security. DDEEBBUUGGGGIINNGG The library provides a means for obtaining additional debugging information. The output itself is not part of the lliibbpprroocc library's stable interface. Setting the environment variable LIBPROC_DEBUG to some value will print information to standard error. For example, LIBPROC_DEUBG=_p_l_e_a_s_e. LLOOCCKKIINNGG Most functions operate on a handle to a process in the form of a _s_t_r_u_c_t _p_s___p_r_o_c_h_a_n_d_l_e _*. Unless otherwise indicated, the library does not provide any synchronization for different routines that are operating on the ssaammee lliibbpprroocc 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 lliibbpprroocc library routines at the same time as long as each thread is using a different handle. Each individual function notes its MMTT--LLeevveell 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 attributes(5). IINNTTEERRFFAACCEE SSTTAABBIILLIITTYY UUnnccoommmmiitttteedd 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. SSEEEE AALLSSOO gcore(1), mdb(1), proc(1), ps(1), coreadm(1M), exec(2), fcntl(2), stat(2), Intro(3), dlopen(3C), elf(3ELF), ctf(4), proc(4), attributes(5), environ(5), privileges(5) _L_i_n_k_e_r_s _a_n_d _L_i_b_r_a_r_i_e_s _G_u_i_d_e. Lfree(3PROC), Lgrab(3PROC), Lgrab_error(3PROC), Pcreate(3PROC), Pcreate_agent(3PROC), Pcreate_callback(3PROC), Pcreate_error(3PROC), Pdestroy_agent(3PROC), Pfgrab_core(3PROC), Pfree(3PROC), Pgrab(3PROC), Pgrab_core(3PROC), Pgrab_error(3PROC), Pgrab_file(3PROC), Pgrab_ops(3PROC), Prelease(3PROC), Preopen(3PROC), Pxcreate(3PROC) Paddr_to_ctf(3PROC), Paddr_to_loadobj(3PROC), Paddr_to_map(3PROC), Paddr_to_text_map(3PROC), Pasfd(3PROC), Pclearfault(3PROC), Pclearsig(3PROC), Pcontent(3PROC), Pcred(3PROC), Pctlfd(3PROC), Pdelbkpt(3PROC), Pdelwapt(3PROC), Pdstop(3PROC), Pexecname(3PROC), Pfault(3PROC), Pfgcore(3PROC), Pgcore(3PROC), Pgetareg(3PROC), Pgetauxval(3PROC), Pgetauxvec(3PROC), Pgetenv(3PROC), Pisprocdir(3PROC), Pissyscall_prev(3PROC), Plmid(3PROC), Plmid_to_loadobj(3PROC), Plmid_to_map(3PROC), Plookup_by_addr(3PROC), Plookup_by_name(3PROC), Plwp_alt_stack(3PROC), Plwp_getfpregs(3PROC), Plwp_getpsinfo(3PROC), Plwp_getregs(3PROC), Plwp_getspymaster(3PROC), Plwp_main_stack(3PROC), Plwp_setfpregs(3PROC), Plwp_setregs(3PROC), Plwp_stack(3PROC), Pname_to_ctf(3PROC), Pname_to_loadobj(3PROC), Pname_to_map(3PROC), Pobjname(3PROC), Pobjname_resolved(3PROC), Pplatform(3PROC), Ppltdest(3PROC), Ppriv(3PROC), Ppsinfo(3PROC), Pputareg(3PROC), Prd_agent(3PROC), Pread(3PROC), Pread_string(3PROC), Preset_maps(3PROC), Psecflags(3PROC), Psetbkpt(3PROC), Psetcred(3PROC), Psetfault(3PROC), Psetflags(3PROC), Psetpriv(3PROC), Psetrun(3PROC), Psetsignal(3PROC), Psetsysentry(3PROC), Psetsysexit(3PROC), Psetwapt(3PROC), Psetzoneid(3PROC), Psignal(3PROC), Pstate(3PROC), Pstatus(3PROC), Pstop(3PROC), Pstopstatus(3PROC), Psync(3PROC), Psysentry(3PROC), Psysexit(3PROC), Puname(3PROC), Punsetflags(3PROC), Pupdate_maps(3PROC), Pupdate_syms(3PROC), Pwait(3PROC), Pwrite(3PROC), Pxecbkpt(3PROC), Pxecwapt(3PROC), Pxlookup_by_addr(3PROC), Pxlookup_by_addr_resolved(3PROC), Pxlookup_by_name(3PROC), Pzonename(3PROC), Pzonepath(3PROC), Pzoneroot(3PROC) Lalt_stack(3PROC), Lclearfault(3PROC), Lclearsig(3PROC), Lctlfd(3PROC), Ldstop(3PROC), Lgetareg(3PROC), Lmain_stack(3PROC), Lprochandle(3PROC), Lpsinfo(3PROC), Lputareg(3PROC), Lsetrun(3PROC), Lstack(3PROC), Lstate(3PROC), Lstatus(3PROC), Lstop(3PROC), Lsync(3PROC), Lwait(3PROC), Lxecbkpt(3PROC), Lxecwapt(3PROC) pr_access(3PROC), pr_close(3PROC), pr_creat(3PROC), pr_door_info(3PROC), pr_exit(3PROC), pr_fcntl(3PROC), pr_fstat(3PROC), pr_fstat64(3PROC), pr_fstatvfs(3PROC), pr_getitimer(3PROC), pr_getpeername(3PROC), pr_getpeerucred(3PROC), pr_getprojid(3PROC), pr_getrctl(3PROC), pr_getrlimit(3PROC), pr_getrlimit64(3PROC), pr_getsockname(3PROC), pr_getsockopt(3PROC), pr_gettaskid(3PROC), pr_getzoneid(3PROC), pr_ioctl(3PROC), pr_link(3PROC), pr_llseek(3PROC), pr_lseek(3PROC), pr_lstat(3PROC), pr_lstat64(3PROC), pr_memcntl(3PROC), pr_meminfo(3PROC), pr_mmap(3PROC), pr_munmap(3PROC), pr_open(3PROC), pr_processor_bind(3PROC), pr_rename(3PROC), pr_setitimer(3PROC), pr_setrctl(3PROC), pr_setrlimit(3PROC), pr_setrlimit64(3PROC), pr_settaskid(3PROC), pr_sigaction(3PROC), pr_stat(3PROC), pr_stat64(3PROC), pr_statvfs(3PROC), pr_unlink(3PROC), pr_waitid(3PROC), Penv_iter(3PROC), Plwp_iter(3PROC), Plwp_iter_all(3PROC), Pmapping_iter(3PROC), Pmapping_iter_resolved(3PROC), Pobject_iter(3PROC), Pobject_iter_resolved(3PROC), Pstack_iter(3PROC), Psymbol_iter(3PROC), Psymbol_iter_by_addr(3PROC), Psymbol_iter_by_lmid(3PROC), Psymbol_iter_by_name(3PROC), Pxsymbol_iter(3PROC), Pfdinfo_iter(3PROC) Perror_printf(3PROC), proc_arg_grab(3PROC), proc_arg_psinfo(3PROC), proc_arg_xgrab(3PROC), proc_arg_xpsinfo(3PROC), proc_content2str(3PROC), proc_finistdio(3PROC), proc_fltname(3PROC), proc_fltset2str(3PROC), proc_flushstdio(3PROC), proc_get_auxv(3PROC), proc_get_cred(3PROC), proc_get_priv(3PROC), proc_get_psinfo(3PROC), proc_get_status(3PROC), proc_initstdio(3PROC), proc_lwp_in_set(3PROC), proc_lwp_range_valid(3PROC), proc_signame(3PROC), proc_sigset2str(3PROC), proc_str2content(3PROC), proc_str2flt(3PROC), proc_str2fltset(3PROC), proc_str2sig(3PROC), proc_str2sigset(3PROC), proc_str2sys(3PROC), proc_str2sysset(3PROC), proc_sysname(3PROC), proc_sysset2str(3PROC), proc_unctrl_psinfo(3PROC), proc_walk(3PROC) Pldt(3PROC), proc_get_ldt(3PROC), Plwp_getgwindows(3PROC), Plwp_getxregs(3PROC), Plwp_setxregs(3PROC), Plwp_getasrs(3PROC), Plwp_setasrs(3PROC) illumos August 31, 2018 illumos