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