1 LIBPROC(3LIB) Interface Libraries LIBPROC(3LIB)
2
3 NAME
4 libproc - process control library
5
6 SYNOPSIS
7 Process Control Library (libproc, -lproc)
8 #include <libproc.h>
9
10 DESCRIPTION
11 The libproc library provides consumers a general series of interfaces to
12 inspect and control both live processes and core files. It is intended
13 for introspection tools such as debuggers by providing a high-level
14 interface to the /proc file system (proc(5)).
15
16 The libproc library provides interfaces that focus on:
17
18 o Creating and attaching to live process, core files, and
19 arbitrary ELF objects.
20
21 o Interrogating the state of a process or core file.
22
23 o Manipulating the current state of a process or thread.
24
25 o Interrogating the state of threads of a process or core file.
26
27 o Running system calls in the context of another process.
28
29 o Various utilities for iterating process and core file file
30 descriptors, mappings, symbols, and more.
31
32 o Various utilities to support debugging tools.
33
34 Live Processes
35 The libproc library can be used to manipulate running processes and to
36 create new ones. To manipulate an existing process first grab it with
37 the Pgrab() function. A process is generally stopped as a side effect of
38 grabbing it. Callers must exercise caution, as if they do not use the
39 library correctly, or they terminate unexpectedly, a process may remain
40 stopped.
41
42 Unprivileged users may only grab their own processes. Users with the
43 privilege {PRIV_PROC_OWNER} may manipulate processes that they do not
44 own; however, additional restrictions as described in privileges(7)
45 apply.
46
47 In addition, the Pcreate() and Pxcreate() functions may be used to create
48 processes which are always controlled by the library.
49
50 Core Files
51 The libproc library has the ability to open and interpret core files
52 produced by processes on the system. Process core dump generation is
53 controlled by the coreadm(8) command. In addition, the library has the
54 ability to understand and interpret core dumps generated by Linux kernel
55 and can provide a subset of its functionality on such core files,
56 provided the original binary is also present.
57
58 Not all functions in the libproc library are valid for core files. In
59 general, none of the commands which manipulate the current state of a
60 process or thread or that try to force system calls on a victim process
61 will work. Furthermore several of the information and iteration
62 interfaces are limited based on the data that is available in the core
63 file. For example, if the core file is of a process that omits the frame
64 pointer, the ability to iterate the stack will be limited.
65
66 Use the Pgrab_core() or Pfgrab_core() function to open a core file. Use
67 the Pgrab_file() function to open an ELF object file. This is useful for
68 obtaining information stored in ELF headers and sections.
69
70 Debug Information
71 Many of the operations in the library rely on debug information being
72 present in a process and its associated libraries. The library leverages
73 symbol table information, CTF data (ctf(5)) sections, and frame unwinding
74 information based on the use of an ABI defined frame pointer, e.g. %ebp
75 and %rbp on x86 systems.
76
77 Some software providers strip programs of this information or build their
78 executables such that the information will not be present in a core dump.
79 To deal with this fact, the library is able to consume information that
80 is not present in the core file or the running process. It can both
81 consume it from the underlying executable and it also supports finding it
82 from related ELF objects that are linked to it via the .gnu_debuglink and
83 the .note.gnu.build-id ELF sections.
84
85 Iteration Interfaces
86 The libproc library provides the ability to iterate over the following
87 aspects of a process or core file:
88
89 o Active threads
90
91 o Active and zombie threads
92
93 o All non-system processes
94
95 o All process mappings
96
97 o All objects in a process
98
99 o The environment
100
101 o The symbol table
102
103 o Stack frames
104
105 o File Descriptors
106
107 System Call Injection
108 The libproc library allows the caller to force system calls to be
109 executed in the context of the running process. This can be used both as
110 a tool for introspection, allowing one to get information outside its
111 current context as well as performing modifications to a process.
112
113 These functions run in the context of the calling process. This is often
114 an easier way of getting non-exported information about a process from
115 the system. For example, the pfiles(1) command uses this interface to
116 get more detailed information about a process's open file descriptors,
117 which it would not have access to otherwise.
118
119 INTERFACES
120 The shared object libproc.so.1 provides the public interfaces defined
121 below. See Intro(3) for additional information on shared object
122 interfaces. Functions are organized into categories that describe their
123 purpose. Individual functions are documented in their own manual pages.
124
125 Creation, Grabbing, and Releasing
126 The following routines are related to creating library handles, grabbing
127 cores, processes, and threads, and releasing those resources.
128
129 Lfree Lgrab
130 Lgrab_error Pcreate
131 Pcreate_agent Pcreate_callback
132 Pcreate_error Pdestroy_agent
133 Pfgrab_core Pfree
134 Pgrab Pgrab_core
135 Pgrab_error Pgrab_file
136 Pgrab_ops Prelease
137 Preopen Pxcreate
138
139 Process interrogation and manipulation
140 The following routines obtain information about a process and allow
141 manipulation of the process itself.
142
143 Paddr_to_ctf Paddr_to_loadobj
144 Paddr_to_map Paddr_to_text_map
145 Pasfd Pclearfault
146 Pclearsig Pcontent
147 Pcred Pctlfd
148 Pdelbkpt Pdelwapt
149 Pdstop Pexecname
150 Pfault Pfgcore
151 Pgcore Pgetareg
152 Pgetauxval Pgetauxvec
153 Pgetenv Pisprocdir
154 Pissyscall_prev Plmid
155 Plmid_to_loadobj Plmid_to_map
156 Plookup_by_addr Plookup_by_name
157 Pname_to_ctf Pname_to_loadobj
158 Pname_to_map Pobjname
159 Pobjname_resolved Pplatform
160 Ppltdest Ppriv
161 Ppsinfo Pputareg
162 Prd_agent Pread
163 Pread_string Preset_maps
164 Psetbkpt Psecflags
165 Psetcred Psetfault
166 Psetflags Psetpriv
167 Psetrun Psetsignal
168 Psetsysentry Psetsysexit
169 Psetwapt Psetzoneid
170 Psignal Pstate
171 Pstatus Pstop
172 Pstopstatus Psync
173 Psysentry Psysexit
174 Puname Pupanic
175 Pupanic_free Punsetflags
176 Pupdate_maps Pupdate_syms
177 Pwait Pwrite
178 Pxecbkpt Pxecwapt
179 Pxlookup_by_addr Pxlookup_by_addr_resolved
180 Pxlookup_by_name Pzonename
181 Pzonepath Pzoneroot
182
183 Thread interrogation and manipulation
184 The following routines obtain information about a thread and allow
185 manipulation of the thread itself.
186
187 Lalt_stack Lclearfault
188 Lclearsig Lctlfd
189 Ldstop Lgetareg
190 Lgetfpregs Lgetregs
191 Lgetxregs Lmain_stack
192 Lprochandle Lpsinfo
193 Lputareg Lsetrun
194 Lsetfpregs Lsetregs
195 Lsetxregs Lstack
196 Lstate Lstatus
197 Lstop Lsync
198 Lwait Lxecbkpt
199 Lxecwapt
200
201 Plwp_alt_stack Plwp_freexregs
202 Plwp_getfpregs Plwp_getname
203 Plwp_getpsinfo Plwp_getregs
204 Plwp_getspymaster Plwp_main_stack
205 Plwp_getxregs Plwp_setfpregs
206 Plwp_setregs Plwp_setxregs
207 Plwp_stack
208
209 System Call Injection
210 The following routines are used to inject specific system calls and have
211 them run in the context of a process.
212
213 pr_access pr_close
214 pr_creat pr_door_info
215 pr_exit pr_fcntl
216 pr_fstat pr_fstat64
217 pr_fstatvfs pr_getitimer
218 pr_getpeername pr_getpeerucred
219 pr_getprojid pr_getrctl
220 pr_getrlimit pr_getrlimit64
221 pr_getsockname pr_getsockopt
222 pr_gettaskid pr_getzoneid
223 pr_ioctl pr_link
224 pr_llseek pr_lseek
225 pr_lstat pr_lstat64
226 pr_memcntl pr_meminfo
227 pr_mmap pr_munmap
228 pr_open pr_processor_bind
229 pr_rename pr_setitimer
230 pr_setrctl pr_setrlimit
231 pr_setrlimit64 pr_settaskid
232 pr_sigaction pr_stat
233 pr_stat64 pr_statvfs
234 pr_unlink pr_waitid
235
236 Iteration routines
237 These routines are used to iterate over the contents of a process.
238
239 Penv_iter Plwp_iter
240 Plwp_iter_all Pmapping_iter
241 Pmapping_iter_resolved Pobject_iter
242 Pobject_iter_resolved Pstack_iter
243 Psymbol_iter Psymbol_iter_by_addr
244 Psymbol_iter_by_lmid Psymbol_iter_by_name
245 Pxsymbol_iter Pfdinfo_iter
246
247 Utility routines
248 The following routines are utilities that are useful to consumers of the
249 library.
250
251 Perror_printf proc_arg_grab
252 proc_arg_psinfo proc_arg_xgrab
253 proc_arg_xpsinfo proc_content2str
254 proc_dmodelname proc_finistdio
255 proc_fltname proc_fltset2str
256 proc_flushstdio proc_get_auxv
257 proc_fdinfo_misc proc_get_cred
258 proc_get_fdinfo proc_get_lwpsinfo
259 proc_get_priv proc_get_psinfo
260 proc_get_status proc_get_initstdio
261 proc_lwp_in_set proc_lwp_range_valid
262 proc_signame proc_sigset2str
263 proc_str2content proc_str2flt
264 proc_str2fltset proc_str2sig
265 proc_str2sigset proc_str2sys
266 proc_str2sysset proc_sysname
267 proc_sysset2str proc_unctrl_psinfo
268
269 x86 Specific Routines
270 The following routines are specific to the x86, 32-bit and 64-bit,
271 versions of the libproc library.
272
273 Pldt proc_get_ldt
274
275 SPARC specific Routines
276 The following functions are specific to the SPARC, 32-bit and 64-bit,
277 versions of the libproc library.
278
279 Plwp_getgwindows
280
281 The following functions are specific to the 64-bit SPARC version of the
282 libproc library.
283
284 Plwp_getasrs Plwp_setasrs
285
286 PROCESS STATES
287 Every process handle that exists in libproc has a state. In some cases,
288 such as for core files, these states are static. In other cases, such as
289 handles that correspond to a running process or a created process, these
290 states are dynamic and change based on actions taken in the library. The
291 state can be obtained with the Pstate(3PROC) function.
292
293 The various states are:
294
295 PS_RUN An actively running process. This may be a process
296 that was obtained by creating it with functions such
297 as Pcreate(3PROC) or by grabbing an existing process
298 such as Pgrab(3PROC).
299
300 PS_STOP An active process that is no longer executing. A
301 process may stop for many reasons such as an explicit
302 stop request (through pstop(1) for example) or if a
303 tracing event is hit.
304
305 The reason a process is stopped may be obtained
306 through the thread's lwpstatus_t structure read
307 directly from /proc or obtained through the
308 Lstatus(3PROC) function.
309
310 PS_LOST Control over the process has been lost. This may
311 happen when the process executes a new image
312 requiring a different set of privileges. To resume
313 control call Preopen(3PROC). For more information on
314 losing control of a process, see proc(5).
315
316 PS_UNDEAD A zombie process. It has terminated, but it has not
317 been cleaned up yet by its parent. For more on the
318 conditions of becoming a zombie, see exec(2).
319
320 PS_DEAD Processes in this state are always core files. See
321 the earlier section Core Files for more information
322 on working with core files.
323
324 PS_IDLE A process that has never been run. This is always
325 the case for handles that refer to files as the files
326 cannot be executed. Those process handles are
327 obtained through calling Pgrab_file(3PROC).
328
329 Many functions relating to tracing processes, for example Psignal(3PROC),
330 Psetsignal(3PROC), Psetfault(3PROC), Psysentry(3PROC), and others,
331 mention that they only act upon Active Processes. This specifically
332 refers to processes whose state are in PS_RUN and PS_STOP. Process
333 handles in the other states have no notion of settable tracing flags,
334 though core files (type PS_DEAD) may have a read-only snapshot of their
335 tracing settings available.
336
337 TYPES
338 The libproc library uses many types that come from the /proc file system
339 (proc(5)) and the ELF format (elf(3ELF)). However, it also defines the
340 following types:
341
342 struct ps_prochandle
343
344 The struct ps_prochandle is an opaque handle to the library and the core
345 element of control for a process. Consumers obtain pointers to a handle
346 through the use of the Pcreate(), Pgrab(), and related functions. When a
347 caller is done with a handle, then it should call one of the Pfree() and
348 Prelease() functions to relinquish the handle, release associated
349 resources, and potentially set the process to run again.
350
351 struct ps_lwphandle
352
353 The struct ps_lwphandle is analogous to the struct ps_prochandle, but it
354 represents the control of an individual thread, rather than a process.
355 Consumers obtain pointers to a handle through the Lgrab() function and
356 relinquish it with the Lfree() function.
357
358 core_content_t
359
360 The core_content_t is a value which describes the various content types
361 of core files. These are used in functions such as Pcontent(3PROC) and
362 Pgcore(3PROC) to describe and control the types of content that get
363 included. Various content types may be included together through a
364 bitwise-inclusive-OR. The default system core contents are controlled
365 with the coreadm(8) tool. The following table lists the current set of
366 core contents in the system, though the set may increase over time. The
367 string after the macro is the human readable string that corresponds with
368 the constant and is used by coreadm(8), proc_content2str(3PROC), and
369 proc_str2content(3PROC).
370
371 CC_CONTENT_STACK ("stack")
372 The contents include the process stack. Note, this only
373 covers the main thread's stack. The stack of other threads
374 is covered by CC_CONTENT_ANON.
375
376 CC_CONTENT_HEAP ("heap")
377 The contents include the process heap.
378
379 CC_CONTENT_SHFILE ("shfile")
380 The contents include shared mappings that are backed by
381 files (e.g. mapped through mmap(2) with the MAP_SHARED
382 flag).
383
384 CC_CONTENT_SHANNON ("shannon")
385 The contents include shared mappings that are backed by
386 anonymous memory (e.g. mapped through mmap(2) with the
387 MAP_SHARED and MAP_ANON flags).
388
389 CC_CONTENT_RODATA ("rodata")
390 The contents include private read-only file mappings, such
391 as shared library text.
392
393 CC_CONTENT_ANON ("anon")
394 The contents include private anonymous mappings. This
395 includes the stacks of threads which are not the main
396 thread.
397
398 CC_CONTENT_SHM ("shm")
399 The contents include system V shared memory.
400
401 CC_CONTENT_ISM ("ism")
402 The contents include ISM (intimate shared memory) mappings.
403
404 CC_CONTENT_DISM ("dism")
405 The contents include DISM (dynamic shared memory) mappings.
406
407 CC_CONTENT_CTF ("ctf")
408 The contents include ctf(5) (Compact C Type Format)
409 information. Note, not all objects in the process may have
410 CTF information available.
411
412 CC_CONTENT_SYMTAB ("symtab")
413 The contents include the symbol table. Note, not all
414 objects in the process may have a symbol table available.
415
416 CC_CONTENT_ALL ("all")
417 This value indicates that all of the above content values
418 are present. Note that additional values may be added in
419 the future, in which case the value of the symbol will be
420 updated to include them. Comparisons with CC_CONTENT_ALL
421 should validate all the expected bits are set by an
422 expression such as (c & CC_CONTENT_ALL) == CC_CONTENT_ALL.
423
424 CC_CONTENT_NONE ("none")
425 This value indicates that there is no content present.
426
427 CC_CONTENT_DEFAULT ("default")
428 The content includes the following set of default values:
429 CC_CONTENT_STACK, CC_CONTENT_HEAP, CC_CONTENT_ISM,
430 CC_CONTENT_DISM, CC_CONTENT_SHM, CC_CONTENT_SHANON,
431 CC_CONTENT_TEXT, CC_CONTENT_DATA, CC_CONTENT_RODATA,
432 CC_CONTENT_ANON, CC_CONTENT_CTF, and CC_CONTENT_SYMTAB.
433 Note that the default may change. Comparisons with
434 CC_CONTENT_DEFAULT should validate that all of the expected
435 bits are set with an expression such as
436 (c & CC_CONTENT_DEFAULT) == CC_CONTENT_DEFAULT.
437
438 CC_CONTENT_INVALID
439 This indicates that the contents are invalid.
440
441 prfdinfo_t
442
443 The prfdinfo_t structure is used with the Pfdinfo_iter(), proc_fdwalk(),
444 proc_fdinfowalk() and proc_get_fdinfo() functions and describes
445 information about a file descriptor. The structure is defined as
446 follows:
447
448 typedef struct prfdinfo {
449 int pr_fd; /* file descriptor number */
450 mode_t pr_mode; /* (see st_mode in stat(2)) */
451 ino64_t pr_ino; /* inode number */
452 off64_t pr_size; /* file size */
453 off64_t pr_offset; /* current offset */
454 uid_t pr_uid; /* owner's user id */
455 gid_t pr_gid; /* owner's group id */
456 major_t pr_major; /* major number of device */
457 minor_t pr_minor; /* minor number of device */
458 major_t pr_rmajor; /* major number (if special file) */
459 minor_t pr_rminor; /* minor number (if special file) */
460 int pr_fileflags; /* (see F_GETXFL in fcntl(2)) */
461 int pr_fdflags; /* (see F_GETFD in fcntl(2)) */
462 short pr_locktype; /* (see F_GETLK in fcntl(2)) */
463 pid_t pr_lockpid; /* process holding file lock */
464 int pr_locksysid; /* sysid of locking process */
465 pid_t pr_peerpid; /* peer process (socket, door) */
466 int pr_filler[25]; /* reserved for future use */
467 char pr_peername[PRFNSZ]; /* peer process name */
468 #if __STDC_VERSION__ >= 199901L
469 uint8_t pr_misc[]; /* self describing structures */
470 else
471 uint8_t pr_misc[1]; /* self describing structures */
472 #endif
473 } prfdinfo_t;
474
475 The structure has similar information to that found in the stat structure
476 that's used as part of the stat family of system calls, defined in
477 stat(2). The member pr_fd contains the number of the file descriptor of
478 the file. The members pr_mode, pr_uid, pr_gid, pr_ino, and pr_size are
479 the same as the members st_mode, st_uid, st_gid, st_ino, and st_size in
480 the stat structure.
481
482 The pr_major and pr_minor members contain the major and minor numbers of
483 the device containing the directory for this file. This is similar to
484 the st_dev member of the stat structure, except that it is broken out
485 into its major and minor components. The pr_rmajor and pr_rminor members
486 are similar in spirit to pr_major and pr_minor; however, they are
487 equivalent to the st_rdev member of the stat structure and thus have
488 meaning for special character and block files.
489
490 The pr_offset member contains the current seek offset of the file
491 descriptor. The pr_fileflags and pr_fdflags members contain the flags
492 that would have been returned by a call to fcntl(2) with the arguments
493 F_GETXFL and F_GETFD respectively.
494
495 The pr_locktype, pr_lockpid, and pr_locksysid contain the information
496 that would have been returned by a call to fcntl(2) with an argument of
497 F_GETLK.
498
499 The pr_peerpid and pr_peername members contain the process ID and name of
500 any peer endpoint of a connection-oriented socket or stream fd. This
501 information is the same as that which would be returned by a call to
502 getpeerucred(3C)
503
504 The pr_misc member contains miscellaneous additional data relating to the
505 file descriptor. The format of these data is described in proc(5).
506
507 prsyminfo_t
508
509 The prsyminfo_t structure is used with the various symbol look up
510 functions Pxlookup_by_name(), Pxlookup_by_addr(), and
511 Pxlookup_by_addr_resolved() which describes additional information about
512 a symbol. The structure is defined as follows:
513
514 typedef struct prsyminfo {
515 const char *prs_object; /* object name */
516 const char *prs_name; /* symbol name */
517 Lmid_t prs_lmid; /* link map id */
518 uint_t prs_id; /* symbol id */
519 uint_t prs_table; /* symbol table id */
520 } prsyminfo_t;
521
522 The member prs_object points to a string that contains the name of the
523 object file, if known, that the symbol comes from. The member prs_name
524 points to the name of the symbol, if known. This may be unknown due to a
525 stripped binary that contains no symbol table. The member prs_lmid
526 indicates the link map identifier that the symbol was found on. For more
527 information on link map identifiers refer to the Linker and Libraries
528 Guide and dlopen(3C).
529
530 The members prs_id and prs_table can be used to determine both the symbol
531 table that the entry came from and which entry in the table it
532 corresponds to. If the value of prs_table is PR_SYMTAB then it came from
533 the ELF standard symbol table. However, if it is instead PR_DYNSYM, then
534 that indicates that it comes from the process's dynamic section.
535
536 proc_lwp_f
537
538 The proc_lwp_f is a function pointer type that is used with the
539 Plwp_iter() function. It is defined as typedef int proc_lwp_f(void *,
540 const lwpstatus_t *). The first argument is a pointer to an argument
541 that the user specifies, while the second has the thread's status
542 information and is defined in proc(5). For additional information on
543 using this type, see Plwp_iter(3PROC).
544
545 proc_lwp_all_f
546
547 The proc_lwp_all_f is a function pointer type that is used with the
548 Plwp_iter_all() function. It is defined as typedef int
549 proc_lwp_all_f(void *, const lwpstatus_t *, const lwpsinfo_t *). The
550 first argument is a pointer to an argument that the user specifies. The
551 second and third arguments contain the thread's status and thread-
552 specific ps(1) information respectively. Both structures are defined in
553 proc(5). For additional information on using this type, see
554 Plwp_iter_all(3PROC).
555
556 proc_fdinfowalk_f
557
558 The proc_fdinfowalk_f is a function pointer type that is used with the
559 proc_fdinfowalk() function to walk the miscellaneous data items contained
560 within a prfdinfo_t structure. It is defined as typedef int
561 proc_fdinfowalk_f(uint_t, const void *, size_t, void *). The first
562 argument contains the type of the miscellaneous information being
563 presented, the second and third provide a pointer to the associated data
564 and the length of that data. The final argument is a pointer to an
565 argument that the user specifies. For more information on using this,
566 see proc_fdinfowalk(3PROC).
567
568 proc_fdwalk_f
569
570 The proc_fdwalk_f is a function pointer type that is used with the
571 proc_fdwalk() function. It is defined as typedef int
572 proc_fdwalk_f(const prfdinfo_t *, void *). The first argument contains
573 the file descriptor information. The prfdinfo_t structure is defined in
574 proc(5). The final argument is a pointer to an argument that the user
575 specifies. For more information on using this, see proc_fdwalk(3PROC).
576
577 proc_walk_f
578
579 The proc_walk_f is a function pointer type that is used with the
580 proc_walk() function. It is defined as typedef int
581 proc_walk_f(psinfo_t *, lwpsinfo_t *, void *). The first argument
582 contains the process ps(1) information and the second argument contains
583 the representative thread's ps(1) information. Both structures are
584 defined in proc(5). The final argument is a pointer to an argument that
585 the user specifies. For more information on using this, see
586 proc_walk(3PROC).
587
588 proc_map_f
589
590 The proc_map_f is a function pointer type that is used with the
591 Pmapping_iter(), Pmapping_iter_resolved(), Pobject_iter(), and
592 Pobject_iter_resolved() functions. It is defined as typedef int
593 proc_map_f(void *, const prmap_t *, const char *). The first argument is
594 a pointer to an argument that the user specifies. The second argument is
595 describes the mapping information and is defined in proc(5). The final
596 argument contains the name of the mapping or object file in question.
597 For additional information on using this type, see Pmapping_iter(3PROC).
598
599 proc_env_f
600
601 The proc_env_f is a function pointer type that is used with the
602 Penv_iter() function. It is defined as typedef int proc_env_f(void *,
603 struct ps_prochandle *, uintptr_t, const char *). The first argument is
604 a pointer to an argument that the user specifies. The second argument is
605 a pointer to the struct ps_prochandle that the callback was passed to.
606 The third argument is the address of the environment variable in the
607 process. The fourth argument is the environment variable. Values in the
608 environment follow the convention of the form variable=value. For more
609 information on environment variables see exec(2) and environ(7). For
610 additional information on using this type, see Penv_iter(3PROC).
611
612 proc_sym_f
613
614 The proc_sym_f is a function pointer type that is used with the
615 Psmbol_iter(), Psymbol_iter_by_addr(), Psymbol_iter_by_name(), and
616 Psymbol_iter_by_lmid() functions. It is defined as typedef int
617 proc_sym_f(void *, const GElf_Sym *, const char *). The first argument
618 is a pointer to an argument that the user supplies. The second argument
619 is a pointer to the ELF symbol information in a 32-bit and 64-bit neutral
620 form. See elf(3ELF) and gelf(3ELF) for more information on it. The
621 final argument points to a character string that has the name of the
622 symbol. For additional information on using this type, see
623 Psymbol_iter(3PROC), Psymbol_iter_by_addr(3PROC),
624 Psymbol_iter_by_name(3PROC), and Psymbol_iter_by_lmid(3PROC).
625
626 proc_xsym_f
627
628 The proc_xsym_f is a function pointer type that is used with the
629 Pxsymbol_iter() function. It is defined as typedef int
630 proc_xsym_f(void *, const GElf_Sym *, const char *, const prsyminfo_t *).
631 The first three arguments are identical to those of proc_sym_f. The
632 final argument contains additional information about the symbol itself.
633 The members of the prsyminfo_t are defined earlier in this section. For
634 additional information on using this type, see Pxsymbol_iter(3PROC).
635
636 proc_stack_f
637
638 The proc_stack_f is a function pointer type that is used with the
639 Pstack_iter() function. It is defined as typedef int
640 proc_stack_f(void *, prgregset_t, uint_t, const long *). The first
641 argument is a pointer to an argument that the user specifies. The second
642 argument's contents are platform specific. The registers that contain
643 stack information, usually the stack pointer and frame pointer, will be
644 filled in to point to an entry. The prgregset_t is defined in proc(5).
645
646 The third argument contains the number of arguments to the current stack
647 frame and the fourth argument contains an array of addresses that
648 correspond to the arguments to that stack function. The value of the
649 third argument dictates the number of entries in the fourth argument.
650 For additional information on using this type, see Pstack_iter(3PROC).
651
652 proc_fdinfo_f
653
654 The proc_fdinfo_f is a function pointer type that is used with the
655 Pfdinfo_iter() function. It is defined as typedef int
656 proc_fdinfo_f(void *, prfdinfo_t *). The first argument is a pointer to
657 an argument that the user specifies. The second argument contains
658 information about an open file descriptor. The members of the prfdinfo_t
659 are defined earlier in this section. For additional information on using
660 this type, see Pfdinfo_iter(3PROC).
661
662 PROGRAMMING NOTES
663 When working with live processes, whether from the Pgrab(3PROC) or
664 Pcreate(3PROC) family of functions, there are some additional
665 considerations. Importantly, if a process calls any of the exec(2) suite
666 of functions, much of the state information that is obtained,
667 particularly that about mappings in the process will be invalid. Callers
668 must ensure that they call Preset_maps(3PROC) when they hold a process
669 handle across an exec. In addition, users of the library should
670 familiarize themselves with the PROGRAMMING NOTES section of the proc(5)
671 manual page, which discusses issues of privileges and security.
672
673 DEBUGGING
674 The library provides a means for obtaining additional debugging
675 information. The output itself is not part of the libproc library's
676 stable interface. Setting the environment variable LIBPROC_DEBUG to some
677 value will print information to standard error. For example,
678 LIBPROC_DEBUG=please.
679
680 LOCKING
681 Most functions operate on a handle to a process in the form of a struct
682 ps_prochandle *. Unless otherwise indicated, the library does not
683 provide any synchronization for different routines that are operating on
684 the same libproc library handle. It is up to the caller to ensure that
685 only a single thread is using a handle at any given time. Multiple
686 threads may call libproc library routines at the same time as long as
687 each thread is using a different handle.
688
689 Each individual function notes its MT-Level section. The MT-Level of a
690 routine that matches the above description will refer to this manual
691 page. If it does not, then it refers to the standard attributes in
692 attributes(7).
693
694 INTERFACE STABILITY
695 Uncommitted
696
697 While the library is considered an uncommitted interface, and is still
698 evolving, changes that break compatibility have been uncommon and this
699 trend is expected to continue. It is documented to allow consumers,
700 whether part of illumos or outside of it, to understand the library and
701 make use of it with the understanding that changes may occur which break
702 both source and binary compatibility.
703
704 SEE ALSO
705 gcore(1), mdb(1), proc(1), ps(1), exec(2), fcntl(2), stat(2), Intro(3),
706 dlopen(3C), elf(3ELF), ctf(5), proc(5), attributes(7), environ(7),
707 privileges(7), coreadm(8)
708
709
710 Linkers and Libraries Guide.
711
712 Lfree(3PROC), Lgrab(3PROC), Lgrab_error(3PROC), Pcreate(3PROC),
713 Pcreate_agent(3PROC), Pcreate_callback(3PROC), Pcreate_error(3PROC),
714 Pdestroy_agent(3PROC), Pfgrab_core(3PROC), Pfree(3PROC), Pgrab(3PROC),
715 Pgrab_core(3PROC), Pgrab_error(3PROC), Pgrab_file(3PROC),
716 Pgrab_ops(3PROC), Prelease(3PROC), Preopen(3PROC), Pxcreate(3PROC)
717
718 Paddr_to_ctf(3PROC), Paddr_to_loadobj(3PROC), Paddr_to_map(3PROC),
719 Paddr_to_text_map(3PROC), Pasfd(3PROC), Pclearfault(3PROC),
720 Pclearsig(3PROC), Pcontent(3PROC), Pcred(3PROC), Pctlfd(3PROC),
721 Pdelbkpt(3PROC), Pdelwapt(3PROC), Pdstop(3PROC), Pexecname(3PROC),
722 Pfault(3PROC), Pfgcore(3PROC), Pgcore(3PROC), Pgetareg(3PROC),
723 Pgetauxval(3PROC), Pgetauxvec(3PROC), Pgetenv(3PROC), Pisprocdir(3PROC),
724 Pissyscall_prev(3PROC), Plmid(3PROC), Plmid_to_loadobj(3PROC),
725 Plmid_to_map(3PROC), Plookup_by_addr(3PROC), Plookup_by_name(3PROC),
726 Plwp_alt_stack(3PROC), Plwp_getfpregs(3PROC), Plwp_getpsinfo(3PROC),
727 Plwp_getregs(3PROC), Plwp_getspymaster(3PROC), Plwp_main_stack(3PROC),
728 Plwp_setfpregs(3PROC), Plwp_setregs(3PROC), Plwp_stack(3PROC),
729 Pname_to_ctf(3PROC), Pname_to_loadobj(3PROC), Pname_to_map(3PROC),
730 Pobjname(3PROC), Pobjname_resolved(3PROC), Pplatform(3PROC),
731 Ppltdest(3PROC), Ppriv(3PROC), Ppsinfo(3PROC), Pputareg(3PROC),
732 Prd_agent(3PROC), Pread(3PROC), Pread_string(3PROC), Preset_maps(3PROC),
733 Psecflags(3PROC), Psetbkpt(3PROC), Psetcred(3PROC), Psetfault(3PROC),
734 Psetflags(3PROC), Psetpriv(3PROC), Psetrun(3PROC), Psetsignal(3PROC),
735 Psetsysentry(3PROC), Psetsysexit(3PROC), Psetwapt(3PROC),
736 Psetzoneid(3PROC), Psignal(3PROC), Pstate(3PROC), Pstatus(3PROC),
737 Pstop(3PROC), Pstopstatus(3PROC), Psync(3PROC), Psysentry(3PROC),
738 Psysexit(3PROC), Puname(3PROC), Pupanic(3PROC), Pupanic_free(3PROC),
739 Punsetflags(3PROC), Pupdate_maps(3PROC), Pupdate_syms(3PROC),
740 Pwait(3PROC), Pwrite(3PROC), Pxecbkpt(3PROC), Pxecwapt(3PROC),
741 Pxlookup_by_addr(3PROC), Pxlookup_by_addr_resolved(3PROC),
742 Pxlookup_by_name(3PROC), Pzonename(3PROC), Pzonepath(3PROC),
743 Pzoneroot(3PROC)
744
745 Lalt_stack(3PROC), Lclearfault(3PROC), Lclearsig(3PROC), Lctlfd(3PROC),
746 Ldstop(3PROC), Lgetareg(3PROC), Lmain_stack(3PROC), Lprochandle(3PROC),
747 Lpsinfo(3PROC), Lputareg(3PROC), Lsetrun(3PROC), Lstack(3PROC),
748 Lstate(3PROC), Lstatus(3PROC), Lstop(3PROC), Lsync(3PROC), Lwait(3PROC),
749 Lxecbkpt(3PROC), Lxecwapt(3PROC)
750
751 pr_access(3PROC), pr_close(3PROC), pr_creat(3PROC), pr_door_info(3PROC),
752 pr_exit(3PROC), pr_fcntl(3PROC), pr_fstat(3PROC), pr_fstat64(3PROC),
753 pr_fstatvfs(3PROC), pr_getitimer(3PROC), pr_getpeername(3PROC),
754 pr_getpeerucred(3PROC), pr_getprojid(3PROC), pr_getrctl(3PROC),
755 pr_getrlimit(3PROC), pr_getrlimit64(3PROC), pr_getsockname(3PROC),
756 pr_getsockopt(3PROC), pr_gettaskid(3PROC), pr_getzoneid(3PROC),
757 pr_ioctl(3PROC), pr_link(3PROC), pr_llseek(3PROC), pr_lseek(3PROC),
758 pr_lstat(3PROC), pr_lstat64(3PROC), pr_memcntl(3PROC), pr_meminfo(3PROC),
759 pr_mmap(3PROC), pr_munmap(3PROC), pr_open(3PROC),
760 pr_processor_bind(3PROC), pr_rename(3PROC), pr_setitimer(3PROC),
761 pr_setrctl(3PROC), pr_setrlimit(3PROC), pr_setrlimit64(3PROC),
762 pr_settaskid(3PROC), pr_sigaction(3PROC), pr_stat(3PROC),
763 pr_stat64(3PROC), pr_statvfs(3PROC), pr_unlink(3PROC), pr_waitid(3PROC),
764
765 Penv_iter(3PROC), Plwp_iter(3PROC), Plwp_iter_all(3PROC),
766 Pmapping_iter(3PROC), Pmapping_iter_resolved(3PROC), Pobject_iter(3PROC),
767 Pobject_iter_resolved(3PROC), Pstack_iter(3PROC), Psymbol_iter(3PROC),
768 Psymbol_iter_by_addr(3PROC), Psymbol_iter_by_lmid(3PROC),
769 Psymbol_iter_by_name(3PROC), Pxsymbol_iter(3PROC), Pfdinfo_iter(3PROC)
770
771 Perror_printf(3PROC), proc_arg_grab(3PROC), proc_arg_psinfo(3PROC),
772 proc_arg_xgrab(3PROC), proc_arg_xpsinfo(3PROC), proc_content2str(3PROC),
773 proc_dmodelname(3PROC), proc_finistdio(3PROC), proc_fltname(3PROC),
774 proc_fltset2str(3PROC), proc_flushstdio(3PROC), proc_get_auxv(3PROC),
775 proc_get_cred(3PROC), proc_get_fdinfo(3PROC), proc_get_priv(3PROC),
776 proc_get_psinfo(3PROC), proc_get_status(3PROC), proc_initstdio(3PROC),
777 proc_lwp_in_set(3PROC), proc_lwp_range_valid(3PROC), proc_signame(3PROC),
778 proc_sigset2str(3PROC), proc_str2content(3PROC), proc_str2flt(3PROC),
779 proc_str2fltset(3PROC), proc_str2sig(3PROC), proc_str2sigset(3PROC),
780 proc_str2sys(3PROC), proc_str2sysset(3PROC), proc_sysname(3PROC),
781 proc_sysset2str(3PROC), proc_unctrl_psinfo(3PROC),
782 proc_fdinfowalk(3PROC), proc_fdwalk(3PROC), proc_walk(3PROC)
783
784 Pldt(3PROC), proc_get_ldt(3PROC),
785
786 Plwp_getgwindows(3PROC), Plwp_getxregs(3PROC), Plwp_setxregs(3PROC),
787
788 Plwp_getasrs(3PROC), Plwp_setasrs(3PROC)
789
790 illumos March 20, 2023 illumos