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 26 The 27 .Nm 28 library provides consumers a general series of interfaces to inspect 29 and control both live processes and core files. 30 It is intended for introspection tools such as debuggers by providing a 31 high-level interface to the /proc file system 32 .Pf ( Xr proc 4 ) . 33 .Pp 34 The 35 .Nm 36 library provides interfaces that focus on: 37 .Bl -bullet -offset indent 38 .It 39 Creating and attaching to live process, core files, and arbitrary ELF 40 objects. 41 .It 42 Interrogating the state of a process or core file. 43 .It 44 Manipulating the current state of a process or thread. 45 .It 46 Interrogating the state of threads of a process or core file. 47 .It 48 Running system calls in the context of another process. 49 .It 50 Various utilities for iterating process and core file file descriptors, 51 mappings, symbols, and more. 52 .It 53 Various utilities to support debugging tools. 54 .El 55 .Ss Live Processes 56 The 57 .Nm 58 library can be used to manipulate running processes and to create new 59 ones. 60 To manipulate an existing process first 61 .Em grab 62 it with the 63 .Fn Pgrab 64 function. 65 A process is generally stopped as a side effect of grabbing it. 66 Callers must exercise caution, as if they do not use the library correctly, or 67 they terminate unexpectedly, a process may remain stopped. 68 .Pp 69 Unprivileged users may only grab their own processes. 70 Users with the privilege 71 .Brq Sy PRIV_PROC_OWNER 72 may manipulate processes that they do not own; however, additional 73 restrictions as described in 74 .Xr privileges 5 75 apply. 76 .Pp 77 In addition, the 78 .Fn Pcreate 79 and 80 .Fn Pxcreate 81 functions may be used to create processes which are always controlled by 82 the library. 83 .Ss Core Files 84 The 85 .Nm 86 library has the ability to open and interpret core files produced by 87 processes on the system. 88 Process core dump generation is controlled by the 89 .Xr coreadm 1M 90 command. 91 In addition, the library has the ability to understand and interpret core dumps 92 generated by Linux kernel and can provide a subset of its functionality on such 93 core files, provided the original binary is also present. 94 .Pp 95 Not all functions in the 96 .Nm 97 library are valid for core files. 98 In general, none of the commands which manipulate the current state of a process 99 or thread or that try to force system calls on a victim process will work. 100 Furthermore several of the information and iteration interfaces are limited 101 based on the data that is available in the core file. 102 For example, if the core file is of a process that omits the frame pointer, the 103 ability to iterate the stack will be limited. 104 .Pp 105 Use the 106 .Fn Pgrab_core 107 or 108 .Fn Pfgrab_core 109 function to open a core file. 110 Use the 111 .Fn Pgrab_file 112 function to open an ELF object file. 113 This is useful for obtaining information stored in ELF headers and 114 sections. 115 .Ss Debug Information 116 Many of the operations in the library rely on debug information being 117 present in a process and its associated libraries. 118 The library leverages symbol table information, CTF data 119 .Pq Xr ctf 4 120 sections, and frame unwinding information based on the use of an ABI 121 defined frame pointer, e\&.g\&. 122 .Sy %ebp 123 and 124 .Sy %rbp 125 on x86 systems. 126 .Pp 127 Some software providers strip programs of this information or build 128 their executables such that the information will not be present in a 129 core dump. 130 To deal with this fact, the library is able to consume information that is not 131 present in the core file or the running process. 132 It can both consume it from the underlying executable and it also supports 133 finding it from related ELF objects that are linked to it via the 134 .Sy .gnu_debuglink 135 and the 136 .Sy .note.gnu.build-id 137 ELF sections. 138 .Ss Iteration Interfaces 139 The 140 .Nm 141 library provides the ability to iterate over the following aspects of a 142 process or core file: 143 .Bl -bullet -offset indent 144 .It 145 Active threads 146 .It 147 Active and zombie threads 148 .It 149 All non-system processes 150 .It 151 All process mappings 152 .It 153 All objects in a process 154 .It 155 The environment 156 .It 157 The symbol table 158 .It 159 Stack frames 160 .It 161 File Descriptors 162 .El 163 .Ss System Call Injection 164 The 165 .Nm 166 library allows the caller to force system calls to be executed in the 167 context of the running process. 168 This can be used both as a tool for introspection, allowing one to get 169 information outside its current context as well as performing modifications to a 170 process. 171 .Pp 172 These functions run in the context of the calling process. 173 This is often an easier way of getting non-exported information about a 174 process from the system. 175 For example, the 176 .Xr pfiles 1 177 command uses this interface to get more detailed information about a 178 process's open file descriptors, which it would not have access to 179 otherwise. 180 .Sh INTERFACES 181 The shared object 182 .Sy libproc.so.1 183 provides the public interfaces defined below. 184 See 185 .Xr Intro 3 186 for additional information on shared object interfaces. 187 Functions are organized into categories that describe their purpose. 188 Individual functions are documented in their own manual pages. 189 .Ss Creation, Grabbing, and Releasing 190 The following routines are related to creating library handles, 191 grabbing 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 204 The following routines obtain information about a process and allow 205 manipulation 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 252 The following routines obtain information about a thread and allow 253 manipulation 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 267 The following routines are used to inject specific system calls and have 268 them 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 294 These 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 305 The following routines are utilities that are useful to consumers of the 306 library. 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 326 The following routines are specific to the x86, 32-bit and 64-bit, 327 versions of the 328 .Nm 329 library. 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 334 The following functions are specific to the SPARC, 32-bit and 64-bit, 335 versions of the 336 .Nm 337 library. 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 343 The following functions are specific to the 64-bit SPARC version of the 344 .Nm 345 library. 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 350 Every process handle that exists in 351 .Nm 352 has a state. 353 In some cases, such as for core files, these states are static. 354 In other cases, such as handles that correspond to a running process or a 355 created process, these states are dynamic and change based on actions taken in 356 the library. 357 The state can be obtained with the 358 .Xr Pstate 3PROC 359 function. 360 .Pp 361 The various states are: 362 .Bl -tag -width Dv -offset indent 363 .It Dv PS_RUN 364 An actively running process. 365 This may be a process that was obtained by creating it with functions such as 366 .Xr Pcreate 3PROC 367 or by grabbing an existing process such as 368 .Xr Pgrab 3PROC . 369 .It Dv PS_STOP 370 An active process that is no longer executing. 371 A process may stop for many reasons such as an explicit stop request (through 372 .Xr pstop 1 373 for example) or if a tracing event is hit. 374 .Pp 375 The reason a process is stopped may be obtained through the thread's 376 .Vt lwpstatus_t 377 structure read directly from /proc or obtained through the 378 .Xr Lstatus 3PROC 379 function. 380 .It Dv PS_LOST 381 Control over the process has been lost. 382 This may happen when the process executes a new image requiring a different set 383 of privileges. 384 To resume control call 385 .Xr Preopen 3PROC . 386 For more information on losing control of a process, see 387 .Xr proc 4 . 388 .It Dv PS_UNDEAD 389 A zombie process. 390 It has terminated, but it has not been cleaned up yet by its parent. 391 For more on the conditions of becoming a zombie, see 392 .Xr exec 2 . 393 .It Dv PS_DEAD 394 Processes in this state are always core files. 395 See the earlier section 396 .Sx Core Files 397 for more information on working with core files. 398 .It Dv PS_IDLE 399 A process that has never been run. 400 This is always the case for handles that refer to files as the files cannot be 401 executed. 402 Those process handles are obtained through calling 403 .Xr Pgrab_file 3PROC . 404 .El 405 .Pp 406 Many functions relating to tracing processes, for example 407 .Xr Psignal 3PROC , 408 .Xr Psetsignal 3PROC , 409 .Xr Psetfault 3PROC , 410 .Xr Psysentry 3PROC , 411 and others, mention that they only act upon 412 .Em Active Processes . 413 This specifically refers to processes whose state are in 414 .Dv PS_RUN 415 and 416 .Dv PS_STOP . 417 Process handles in the other states have no notion of settable tracing 418 flags, though core files 419 .Pq type Dv PS_DEAD 420 may have a read-only snapshot of their tracing settings available. 421 .Sh TYPES 422 The 423 .Nm 424 library uses many types that come from the /proc file system 425 .Pq Xr proc 4 426 and the ELF format 427 .Pq Xr elf 3ELF . 428 However, it also defines the following types: 429 .Pp 430 .Vt struct ps_prochandle 431 .Pp 432 The 433 .Vt struct ps_prochandle 434 is an opaque handle to the library and the core element of control for a 435 process. 436 Consumers obtain pointers to a handle through the use of the 437 .Fn Pcreate , 438 .Fn Pgrab , 439 and related functions. 440 When a caller is done with a handle, then it should call one of the 441 .Fn Pfree 442 and 443 .Fn Prelease 444 functions to relinquish the handle, release associated resources, and 445 potentially set the process to run again. 446 .Pp 447 .Vt struct ps_lwphandle 448 .Pp 449 The 450 .Vt struct ps_lwphandle 451 is analogous to the 452 .Vt struct ps_prochandle , 453 but it represents the control of an individual thread, rather than a 454 process. 455 Consumers obtain pointers to a handle through the 456 .Fn Lgrab 457 function and relinquish it with the 458 .Fn Lfree 459 function. 460 .Pp 461 .Vt core_content_t 462 .Pp 463 The 464 .Vt core_content_t 465 is a value which describes the various content types of core files. 466 These are used in functions such as 467 .Xr Pcontent 3PROC 468 and 469 .Xr Pgcore 3PROC 470 to describe and control the types of content that get included. 471 Various content types may be included together through a bitwise-inclusive-OR. 472 The default system core contents are controlled with the 473 .Xr coreadm 1M 474 tool. 475 The following table lists the current set of core contents in the system, though 476 the set may increase over time. 477 The string after the macro is the human readable string that corresponds with 478 the constant and is used by 479 .Xr coreadm 1M , 480 .Xr proc_content2str 3PROC , 481 and 482 .Xr proc_str2content 3PROC . 483 .Bl -tag -offset indent -width indent 484 .It Dv CC_CONTENT_STACK ("stack") 485 The contents include the process stack. 486 Note, this only covers the main thread's stack. 487 The stack of other threads is covered by 488 .Dv CC_CONTENT_ANON . 489 .It Dv CC_CONTENT_HEAP ("heap") 490 The contents include the process heap. 491 .It Dv CC_CONTENT_SHFILE ("shfile") 492 The contents include shared mappings that are backed by files (e.g. 493 mapped through 494 .Xr mmap 2 495 with the 496 .Dv MAP_SHARED 497 flag). 498 .It Dv CC_CONTENT_SHANNON ("shannon") 499 The contents include shared mappings that are backed by anonymous memory 500 (e.g. mapped through 501 .Xr mmap 2 502 with the 503 .Dv MAP_SHARED 504 and 505 .Dv MAP_ANON 506 flags). 507 .It Dv CC_CONTENT_RODATA ("rodata") 508 The contents include private read-only file mappings, such as shared 509 library text. 510 .It Dv CC_CONTENT_ANON ("anon") 511 The contents include private anonymous mappings. 512 This includes the stacks of threads which are not the main thread. 513 .It Dv CC_CONTENT_SHM ("shm") 514 The contents include system V shared memory. 515 .It Dv CC_CONTENT_ISM ("ism") 516 The contents include ISM (intimate shared memory) mappings. 517 .It Dv CC_CONTENT_DISM ("dism") 518 The contents include DISM (dynamic shared memory) mappings. 519 .It Dv CC_CONTENT_CTF ("ctf") 520 The contents include 521 .Xr ctf 4 522 (Compact C Type Format) information. 523 Note, not all objects in the process may have CTF information available. 524 .It Dv CC_CONTENT_SYMTAB ("symtab") 525 The contents include the symbol table. 526 Note, not all objects in the process may have a symbol table available. 527 .It Dv CC_CONTENT_ALL ("all") 528 This value indicates that all of the above content values are present. 529 Note that additional values may be added in the future, in which case 530 the value of the symbol will be updated to include them. 531 Comparisons with 532 .Dv CC_CONTENT_ALL 533 should 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") 536 This value indicates that there is no content present. 537 .It Dv CC_CONTENT_DEFAULT ("default") 538 The 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 , 550 and 551 .Dv CC_CONTENT_SYMTAB . 552 Note that the default may change. 553 Comparisons with CC_CONTENT_DEFAULT should validate that all of the expected 554 bits are set with an expression such as 555 .Li (c\ &\ CC_CONTENT_DEFAULT)\ ==\ CC_CONTENT_DEFAULT . 556 .It Dv CC_CONTENT_INVALID 557 This indicates that the contents are invalid. 558 .El 559 .Pp 560 .Vt prfdinfo_t 561 .Pp 562 The 563 .Vt prfdinfo_t 564 structure is used with the 565 .Fn Pfdinfo_iter 566 function which describes information about a file descriptor. 567 The structure is defined as follows: 568 .Bd -literal 569 typedef 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 587 The structure has similar information to that found in the 588 .Sy stat 589 structure that's used as part of the stat family of system calls, 590 defined in 591 .Xr stat 2 . 592 The member 593 .Sy pr_fd 594 contains the number of the file descriptor of the file. 595 The members 596 .Fa pr_mode , 597 .Fa pr_uid , 598 .Fa pr_gid , 599 .Fa pr_ino , 600 and 601 .Fa pr_size 602 are the same as the members 603 .Fa st_mode , 604 .Fa st_uid , 605 .Fa st_gid , 606 .Fa st_ino , 607 and 608 .Fa st_size 609 in the 610 .Fa stat 611 structure. 612 .Pp 613 The 614 .Fa pr_major 615 and 616 .Fa pr_minor 617 members contain the major and minor numbers of the device containing the 618 directory for this file. 619 This is similar to the 620 .Fa st_dev 621 member of the 622 .Vt stat 623 structure, except that it is broken out into its major and minor components. 624 The 625 .Fa pr_rmajor 626 and 627 .Fa pr_rminor 628 members are similar in spirit to 629 .Fa pr_major 630 and 631 .Fa pr_minor ; 632 however, they are equivalent to the 633 .Fa st_rdev 634 member of the 635 .Vt stat 636 structure and thus have meaning for special character and block files. 637 .Pp 638 The 639 .Fa pr_offset 640 member contains the current seek offset of the file descriptor. 641 The 642 .Fa pr_fileflags 643 and 644 .Fa pr_fdflags 645 members contain the flags that would have been returned by a call to 646 .Xr fcntl 2 647 with the arguments 648 .Dv F_GETXFL 649 and 650 .Dv F_GETFD 651 respectively. 652 .Pp 653 .Vt prsyminfo_t 654 .Pp 655 The 656 .Vt prsyminfo_t 657 structure is used with the various symbol look up functions 658 .Fn Pxlookup_by_name , 659 .Fn Pxlookup_by_addr , 660 and 661 .Fn Pxlookup_by_addr_resolved 662 which describes additional information about a symbol. 663 The structure is defined as follows: 664 .Bd -literal 665 typedef 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 674 The member 675 .Fa prs_object 676 points to a string that contains the name of the object file, if known, 677 that the symbol comes from. 678 The member 679 .Fa prs_name 680 points to the name of the symbol, if known. 681 This may be unknown due to a stripped binary that contains no symbol table. 682 The member 683 .Fa prs_lmid 684 indicates the link map identifier that the symbol was found on. 685 For more information on link map identifiers refer to the 686 .%B Linker and Libraries Guide 687 and 688 .Xr dlopen 3C . 689 .Pp 690 The members 691 .Fa prs_id 692 and 693 .Fa prs_table 694 can be used to determine both the symbol table that the entry came from 695 and which entry in the table it corresponds to. 696 If the value of 697 .Fa prs_table 698 is 699 .Dv PR_SYMTAB 700 then it came from the ELF standard symbol table. 701 However, if it is instead 702 .Dv PR_DYNSYM , 703 then that indicates that it comes from the process's dynamic section. 704 .Pp 705 .Vt proc_lwp_f 706 .Pp 707 The 708 .Vt proc_lwp_f 709 is a function pointer type that is used with the 710 .Fn Plwp_iter 711 function. 712 It is defined as 713 .Sy typedef 714 .Ft int 715 .Fo proc_lwp_f 716 .Fa "void *" 717 .Fa "const lwpstatus_t *" 718 .Fc . 719 The first argument is a pointer to an argument that the user specifies, 720 while the second has the thread's status information and is defined in 721 .Xr proc 4 . 722 For additional information on using this type, see 723 .Xr Plwp_iter 3PROC . 724 .Pp 725 .Vt proc_lwp_all_f 726 .Pp 727 The 728 .Vt proc_lwp_all_f 729 is a function pointer type that is used with the 730 .Fn Plwp_iter_all 731 function. 732 It 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 . 740 The first argument is a pointer to an argument that the user specifies. 741 The second and third arguments contain the thread's status and 742 thread-specific 743 .Xr ps 1 744 information respectively. 745 Both structures are defined in 746 .Xr proc 4 . 747 For additional information on using this type, see 748 .Xr Plwp_iter_all 3PROC . 749 .Pp 750 .Vt proc_walk_f 751 .Pp 752 The 753 .Vt proc_walk_f 754 is a function pointer type that is used with the 755 .Fn proc_walk 756 function. 757 It 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 . 765 The first argument contains the process 766 .Xr ps 1 767 information and the second argument contains the representative thread's 768 .Xr ps 1 769 information. 770 Both structures are defined in 771 .Xr proc 4 . 772 The final argument is a pointer to an argument that the user specifies. 773 For more information on using this, see 774 .Xr proc_walk 3PROC . 775 .Pp 776 .Vt proc_map_f 777 .Pp 778 The 779 .Vt proc_map_f 780 is a function pointer type that is used with the 781 .Fn Pmapping_iter , 782 .Fn Pmapping_iter_resolved , 783 .Fn Pobject_iter , 784 and 785 .Fn Pobject_iter_resolved 786 functions. 787 It 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 . 795 The first argument is a pointer to an argument that the user specifies. 796 The second argument is describes the mapping information and is defined 797 in 798 .Xr proc 4 . 799 The final argument contains the name of the mapping or object file in 800 question. 801 For additional information on using this type, see 802 .Xr Pmapping_iter 3PROC . 803 .Pp 804 .Vt proc_env_f 805 .Pp 806 The 807 .Vt proc_env_f 808 is a function pointer type that is used with the 809 .Fn Penv_iter 810 function. 811 It 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 . 820 The first argument is a pointer to an argument that the user specifies. 821 The second argument is a pointer to the 822 .Vt struct ps_prochandle 823 that the callback was passed to. 824 The third argument is the address of the environment variable in the process. 825 The fourth argument is the environment variable. 826 Values in the environment follow the convention of the form 827 .Em variable=value . 828 For more information on environment variables see 829 .Xr exec 2 830 and 831 .Xr environ 5 . 832 For additional information on using this type, see 833 .Xr Penv_iter 3PROC . 834 .Pp 835 .Vt proc_sym_f 836 .Pp 837 The 838 .Vt proc_sym_f 839 is 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 , 843 and 844 .Fn Psymbol_iter_by_lmid 845 functions. 846 It 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 . 854 The first argument is a pointer to an argument that the user supplies. 855 The second argument is a pointer to the ELF symbol information in a 856 32-bit and 64-bit neutral form. 857 See 858 .Xr elf 3ELF 859 and 860 .Xr gelf 3ELF 861 for more information on it. 862 The final argument points to a character string that has the name of the symbol. 863 For 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 , 867 and 868 .Xr Psymbol_iter_by_lmid 3PROC . 869 .Pp 870 .Vt proc_xsym_f 871 .Pp 872 The 873 .Vt proc_xsym_f 874 is a function pointer type that is used with the 875 .Fn Pxsymbol_iter 876 function. 877 It 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 . 886 The first three arguments are identical to those of 887 .Vt proc_sym_f . 888 The final argument contains additional information about the symbol 889 itself. 890 The members of the 891 .Vt prsyminfo_t 892 are defined earlier in this section. 893 For additional information on using this type, see 894 .Xr Pxsymbol_iter 3PROC . 895 .Pp 896 .Vt proc_stack_f 897 .Pp 898 The 899 .Vt proc_stack_f 900 is a function pointer type that is used with the 901 .Fn Pstack_iter 902 function. 903 It 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 . 912 The first argument is a pointer to an argument that the user specifies. 913 The second argument's contents are platform specific. 914 The registers that contain stack information, usually the stack pointer and 915 frame pointer, will be filled in to point to an entry. 916 The 917 .Vt prgregset_t 918 is defined in 919 .Xr proc 4 . 920 .Pp 921 The third argument contains the number of arguments to the current stack 922 frame and the fourth argument contains an array of addresses that 923 correspond to the arguments to that stack function. 924 The value of the third argument dictates the number of entries in the fourth 925 argument. 926 For additional information on using this type, see 927 .Xr Pstack_iter 3PROC . 928 .Pp 929 .Vt proc_fdinfo_f 930 .Pp 931 The 932 .Vt proc_fdinfo_f 933 is a function pointer type that is used with the 934 .Fn Pfdinfo_iter 935 function. 936 It is defined as 937 .Sy typedef 938 .Ft int 939 .Fo proc_fdinfo_f 940 .Fa "void *" 941 .Fa "prfdinfo_t *" 942 .Fc . 943 The first argument is a pointer to an argument that the user specifies. 944 The second argument contains information about an open file descriptor. 945 The members of the 946 .Vt prfdinfo_t 947 are defined earlier in this section. 948 For additional information on using this type, see 949 .Xr Pfdinfo_iter 3PROC . 950 .Sh PROGRAMMING NOTES 951 When working with live processes, whether from the 952 .Xr Pgrab 3PROC 953 or 954 .Xr Pcreate 3PROC 955 family of functions, there are some additional considerations. 956 Importantly, if a process calls any of the 957 .Xr exec 2 958 suite of functions, much of the state information that is obtained, 959 particularly that about mappings in the process will be invalid. 960 Callers must ensure that they call 961 .Xr Preset_maps 3PROC 962 when they hold a process handle across an exec. 963 In addition, users of the library should familiarize themselves with the 964 .Sy PROGRAMMING NOTES 965 section of the 966 .Xr proc 4 967 manual page, which discusses issues of privileges and security. 968 .Sh DEBUGGING 969 The library provides a means for obtaining additional debugging 970 information. 971 The output itself is not part of the 972 .Nm 973 library's stable interface. 974 Setting the environment variable 975 .Ev LIBPROC_DEBUG 976 to some value will print information to standard error. 977 For example, 978 .Ev LIBPROC_DEBUG Ns = Ns Em please . 979 .Sh LOCKING 980 Most functions operate on a handle to a process in the form of a 981 .Vt "struct ps_prochandle *" . 982 Unless otherwise indicated, the library does not provide any 983 synchronization for different routines that are operating on the 984 .Sy same 985 .Nm 986 library handle. 987 It is up to the caller to ensure that only a single thread is using a handle at 988 any given time. 989 Multiple threads may call 990 .Nm 991 library routines at the same time as long as each thread is using a 992 different handle. 993 .Pp 994 Each individual function notes its 995 .Sy MT-Level 996 section. 997 The MT-Level of a routine that matches the above description will refer to this 998 manual page. 999 If it does not, then it refers to the standard attributes in 1000 .Xr attributes 5 . 1001 .Sh INTERFACE STABILITY 1002 .Sy Uncommitted 1003 .Pp 1004 While the library is considered an uncommitted interface, and is still 1005 evolving, changes that break compatibility have been uncommon and this 1006 trend is expected to continue. 1007 It is documented to allow consumers, whether part of illumos or outside of it, 1008 to understand the libarary and make use of it with the understanding that 1009 changes 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