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