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