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