1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2018 Joyent, Inc. 13.\" 14.Dd August 31, 2018 15.Dt LIBPROC 3LIB 16.Os 17.Sh NAME 18.Nm libproc 19.Nd process control library 20.Sh SYNOPSIS 21.Lb libproc 22.In libproc.h 23.Sh DESCRIPTION 24The 25.Nm 26library provides consumers a general series of interfaces to inspect 27and control both live processes and core files. 28It is intended for introspection tools such as debuggers by providing a 29high-level interface to the /proc file system 30.Pf ( Xr proc 4 ) . 31.Pp 32The 33.Nm 34library provides interfaces that focus on: 35.Bl -bullet -offset indent 36.It 37Creating and attaching to live process, core files, and arbitrary ELF 38objects. 39.It 40Interrogating the state of a process or core file. 41.It 42Manipulating the current state of a process or thread. 43.It 44Interrogating the state of threads of a process or core file. 45.It 46Running system calls in the context of another process. 47.It 48Various utilities for iterating process and core file file descriptors, 49mappings, symbols, and more. 50.It 51Various utilities to support debugging tools. 52.El 53.Ss Live Processes 54The 55.Nm 56library can be used to manipulate running processes and to create new 57ones. 58To manipulate an existing process first 59.Em grab 60it with the 61.Em Pgrab 62function. 63A process is generally stopped as a side effect of grabbing it. 64Callers must exercise caution, as if they do not use the library correctly, or 65they terminate unexpectedly, a process may remain stopped. 66.Pp 67Unprivileged users may only grab their own processes. 68Users with the privilege 69.Sy PRIV_PROC_OWNER 70may manipulate processes that they do not own; however, additional 71restrictions as described in 72.Xr privileges 5 73apply. 74.Pp 75In addition, the 76.Fn Pcreate 77and 78.Fn Pxcreate 79functions may be used to create processes which are always controlled by 80the library. 81.Ss Core Files 82The 83.Nm 84library has the ability to open and interpret core files produced by 85processes on the system. 86Process core dump generation is controlled by the 87.Xr coreadm 1M 88command. 89In addition, the library has the ability to understand and interpret core dumps 90generated by Linux kernel and can provide a subset of its functionality on such 91core files, provided the original binary is also present. 92.Pp 93Not all functions in the 94.Nm 95library are valid for core files. 96In general, none of the commands which manipulate the current state of a process 97or thread or that try to force system calls on a victim process will work. 98Furthermore several of the information and iteration interfaces are limited 99based on the data that is available in the core file. 100For example, if the core file is of a process that omits the frame pointer, the 101ability to iterate the stack will be limited. 102.Pp 103Use the 104.Fn Pgrab_core 105or 106.Fn Pfgrab_core 107function to open a core file. 108Use the 109.Fn Pgrab_file 110function to open an ELF object file. 111This is useful for obtaining information stored in ELF headers and 112sections. 113.Ss Debug Information 114Many of the operations in the library rely on debug information being 115present in a process and its associated libraries. 116The library leverages symbol table information, CTF data 117.Pf ( Xr CTF 4 ) 118sections, and frame unwinding information based on the use of an ABI 119defined frame pointer, eg. 120.Sy %ebp 121and 122.Sy %rbp 123on x86 systems. 124.Pp 125Some software providers strip programs of this information or build 126their executables such that the information will not be present in a 127core dump. 128To deal with this fact, the library is able to consume information that is not 129present in the core file or the running process. 130It can both consume it from the underlying executable and it also supports 131finding it from related ELF objects that are linked to it via the 132.Sy .gnu_debuglink 133and the 134.Sy .note.gnu.build-id 135ELF sections. 136.Ss Iteration Interfaces 137The 138.Nm 139library provides the ability to iterate over the following aspects of a 140process or core file: 141.Bl -bullet -offset indent 142.It 143Active threads 144.It 145Active and zombie threads 146.It 147All non-system processes 148.It 149All process mappings 150.It 151All objects in a process 152.It 153The environment 154.It 155The symbol table 156.It 157Stack frames 158.It 159File Descriptors 160.El 161.Ss System Call Injection 162The 163.Nm 164library allows the caller to force system calls to be executed in the 165context of the running process. 166This can be used both as a tool for introspection, allowing one to get 167information outside its current context as well as performing modifications to a 168process. 169.Pp 170These functions run in the context of the calling process. 171This is often an easier way of getting non-exported information about a 172process from the system. 173For example, the 174.Xr pfiles 1 175command uses this interface to get more detailed information about a 176process's open file descriptors, which it would not have access to 177otherwise. 178.Sh INTERFACES 179The shared object 180.Sy libproc.so.1 181provides the public interfaces defined below. 182See 183.Xr Intro 3 184for additional information on shared object interfaces. 185Functions are organized into categories that describe their purpose. 186Individual functions are documented in their own manual pages. 187.Ss Creation, Grabbing, and Releasing 188The following routines are related to creating library handles, 189grabbing cores, processes, and threads, and releasing those resources. 190.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr" 191.It Sy Lfree Ta Sy Lgrab 192.It Sy Lgrab_error Ta Sy Pcreate 193.It Sy Pcreate_agent Ta Sy Pcreate_callback 194.It Sy Pcreate_error Ta Sy Pdestroy_agent 195.It Sy Pfgrab_core Ta Sy Pfree 196.It Sy Pgrab Ta Sy Pgrab_core 197.It Sy Pgrab_error Ta Sy Pgrab_file 198.It Sy Pgrab_ops Ta Sy Prelease 199.It Sy Preopen Ta Sy Pxcreate 200.El 201.Ss Process interrogation and manipulation 202The following routines obtain information about a process and allow 203manipulation of the process itself. 204.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr" 205.It Sy Paddr_to_ctf Ta Sy Paddr_to_loadobj 206.It Sy Paddr_to_map Ta Sy Paddr_to_text_map 207.It Sy Pasfd Ta Sy Pclearfault 208.It Sy Pclearsig Ta Sy Pcontent 209.It Sy Pcred Ta Sy Pctlfd 210.It Sy Pdelbkpt Ta Sy Pdelwapt 211.It Sy Pdstop Ta Sy Pexecname 212.It Sy Pfault Ta Sy Pfgcore 213.It Sy Pgcore Ta Sy Pgetareg 214.It Sy Pgetauxval Ta Sy Pgetauxvec 215.It Sy Pgetenv Ta Sy Pisprocdir 216.It Sy Pissyscall_prev Ta Sy Plmid 217.It Sy Plmid_to_loadobj Ta Sy Plmid_to_map 218.It Sy Plookup_by_addr Ta Sy Plookup_by_name 219.It Sy Plwp_alt_stack Ta Sy Plwp_getfpregs 220.It Sy Plwp_getname Ta Sy Plwp_getpsinfo 221.It Sy Plwp_getregs Ta Sy Plwp_getspymaster 222.It Sy Plwp_main_stack Ta Sy Plwp_setfpregs 223.It Sy Plwp_setregs Ta Sy Plwp_stack 224.It Sy Pname_to_ctf Ta Sy Pname_to_loadobj 225.It Sy Pname_to_map Ta Sy Pobjname 226.It Sy Pobjname_resolved Ta Sy Pplatform 227.It Sy Ppltdest Ta Sy Ppriv 228.It Sy Ppsinfo Ta Sy Pputareg 229.It Sy Prd_agent Ta Sy Pread 230.It Sy Pread_string Ta Sy Preset_maps 231.It Sy Psetbkpt Ta Sy Psecflags 232.It Sy Psetcred Ta Sy Psetfault 233.It Sy Psetflags Ta Sy Psetpriv 234.It Sy Psetrun Ta Sy Psetsignal 235.It Sy Psetsysentry Ta Sy Psetsysexit 236.It Sy Psetwapt Ta Sy Psetzoneid 237.It Sy Psignal Ta Sy Pstate 238.It Sy Pstatus Ta Sy Pstop 239.It Sy Pstopstatus Ta Sy Psync 240.It Sy Psysentry Ta Sy Psysexit 241.It Sy Puname Ta Sy Punsetflags 242.It Sy Pupdate_maps Ta Sy Pupdate_syms 243.It Sy Pwait Ta Sy Pwrite 244.It Sy Pxecbkpt Ta Sy Pxecwapt 245.It Sy Pxlookup_by_addr Ta Sy Pxlookup_by_addr_resolved 246.It Sy Pxlookup_by_name Ta Sy Pzonename 247.It Sy Pzonepath Ta Sy Pzoneroot Ta 248.El 249.Ss Thread interrogation and manipulation 250The following routines obtain information about a thread and allow 251manipulation of the thread itself. 252.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr" 253.It Sy Lalt_stack Ta Sy Lclearfault 254.It Sy Lclearsig Ta Sy Lctlfd 255.It Sy Ldstop Ta Sy Lgetareg 256.It Sy Lmain_stack Ta Sy Lprochandle 257.It Sy Lpsinfo Ta Sy Lputareg 258.It Sy Lsetrun Ta Sy Lstack 259.It Sy Lstate Ta Sy Lstatus 260.It Sy Lstop Ta Sy Lsync 261.It Sy Lwait Ta Sy Lxecbkpt 262.It Sy Lxecwapt Ta "" 263.El 264.Ss System Call Injection 265The following routines are used to inject specific system calls and have 266them run in the context of a process. 267.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr" 268.It Sy pr_access Ta Sy pr_close 269.It Sy pr_creat Ta Sy pr_door_info 270.It Sy pr_exit Ta Sy pr_fcntl 271.It Sy pr_fstat Ta Sy pr_fstat64 272.It Sy pr_fstatvfs Ta Sy pr_getitimer 273.It Sy pr_getpeername Ta Sy pr_getpeerucred 274.It Sy pr_getprojid Ta Sy pr_getrctl 275.It Sy pr_getrlimit Ta Sy pr_getrlimit64 276.It Sy pr_getsockname Ta Sy pr_getsockopt 277.It Sy pr_gettaskid Ta Sy pr_getzoneid 278.It Sy pr_ioctl Ta Sy pr_link 279.It Sy pr_llseek Ta Sy pr_lseek 280.It Sy pr_lstat Ta Sy pr_lstat64 281.It Sy pr_memcntl Ta Sy pr_meminfo 282.It Sy pr_mmap Ta Sy pr_munmap 283.It Sy pr_open Ta Sy pr_processor_bind 284.It Sy pr_rename Ta Sy pr_setitimer 285.It Sy pr_setrctl Ta Sy pr_setrlimit 286.It Sy pr_setrlimit64 Ta Sy pr_settaskid 287.It Sy pr_sigaction Ta Sy pr_stat 288.It Sy pr_stat64 Ta Sy pr_statvfs 289.It Sy pr_unlink Ta Sy pr_waitid 290.El 291.Ss Iteration routines 292These routines are used to iterate over the contents of a process. 293.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr" 294.It Sy Penv_iter Ta Sy Plwp_iter 295.It Sy Plwp_iter_all Ta Sy Pmapping_iter 296.It Sy Pmapping_iter_resolved Ta Sy Pobject_iter 297.It Sy Pobject_iter_resolved Ta Sy Pstack_iter 298.It Sy Psymbol_iter Ta Sy Psymbol_iter_by_addr 299.It Sy Psymbol_iter_by_lmid Ta Sy Psymbol_iter_by_name 300.It Sy Pxsymbol_iter Ta Sy Pfdinfo_iter 301.El 302.Ss Utility routines 303The following routines are utilities that are useful to consumers of the 304library. 305.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr" 306.It Sy Perror_printf Ta Sy proc_arg_grab 307.It Sy proc_arg_psinfo Ta Sy proc_arg_xgrab 308.It Sy proc_arg_xpsinfo Ta Sy proc_content2str 309.It Sy proc_finistdio Ta Sy proc_fltname 310.It Sy proc_fltset2str Ta Sy proc_flushstdio 311.It Sy proc_get_auxv Ta Sy proc_get_cred 312.It Sy proc_get_priv Ta Sy proc_get_psinfo 313.It Sy proc_get_status Ta Sy proc_initstdio 314.It Sy proc_lwp_in_set Ta Sy proc_lwp_range_valid 315.It Sy proc_signame Ta Sy proc_sigset2str 316.It Sy proc_str2content Ta Sy proc_str2flt 317.It Sy proc_str2fltset Ta Sy proc_str2sig 318.It Sy proc_str2sigset Ta Sy proc_str2sys 319.It Sy proc_str2sysset Ta Sy proc_sysname 320.It Sy proc_sysset2str Ta Sy proc_unctrl_psinfo 321.It Sy proc_walk Ta "" 322.El 323.Ss x86 Specific Routines 324The following routines are specific to the x86, 32-bit and 64-bit, 325versions of the 326.Nm 327library. 328.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr" 329.It Sy Pldt Ta Sy proc_get_ldt 330.El 331.Ss SPARC specific Routines 332The following functions are specific to the SPARC, 32-bit and 64-bit, 333versions of the 334.Nm 335library. 336.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr" 337.It Sy Plwp_getgwindows Ta Sy Plwp_getxregs 338.It Sy Plwp_setxregs Ta Sy "" 339.El 340.Pp 341The following functions are specific to the 64-bit SPARC version of the 342.Nm 343library. 344.Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr" 345.It Sy Plwp_getasrs Ta Sy Plwp_setasrs 346.El 347.Sh PROCESS STATES 348Every process handle that exists in 349.Nm 350has a state. 351In some cases, such as for core files, these states are static. 352In other cases, such as handles that correspond to a running process or a 353created process, these states are dynamic and change based on actions taken in 354the library. 355The state can be obtained with the 356.Xr Pstate 3PROC 357function. 358.Pp 359The various states are: 360.Bl -tag -width Dv -offset indent 361.It Dv PS_RUN 362An actively running process. 363This may be a process that was obtained by creating it with functions such as 364.Xr Pcreate 3PROC 365or by grabbing an existing process such as 366.Xr Pgrab 3PROC . 367.It Dv PS_STOP 368An active process that is no longer executing. 369A process may stop for many reasons such as an explicit stop request (through 370.Xr pstop 1 371for example) or if a tracing event is hit. 372.Pp 373The reason a process is stopped may be obtained through the thread's 374.Sy lwpstatus_t 375structure read directly from /proc or obtained through the 376.Xr Lstatus 3PROC 377function. 378.It Dv PS_LOST 379Control over the process has been lost. 380This may happen when the process executes a new image requiring a different set 381of privileges. 382To resume control call 383.Xr Preopen 3PROC . 384For more information on losing control of a process, see 385.Xr proc 4 . 386.It DV PS_UNDEAD 387A zombie process. 388It has terminated, but it has not been cleaned up yet by its parent. 389For more on the conditions of becoming a zombie, see 390.Xr exec 2 . 391.It DV_PS_DEAD 392Processes in this state are always core files. 393See the earlier section 394.Sx Core Files 395for more information on working with core files. 396.It Dv PS_IDLE 397A process that has never been run. 398This is always the case for handles that refer to files as the files cannot be 399executed. 400Those process handles are obtained through calling 401.Xr Pgrab_file 3PROC . 402.El 403.Pp 404Many functions relating to tracing processes, for example 405.Xr Psignal 3PROC , 406.Xr Psetsignal 3PROC , 407.Xr Psetfault 3PROC , 408.Xr Psysentry 3PROC , 409and others, mention that they only act upon 410.Em Active Processes . 411This specifically refers to processes whose state are in 412.Dv PS_RUN 413and 414.Dv PS_STOP . 415Process handles in the other states have no notion of settable tracing 416flags, though core files 417.Pf ( type Dv PS_DEAD ) 418may have a read-only snapshot of their tracing settings available. 419.Sh TYPES 420The 421.Nm 422library uses many types that come from the /proc file system 423.Pf ( Xr proc 4 ) 424and the ELF format 425.Pf ( Xr elf 3ELF ) . 426However, it also defines the following types: 427.Pp 428.Sy struct ps_prochandle 429.Pp 430The 431.Sy struct ps_prochandle 432is an opaque handle to the library and the core element of control for a 433process. 434Consumers obtain pointers to a handle through the use of the 435.Fn Pcreate , 436.Fn Pgrab , 437and related functions. 438When a caller is done with a handle, then it should call one of the 439.Fn Pfree 440and 441.Fn Prelease 442functions to relinquish the handle, release associated resources, and 443potentially set the process to run again. 444.Pp 445.Sy struct ps_lwphandle 446.Pp 447The 448.Sy struct ps_lwphandle 449is analogous to the 450.Sy struct ps_prochandle , 451but it represents the control of an individual thread, rather than a 452process. 453Consumers obtain pointers to a handle through the 454.Fn Lgrab 455function and relinquish it with the 456.Fn Lfree 457function. 458.Pp 459.Sy core_content_t 460.Pp 461The 462.Sy core_content_t 463is a value which describes the various content types of core files. 464These are used in functions such as 465.Xr Pcontent 3PROC 466and 467.Xr Pgcore 3PROC 468to describe and control the types of content that get included. 469Various content types may be included together through a bitwise-inclusive-OR. 470The default system core contents are controlled with the 471.Xr coreadm 1M 472tool. 473The following table lists the current set of core contents in the system, though 474the set may increase over time. 475The string after the macro is the human readable string that corresponds with 476the constant and is used by 477.Xr coreadm 1M , 478.Xr proc_content2str 3PROC , 479and 480.Xr proc_str2content 3PROC . 481.Bl -tag -offset indent -width indent 482.It Dv CC_CONTENT_STACK ("stack") 483The contents include the process stack. 484Note, this only covers the main thread's stack. 485The stack of other threads is covered by 486.Dv CC_CONTENT_ANON . 487.It Dv CC_CONTENT_HEAP ("heap") 488The contents include the process heap. 489.It Dv CC_CONTENT_SHFILE ("shfile") 490The contents include shared mappings that are backed by files (e.g. 491mapped through 492.Xr mmap 2 493with the 494.Dv MAP_SHARED 495flag). 496.It Dv CC_CONTENT_SHANNON ("shannon") 497The contents include shared mappings that are backed by anonymous memory 498(e.g. mapped through 499.Xr mmap 2 500with the 501.Dv MAP_SHARED 502and 503.Dv MAP_ANON 504flags). 505.It Dv CC_CONTENT_RODATA ("rodata") 506The contents include private read-only file mappings, such as shared 507library text. 508.It Dv CC_CONTENT_ANON ("anon") 509The contents include private anonymous mappings. 510This includes the stacks of threads which are not the main thread. 511.It Dv CC_CONTENT_SHM ("shm") 512The contents include system V shared memory. 513.It Dv CC_CONTENT_ISM ("ism") 514The contents include ISM (intimate shared memory) mappings. 515.It Dv CC_CONTENT_DISM ("dism") 516The contents include DISM (dynamic shared memory) mappings. 517.It Dv CC_CONTENT_CTF ("ctf") 518The contents include 519.Xr ctf 4 520(Compact C Type Format) information. 521Note, not all objects in the process may have CTF information available. 522.It Dv CC_CONTENT_SYMTAB ("symtab") 523The contents include the symbol table. 524Note, not all objects in the process may have a symbol table available. 525.It Dv CC_CONTENT_ALL ("all") 526This value indicates that all of the above content values are present. 527Note that additional values may be added in the future, in which case 528the value of the symbol will be updated to include them. 529Comparisons with 530.Dv CC_CONTENT_ALL 531should validate all the expected bits are set by an expression such as 532.Li (c & CC_CONTENT_ALL) == CC_CONTENT_ALL . 533.It Dv CC_CONTENT_NONE ("none") 534This value indicates that there is no content present. 535.It Dv CC_CONTENT_DEFAULT ("default") 536The content includes the following set of default values: 537.Dv CC_CONTENT_STACK , 538.Dv CC_CONTENT_HEAP , 539.Dv CC_CONTENT_ISM , 540.Dv CC_CONTENT_DISM , 541.Dv CC_CONTENT_SHM , 542.Dv CC_CONTENT_SHANON , 543.Dv CC_CONTENT_TEXT , 544.Dv CC_CONTENT_DATA , 545.Dv CC_CONTENT_RODATA , 546.Dv CC_CONTENT_ANON , 547.Dv CC_CONTENT_CTF , 548and 549.Dv CC_CONTENT_SYMTAB. 550Note that the default may change. 551Comparisons with CC_CONTENT_DEFAULT should validate that all of the expected 552bits are set with an expression such as 553.Li (c\ &\ CC_CONTENT_DEFAULT)\ ==\ CC_CONTENT_DEFAULT. 554.It Dv CC_CONTENT_INVALID 555This indicates that the contents are invalid. 556.El 557.Pp 558.Sy prfdinfo_t 559.Pp 560The 561.Sy prfdinfo_t 562structure is used with the 563.Fn Pfdinfo_iter 564function which describes information about a file descriptor. 565The structure is defined as follows: 566.Bd -literal 567typedef struct prfdinfo { 568 int pr_fd; 569 mode_t pr_mode; 570 uid_t pr_uid; 571 gid_t pr_gid; 572 major_t pr_major; /* think stat.st_dev */ 573 minor_t pr_minor; 574 major_t pr_rmajor; /* think stat.st_rdev */ 575 minor_t pr_rminor; 576 ino64_t pr_ino; 577 off64_t pr_offset; 578 off64_t pr_size; 579 int pr_fileflags; /* fcntl(F_GETXFL), etc */ 580 int pr_fdflags; /* fcntl(F_GETFD), etc. */ 581 char pr_path[MAXPATHLEN]; 582} prfdinfo_t; 583.Ed 584.Pp 585The structure has similar information to that found in the 586.Sy stat 587structure that's used as part of the stat family of system calls, 588defined in 589.Xr stat 2 . 590The member 591.Sy pr_fd 592contains the number of the file descriptor of the file. 593The members 594.Sy pr_mode , 595.Sy pr_uid , 596.Sy pr_gid , 597.Sy pr_ino , 598and 599.Sy pr_size 600are the same as the members 601.Sy st_mode , 602.Sy st_uid , 603.Sy st_gid , 604.Sy st_ino , 605and 606.Sy st_size 607in the 608.Sy stat 609structure. 610.Pp 611The 612.Sy pr_major 613and 614.Sy pr_minor 615members contain the major and minor numbers of the device containing the 616directory for this file. 617This is similar to the 618.Sy st_dev 619member of the 620.Sy stat 621structure, except that it is broken out into its major and minor components. 622The 623.Sy pr_rmajor 624and 625.Sy pr_rminor 626members are similar in spirit to 627.Sy pr_major 628and 629.Sy pr_minor ; 630however, they are equivalent to the 631.Sy st_rdev 632member of the 633.Sy stat 634structure and thus have meaning for special character and block files. 635.Pp 636The 637.Sy pr_offset 638member contains the current seek offset of the file descriptor. 639The 640.Sy pr_fileflags 641and 642.Sy pr_fdflags 643members contain the flags that would have been returned by a call to 644.Xr fcntl 2 645with the arguments 646.Dv F_GETXFL 647and 648.Dv F_GETFD 649respectively. 650.Pp 651.Sy prsyminfo_t 652.Pp 653The 654.Sy prsyminfo_t 655structure is used with the various symbol look up functions 656.Fn Pxlookup_by_name , 657.Fn Pxlookup_by_addr , 658and 659.Fn Pxlookup_by_addr_resolved 660which describes additional information about a symbol. 661The structure is defined as follows: 662.Bd -literal 663typedef struct prsyminfo { 664 const char *prs_object; /* object name */ 665 const char *prs_name; /* symbol name */ 666 Lmid_t prs_lmid; /* link map id */ 667 uint_t prs_id; /* symbol id */ 668 uint_t prs_table; /* symbol table id */ 669} prsyminfo_t; 670.Ed 671.Pp 672The member 673.Sy prs_object 674points to a string that contains the name of the object file, if known, 675that the symbol comes from. 676The member 677.Sy prs_name 678points to the name of the symbol, if known. 679This may be unknown due to a stripped binary that contains no symbol table. 680The member 681.Sy prs_lmid 682indicates the link map identifier that the symbol was found on. 683For more information on link map identifiers refer to the 684.Em Linker and Libraries Guide 685and 686.Xr dlopen 3C . 687.Pp 688The members 689.Sy prs_id 690and 691.Sy prs_table 692can be used to determine both the symbol table that the entry came from 693and which entry in the table it corresponds to. 694If the value of 695.Sy prs_table 696is 697.Dv PR_SYMTAB 698then it came from the ELF standard symbol table. 699However, if it is instead 700.Dv PR_DYNSYM , 701then that indicates that it comes from the process's dynamic section. 702.Pp 703.Sy proc_lwp_f 704.Pp 705The 706.Sy proc_lwp_f 707is a function pointer type that is used with the 708.Fn Plwp_iter 709function. 710It is defined as 711.Sy typedef 712.Ft int 713.Fo proc_lwp_f 714.Fa "void *" 715.Fa "const lwpstatus_t *" 716.Fc . 717The first argument is a pointer to an argument that the user specifies, 718while the second has the thread's status information and is defined in 719.Xr proc 4 . 720For additional information on using this type, see 721.Xr Plwp_iter 3PROC . 722.Pp 723.Sy proc_lwp_all_f 724.Pp 725The 726.Sy proc_lwp_all_f 727is a function pointer type that is used with the 728.Fn Plwp_iter_all 729function. 730It is defined as 731.Sy typedef 732.Ft int 733.Fo proc_lwp_all_f 734.Fa "void *" 735.Fa "const lwpstatus_t *" 736.Fa "const lwpsinfo_t *" 737.Fc . 738The first argument is a pointer to an argument that the user specifies. 739The second and third arguments contain the thread's status and 740thread-specific 741.Xr ps 1 742information respectively. 743Both structures are defined in 744.Xr proc 4 . 745For additional information on using this type, see 746.Xr Plwp_iter_all 3PROC . 747.Pp 748.Sy proc_walk_f 749.Pp 750The 751.Sy proc_walk_f 752is a function pointer type that is used with the 753.Fn proc_walk 754function. 755It is defined as 756.Sy typedef 757.Ft int 758.Fo proc_walk_f 759.Fa "psinfo_t *" 760.Fa "lwpsinfo_t *" 761.Fa "void *" 762.Fc . 763The first argument contains the process 764.Xr ps 1 765information and the second argument contains the representative thread's 766.Xr ps 1 767information. 768Both structures are defined in 769.Xr proc 4 . 770The final argument is a pointer to an argument that the user specifies. 771For more information on using this, see 772.Xr proc_walk 3PROC . 773.Pp 774.Sy proc_map_f 775.Pp 776The 777.Sy proc_map_f 778is a function pointer type that is used with the 779.Fn Pmapping_iter , 780.Fn Pmapping_iter_resolved , 781.Fn Pobject_iter , 782and 783.Fn Pobject_iter_resolved 784functions. 785It is defined as 786.Sy typedef 787.Ft int 788.Fo proc_map_f 789.Fa "void *" 790.Fa "const prmap_t *" 791.Fa "const char *" 792.Fc . 793The first argument is a pointer to an argument that the user specifies. 794The second argument is describes the mapping information and is defined 795in 796.Xr proc 4 . 797The final argument contains the name of the mapping or object file in 798question. 799For additional information on using this type, see 800.Xr Pmapping_iter 3PROC . 801.Pp 802.Sy proc_env_f 803.Pp 804The 805.Sy proc_env_f 806is a function pointer type that is used with the 807.Fn Penv_iter 808function. 809It is defined as 810.Sy typedef 811.Ft int 812.Fo proc_env_f 813.Fa "void *" 814.Fa "struct ps_prochandle *" 815.Fa "uintptr_t" 816.Fa "const char *" 817.Fc . 818The first argument is a pointer to an argument that the user specifies. 819The second argument is a pointer to the 820.Sy struct ps_prochandle 821that the callback was passed to. 822The third argument is the address of the environment variable in the process. 823The fourth argument is the environment variable. 824Values in the environment follow the convention of the form 825.Em variable=value . 826For more information on environment variables see 827.Xr exec 2 828and 829.Xr environ 5 . 830For additional information on using this type, see 831.Xr Penv_iter 3PROC . 832.Pp 833.Sy proc_sym_f 834.Pp 835The 836.Sy proc_sym_f 837is a function pointer type that is used with the 838.Fn Psmbol_iter , 839.Fn Psymbol_iter_by_addr , 840.Fn Psymbol_iter_by_name , 841and 842.Fn Psymbol_iter_by_lmid 843functions. 844It is defined as 845.Sy typedef 846.Ft int 847.Fo proc_sym_f 848.Fa "void *" 849.Fa "const GElf_Sym *" 850.Fa "const char *" 851.Fc . 852The first argument is a pointer to an argument that the user supplies. 853The second argument is a pointer to the ELF symbol information in a 85432-bit and 64-bit neutral form. 855See 856.Xr elf 3ELF 857and 858.Xr gelf 3ELF 859for more information on it. 860The final argument points to a character string that has the name of the symbol. 861For additional information on using this type, see 862.Xr Psymbol_iter 3PROC , 863.Xr Psymbol_iter_by_addr 3PROC , 864.Xr Psymbol_iter_by_name 3PROC , 865and 866.Xr Psymbol_iter_by_lmid 3PROC . 867.Pp 868.Sy proc_xsym_f 869.Pp 870The 871.Sy proc_xsym_f 872is a function pointer type that is used with the 873.Fn Pxsymbol_iter 874function. 875It is defined as 876.Sy typedef 877.Ft int 878.Fo proc_xsym_f 879.Fa "void *" 880.Fa "const GElf_Sym *" 881.Fa "const char *" 882.Fa "const prsyminfo_t *" 883.Fc . 884The first three arguments are identical to those of 885.Sy proc_sym_f . 886The final argument contains additional information about the symbol 887itself. 888The members of the 889.Sy prsyminfo_t 890are defined earlier in this section. 891For additional information on using this type, see 892.Xr Pxsymbol_iter 3PROC . 893.Pp 894.Sy proc_stack_f 895.Pp 896The 897.Sy proc_stack_f 898is a function pointer type that is used with the 899.Fn Pstack_iter 900function. 901It is defined as 902.Sy typedef 903.Ft int 904.Fo proc_stack_f 905.Fa "void *" 906.Fa "prgregset_t" 907.Fa "uint_t" 908.Fa "const long *" 909.Fc . 910The first argument is a pointer to an argument that the user specifies. 911The second argument's contents are platform specific. 912The registers that contain stack information, usually the stack pointer and 913frame pointer, will be filled in to point to an entry. 914The 915.Sy prgregset_t 916is defined in 917.Xr proc 4 . 918.Pp 919The third argument contains the number of arguments to the current stack 920frame and the fourth argument contains an array of addresses that 921correspond to the arguments to that stack function. 922The value of the third argument dictates the number of entries in the fourth 923argument. 924For additional information on using this type, see 925.Xr Pstack_iter 3PROC . 926.Pp 927.Sy proc_fdinfo_f 928.Pp 929The 930.Sy proc_fdinfo_f 931is a function pointer type that is used with the 932.Fn Pfdinfo_iter 933function. 934It is defined as 935.Sy typedef 936.Ft int 937.Fo proc_fdinfo_f 938.Fa "void *" 939.Fa "prfdinfo_t *" 940.Fc . 941The first argument is a pointer to an argument that the user specifies. 942The second argument contains information about an open file descriptor. 943The members of the 944.Sy prfdinfo_t 945are defined earlier in this section. 946For additional information on using this type, see 947.Xr Pfdinfo_iter 3PROC . 948.Sh PROGRAMMING NOTES 949When working with live processes, whether from the 950.Xr Pgrab 3PROC 951or 952.Xr Pcreate 3PROC 953family of functions, there are some additional considerations. 954Importantly, if a process calls any of the 955.Xr exec 2 956suite of functions, much of the state information that is obtained, 957particularly that about mappings in the process will be invalid. 958Callers must ensure that they call 959.Xr Preset_maps 3PROC 960when they hold a process handle across an exec. 961In addition, users of the library should familiarize themselves with the 962.Sy PROGRAMMING NOTES 963section of the 964.Xr proc 4 965manual page, which discusses issues of privileges and security. 966.Sh DEBUGGING 967The library provides a means for obtaining additional debugging 968information. 969The output itself is not part of the 970.Nm 971library's stable interface. 972Setting the environment variable 973.Ev LIBPROC_DEBUG 974to some value will print information to standard error. 975For example, 976.Ev LIBPROC_DEUBG Ns = Ns Em please . 977.Sh LOCKING 978Most functions operate on a handle to a process in the form of a 979.Vt "struct ps_prochandle *" . 980Unless otherwise indicated, the library does not provide any 981synchronization for different routines that are operating on the 982.Sy same 983.Nm 984library handle. 985It is up to the caller to ensure that only a single thread is using a handle at 986any given time. 987Multiple threads may call 988.Nm 989library routines at the same time as long as each thread is using a 990different handle. 991.Pp 992Each individual function notes its 993.Sy MT-Level 994section. 995The MT-Level of a routine that matches the above description will refer to this 996manual page. 997If it does not, then it refers to the standard attributes in 998.Xr attributes 5 . 999.Sh INTERFACE STABILITY 1000.Sy Uncommitted 1001.Pp 1002While the library is considered an uncommitted interface, and is still 1003evolving, changes that break compatibility have been uncommon and this 1004trend is expected to continue. 1005It is documented to allow consumers, whether part of illumos or outside of it, 1006to understand the libarary and make use of it with the understanding that 1007changes may occur which break both source and binary compatibility. 1008.Sh SEE ALSO 1009.Xr gcore 1 , 1010.Xr mdb 1 , 1011.Xr proc 1 , 1012.Xr ps 1 , 1013.Xr coreadm 1M , 1014.Xr exec 2 , 1015.Xr fcntl 2 , 1016.Xr stat 2 , 1017.Xr Intro 3 , 1018.Xr dlopen 3C , 1019.Xr elf 3ELF , 1020.Xr ctf 4 , 1021.Xr proc 4 , 1022.Xr attributes 5 , 1023.Xr environ 5 , 1024.Xr privileges 5 1025.Pp 1026.Rs 1027.%T Linkers and Libraries Guide 1028.Re 1029.Pp 1030.Xr Lfree 3PROC , 1031.Xr Lgrab 3PROC , 1032.Xr Lgrab_error 3PROC , 1033.Xr Pcreate 3PROC , 1034.Xr Pcreate_agent 3PROC , 1035.Xr Pcreate_callback 3PROC , 1036.Xr Pcreate_error 3PROC , 1037.Xr Pdestroy_agent 3PROC , 1038.Xr Pfgrab_core 3PROC , 1039.Xr Pfree 3PROC , 1040.Xr Pgrab 3PROC , 1041.Xr Pgrab_core 3PROC , 1042.Xr Pgrab_error 3PROC , 1043.Xr Pgrab_file 3PROC , 1044.Xr Pgrab_ops 3PROC , 1045.Xr Prelease 3PROC , 1046.Xr Preopen 3PROC , 1047.Xr Pxcreate 3PROC 1048.Pp 1049.Xr Paddr_to_ctf 3PROC , 1050.Xr Paddr_to_loadobj 3PROC , 1051.Xr Paddr_to_map 3PROC , 1052.Xr Paddr_to_text_map 3PROC , 1053.Xr Pasfd 3PROC , 1054.Xr Pclearfault 3PROC , 1055.Xr Pclearsig 3PROC , 1056.Xr Pcontent 3PROC , 1057.Xr Pcred 3PROC , 1058.Xr Pctlfd 3PROC , 1059.Xr Pdelbkpt 3PROC , 1060.Xr Pdelwapt 3PROC , 1061.Xr Pdstop 3PROC , 1062.Xr Pexecname 3PROC , 1063.Xr Pfault 3PROC , 1064.Xr Pfgcore 3PROC , 1065.Xr Pgcore 3PROC , 1066.Xr Pgetareg 3PROC , 1067.Xr Pgetauxval 3PROC , 1068.Xr Pgetauxvec 3PROC , 1069.Xr Pgetenv 3PROC , 1070.Xr Pisprocdir 3PROC , 1071.Xr Pissyscall_prev 3PROC , 1072.Xr Plmid 3PROC , 1073.Xr Plmid_to_loadobj 3PROC , 1074.Xr Plmid_to_map 3PROC , 1075.Xr Plookup_by_addr 3PROC , 1076.Xr Plookup_by_name 3PROC , 1077.Xr Plwp_alt_stack 3PROC , 1078.Xr Plwp_getfpregs 3PROC , 1079.Xr Plwp_getpsinfo 3PROC , 1080.Xr Plwp_getregs 3PROC , 1081.Xr Plwp_getspymaster 3PROC , 1082.Xr Plwp_main_stack 3PROC , 1083.Xr Plwp_setfpregs 3PROC , 1084.Xr Plwp_setregs 3PROC , 1085.Xr Plwp_stack 3PROC , 1086.Xr Pname_to_ctf 3PROC , 1087.Xr Pname_to_loadobj 3PROC , 1088.Xr Pname_to_map 3PROC , 1089.Xr Pobjname 3PROC , 1090.Xr Pobjname_resolved 3PROC , 1091.Xr Pplatform 3PROC , 1092.Xr Ppltdest 3PROC , 1093.Xr Ppriv 3PROC , 1094.Xr Ppsinfo 3PROC , 1095.Xr Pputareg 3PROC , 1096.Xr Prd_agent 3PROC , 1097.Xr Pread 3PROC , 1098.Xr Pread_string 3PROC , 1099.Xr Preset_maps 3PROC , 1100.Xr Psecflags 3PROC , 1101.Xr Psetbkpt 3PROC , 1102.Xr Psetcred 3PROC , 1103.Xr Psetfault 3PROC , 1104.Xr Psetflags 3PROC , 1105.Xr Psetpriv 3PROC , 1106.Xr Psetrun 3PROC , 1107.Xr Psetsignal 3PROC , 1108.Xr Psetsysentry 3PROC , 1109.Xr Psetsysexit 3PROC , 1110.Xr Psetwapt 3PROC , 1111.Xr Psetzoneid 3PROC , 1112.Xr Psignal 3PROC , 1113.Xr Pstate 3PROC , 1114.Xr Pstatus 3PROC , 1115.Xr Pstop 3PROC , 1116.Xr Pstopstatus 3PROC , 1117.Xr Psync 3PROC , 1118.Xr Psysentry 3PROC , 1119.Xr Psysexit 3PROC , 1120.Xr Puname 3PROC , 1121.Xr Punsetflags 3PROC , 1122.Xr Pupdate_maps 3PROC , 1123.Xr Pupdate_syms 3PROC , 1124.Xr Pwait 3PROC , 1125.Xr Pwrite 3PROC , 1126.Xr Pxecbkpt 3PROC , 1127.Xr Pxecwapt 3PROC , 1128.Xr Pxlookup_by_addr 3PROC , 1129.Xr Pxlookup_by_addr_resolved 3PROC , 1130.Xr Pxlookup_by_name 3PROC , 1131.Xr Pzonename 3PROC , 1132.Xr Pzonepath 3PROC , 1133.Xr Pzoneroot 3PROC 1134.Pp 1135.Xr Lalt_stack 3PROC , 1136.Xr Lclearfault 3PROC , 1137.Xr Lclearsig 3PROC , 1138.Xr Lctlfd 3PROC , 1139.Xr Ldstop 3PROC , 1140.Xr Lgetareg 3PROC , 1141.Xr Lmain_stack 3PROC , 1142.Xr Lprochandle 3PROC , 1143.Xr Lpsinfo 3PROC , 1144.Xr Lputareg 3PROC , 1145.Xr Lsetrun 3PROC , 1146.Xr Lstack 3PROC , 1147.Xr Lstate 3PROC , 1148.Xr Lstatus 3PROC , 1149.Xr Lstop 3PROC , 1150.Xr Lsync 3PROC , 1151.Xr Lwait 3PROC , 1152.Xr Lxecbkpt 3PROC , 1153.Xr Lxecwapt 3PROC 1154.Pp 1155.Xr pr_access 3PROC , 1156.Xr pr_close 3PROC , 1157.Xr pr_creat 3PROC , 1158.Xr pr_door_info 3PROC , 1159.Xr pr_exit 3PROC , 1160.Xr pr_fcntl 3PROC , 1161.Xr pr_fstat 3PROC , 1162.Xr pr_fstat64 3PROC , 1163.Xr pr_fstatvfs 3PROC , 1164.Xr pr_getitimer 3PROC , 1165.Xr pr_getpeername 3PROC , 1166.Xr pr_getpeerucred 3PROC , 1167.Xr pr_getprojid 3PROC , 1168.Xr pr_getrctl 3PROC , 1169.Xr pr_getrlimit 3PROC , 1170.Xr pr_getrlimit64 3PROC , 1171.Xr pr_getsockname 3PROC , 1172.Xr pr_getsockopt 3PROC , 1173.Xr pr_gettaskid 3PROC , 1174.Xr pr_getzoneid 3PROC , 1175.Xr pr_ioctl 3PROC , 1176.Xr pr_link 3PROC , 1177.Xr pr_llseek 3PROC , 1178.Xr pr_lseek 3PROC , 1179.Xr pr_lstat 3PROC , 1180.Xr pr_lstat64 3PROC , 1181.Xr pr_memcntl 3PROC , 1182.Xr pr_meminfo 3PROC , 1183.Xr pr_mmap 3PROC , 1184.Xr pr_munmap 3PROC , 1185.Xr pr_open 3PROC , 1186.Xr pr_processor_bind 3PROC , 1187.Xr pr_rename 3PROC , 1188.Xr pr_setitimer 3PROC , 1189.Xr pr_setrctl 3PROC , 1190.Xr pr_setrlimit 3PROC , 1191.Xr pr_setrlimit64 3PROC , 1192.Xr pr_settaskid 3PROC , 1193.Xr pr_sigaction 3PROC , 1194.Xr pr_stat 3PROC , 1195.Xr pr_stat64 3PROC , 1196.Xr pr_statvfs 3PROC , 1197.Xr pr_unlink 3PROC , 1198.Xr pr_waitid 3PROC , 1199.Pp 1200.Xr Penv_iter 3PROC , 1201.Xr Plwp_iter 3PROC , 1202.Xr Plwp_iter_all 3PROC , 1203.Xr Pmapping_iter 3PROC , 1204.Xr Pmapping_iter_resolved 3PROC , 1205.Xr Pobject_iter 3PROC , 1206.Xr Pobject_iter_resolved 3PROC , 1207.Xr Pstack_iter 3PROC , 1208.Xr Psymbol_iter 3PROC , 1209.Xr Psymbol_iter_by_addr 3PROC , 1210.Xr Psymbol_iter_by_lmid 3PROC , 1211.Xr Psymbol_iter_by_name 3PROC , 1212.Xr Pxsymbol_iter 3PROC , 1213.Xr Pfdinfo_iter 3PROC 1214.Pp 1215.Xr Perror_printf 3PROC , 1216.Xr proc_arg_grab 3PROC , 1217.Xr proc_arg_psinfo 3PROC , 1218.Xr proc_arg_xgrab 3PROC , 1219.Xr proc_arg_xpsinfo 3PROC , 1220.Xr proc_content2str 3PROC , 1221.Xr proc_finistdio 3PROC , 1222.Xr proc_fltname 3PROC , 1223.Xr proc_fltset2str 3PROC , 1224.Xr proc_flushstdio 3PROC , 1225.Xr proc_get_auxv 3PROC , 1226.Xr proc_get_cred 3PROC , 1227.Xr proc_get_priv 3PROC , 1228.Xr proc_get_psinfo 3PROC , 1229.Xr proc_get_status 3PROC , 1230.Xr proc_initstdio 3PROC , 1231.Xr proc_lwp_in_set 3PROC , 1232.Xr proc_lwp_range_valid 3PROC , 1233.Xr proc_signame 3PROC , 1234.Xr proc_sigset2str 3PROC , 1235.Xr proc_str2content 3PROC , 1236.Xr proc_str2flt 3PROC , 1237.Xr proc_str2fltset 3PROC , 1238.Xr proc_str2sig 3PROC , 1239.Xr proc_str2sigset 3PROC , 1240.Xr proc_str2sys 3PROC , 1241.Xr proc_str2sysset 3PROC , 1242.Xr proc_sysname 3PROC , 1243.Xr proc_sysset2str 3PROC , 1244.Xr proc_unctrl_psinfo 3PROC , 1245.Xr proc_walk 3PROC 1246.Pp 1247.Xr Pldt 3PROC , 1248.Xr proc_get_ldt 3PROC , 1249.Pp 1250.Xr Plwp_getgwindows 3PROC , 1251.Xr Plwp_getxregs 3PROC , 1252.Xr Plwp_setxregs 3PROC , 1253.Pp 1254.Xr Plwp_getasrs 3PROC , 1255.Xr Plwp_setasrs 3PROC 1256