Print this page
10229 Some man pages have incorrect cross-references
| 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(4)).
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(5)
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(1M) 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
|
↓ open down ↓ |
62 lines elided |
↑ open up ↑ |
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 - symbol table information, CTF data (CTF(4)) sections, and frame unwinding
73 + symbol table information, CTF data (ctf(4)) 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 Plwp_alt_stack Plwp_getfpregs
158 158 Plwp_getname Plwp_getpsinfo
159 159 Plwp_getregs Plwp_getspymaster
160 160 Plwp_main_stack Plwp_setfpregs
161 161 Plwp_setregs Plwp_stack
162 162 Pname_to_ctf Pname_to_loadobj
163 163 Pname_to_map Pobjname
164 164 Pobjname_resolved Pplatform
165 165 Ppltdest Ppriv
166 166 Ppsinfo Pputareg
167 167 Prd_agent Pread
168 168 Pread_string Preset_maps
169 169 Psetbkpt Psecflags
170 170 Psetcred Psetfault
171 171 Psetflags Psetpriv
172 172 Psetrun Psetsignal
173 173 Psetsysentry Psetsysexit
174 174 Psetwapt Psetzoneid
175 175 Psignal Pstate
176 176 Pstatus Pstop
177 177 Pstopstatus Psync
178 178 Psysentry Psysexit
179 179 Puname Punsetflags
180 180 Pupdate_maps Pupdate_syms
181 181 Pwait Pwrite
182 182 Pxecbkpt Pxecwapt
183 183 Pxlookup_by_addr Pxlookup_by_addr_resolved
184 184 Pxlookup_by_name Pzonename
185 185 Pzonepath Pzoneroot
186 186
187 187 Thread interrogation and manipulation
188 188 The following routines obtain information about a thread and allow
189 189 manipulation of the thread itself.
190 190
191 191 Lalt_stack Lclearfault
192 192 Lclearsig Lctlfd
193 193 Ldstop Lgetareg
194 194 Lmain_stack Lprochandle
195 195 Lpsinfo Lputareg
196 196 Lsetrun Lstack
197 197 Lstate Lstatus
198 198 Lstop Lsync
199 199 Lwait Lxecbkpt
200 200 Lxecwapt
201 201
202 202 System Call Injection
203 203 The following routines are used to inject specific system calls and have
204 204 them run in the context of a process.
205 205
206 206 pr_access pr_close
207 207 pr_creat pr_door_info
208 208 pr_exit pr_fcntl
209 209 pr_fstat pr_fstat64
210 210 pr_fstatvfs pr_getitimer
211 211 pr_getpeername pr_getpeerucred
212 212 pr_getprojid pr_getrctl
213 213 pr_getrlimit pr_getrlimit64
214 214 pr_getsockname pr_getsockopt
215 215 pr_gettaskid pr_getzoneid
216 216 pr_ioctl pr_link
217 217 pr_llseek pr_lseek
218 218 pr_lstat pr_lstat64
219 219 pr_memcntl pr_meminfo
220 220 pr_mmap pr_munmap
221 221 pr_open pr_processor_bind
222 222 pr_rename pr_setitimer
223 223 pr_setrctl pr_setrlimit
224 224 pr_setrlimit64 pr_settaskid
225 225 pr_sigaction pr_stat
226 226 pr_stat64 pr_statvfs
227 227 pr_unlink pr_waitid
228 228
229 229 Iteration routines
230 230 These routines are used to iterate over the contents of a process.
231 231
232 232 Penv_iter Plwp_iter
233 233 Plwp_iter_all Pmapping_iter
234 234 Pmapping_iter_resolved Pobject_iter
235 235 Pobject_iter_resolved Pstack_iter
236 236 Psymbol_iter Psymbol_iter_by_addr
237 237 Psymbol_iter_by_lmid Psymbol_iter_by_name
238 238 Pxsymbol_iter Pfdinfo_iter
239 239
240 240 Utility routines
241 241 The following routines are utilities that are useful to consumers of the
242 242 library.
243 243
244 244 Perror_printf proc_arg_grab
245 245 proc_arg_psinfo proc_arg_xgrab
246 246 proc_arg_xpsinfo proc_content2str
247 247 proc_finistdio proc_fltname
248 248 proc_fltset2str proc_flushstdio
249 249 proc_get_auxv proc_get_cred
250 250 proc_get_priv proc_get_psinfo
251 251 proc_get_status proc_initstdio
252 252 proc_lwp_in_set proc_lwp_range_valid
253 253 proc_signame proc_sigset2str
254 254 proc_str2content proc_str2flt
255 255 proc_str2fltset proc_str2sig
256 256 proc_str2sigset proc_str2sys
257 257 proc_str2sysset proc_sysname
258 258 proc_sysset2str proc_unctrl_psinfo
259 259 proc_walk
260 260
261 261 x86 Specific Routines
262 262 The following routines are specific to the x86, 32-bit and 64-bit,
263 263 versions of the libproc library.
264 264
265 265 Pldt proc_get_ldt
266 266
267 267 SPARC specific Routines
268 268 The following functions are specific to the SPARC, 32-bit and 64-bit,
269 269 versions of the libproc library.
270 270
271 271 Plwp_getgwindows Plwp_getxregs
272 272 Plwp_setxregs
273 273
274 274 The following functions are specific to the 64-bit SPARC version of the
275 275 libproc library.
276 276
277 277 Plwp_getasrs Plwp_setasrs
278 278
279 279 PROCESS STATES
280 280 Every process handle that exists in libproc has a state. In some cases,
281 281 such as for core files, these states are static. In other cases, such as
282 282 handles that correspond to a running process or a created process, these
283 283 states are dynamic and change based on actions taken in the library. The
284 284 state can be obtained with the Pstate(3PROC) function.
285 285
286 286 The various states are:
287 287
288 288 PS_RUN An actively running process. This may be a process
289 289 that was obtained by creating it with functions such
290 290 as Pcreate(3PROC) or by grabbing an existing process
291 291 such as Pgrab(3PROC).
292 292
293 293 PS_STOP An active process that is no longer executing. A
294 294 process may stop for many reasons such as an explicit
295 295 stop request (through pstop(1) for example) or if a
296 296 tracing event is hit.
297 297
298 298 The reason a process is stopped may be obtained
299 299 through the thread's lwpstatus_t structure read
300 300 directly from /proc or obtained through the
301 301 Lstatus(3PROC) function.
302 302
303 303 PS_LOST Control over the process has been lost. This may
304 304 happen when the process executes a new image
305 305 requiring a different set of privileges. To resume
306 306 control call Preopen(3PROC). For more information on
307 307 losing control of a process, see proc(4).
308 308
309 309 PS_UNDEAD A zombie process. It has terminated, but it has not
310 310 been cleaned up yet by its parent. For more on the
311 311 conditions of becoming a zombie, see exec(2).
312 312
313 313 PS_DEAD Processes in this state are always core files. See
314 314 the earlier section Core Files for more information
315 315 on working with core files.
316 316
317 317 PS_IDLE A process that has never been run. This is always
318 318 the case for handles that refer to files as the files
319 319 cannot be executed. Those process handles are
320 320 obtained through calling Pgrab_file(3PROC).
321 321
322 322 Many functions relating to tracing processes, for example Psignal(3PROC),
323 323 Psetsignal(3PROC), Psetfault(3PROC), Psysentry(3PROC), and others,
324 324 mention that they only act upon Active Processes. This specifically
325 325 refers to processes whose state are in PS_RUN and PS_STOP. Process
326 326 handles in the other states have no notion of settable tracing flags,
327 327 though core files (type PS_DEAD) may have a read-only snapshot of their
328 328 tracing settings available.
329 329
330 330 TYPES
331 331 The libproc library uses many types that come from the /proc file system
332 332 (proc(4)) and the ELF format (elf(3ELF)). However, it also defines the
333 333 following types:
334 334
335 335 struct ps_prochandle
336 336
337 337 The struct ps_prochandle is an opaque handle to the library and the core
338 338 element of control for a process. Consumers obtain pointers to a handle
339 339 through the use of the Pcreate(), Pgrab(), and related functions. When a
340 340 caller is done with a handle, then it should call one of the Pfree() and
341 341 Prelease() functions to relinquish the handle, release associated
342 342 resources, and potentially set the process to run again.
343 343
344 344 struct ps_lwphandle
345 345
346 346 The struct ps_lwphandle is analogous to the struct ps_prochandle, but it
347 347 represents the control of an individual thread, rather than a process.
348 348 Consumers obtain pointers to a handle through the Lgrab() function and
349 349 relinquish it with the Lfree() function.
350 350
351 351 core_content_t
352 352
353 353 The core_content_t is a value which describes the various content types
354 354 of core files. These are used in functions such as Pcontent(3PROC) and
355 355 Pgcore(3PROC) to describe and control the types of content that get
356 356 included. Various content types may be included together through a
357 357 bitwise-inclusive-OR. The default system core contents are controlled
358 358 with the coreadm(1M) tool. The following table lists the current set of
359 359 core contents in the system, though the set may increase over time. The
360 360 string after the macro is the human readable string that corresponds with
361 361 the constant and is used by coreadm(1M), proc_content2str(3PROC), and
362 362 proc_str2content(3PROC).
363 363
364 364 CC_CONTENT_STACK ("stack")
365 365 The contents include the process stack. Note, this only
366 366 covers the main thread's stack. The stack of other threads
367 367 is covered by CC_CONTENT_ANON.
368 368
369 369 CC_CONTENT_HEAP ("heap")
370 370 The contents include the process heap.
371 371
372 372 CC_CONTENT_SHFILE ("shfile")
373 373 The contents include shared mappings that are backed by
374 374 files (e.g. mapped through mmap(2) with the MAP_SHARED
375 375 flag).
376 376
377 377 CC_CONTENT_SHANNON ("shannon")
378 378 The contents include shared mappings that are backed by
379 379 anonymous memory (e.g. mapped through mmap(2) with the
380 380 MAP_SHARED and MAP_ANON flags).
381 381
382 382 CC_CONTENT_RODATA ("rodata")
383 383 The contents include private read-only file mappings, such
384 384 as shared library text.
385 385
386 386 CC_CONTENT_ANON ("anon")
387 387 The contents include private anonymous mappings. This
388 388 includes the stacks of threads which are not the main
389 389 thread.
390 390
391 391 CC_CONTENT_SHM ("shm")
392 392 The contents include system V shared memory.
393 393
394 394 CC_CONTENT_ISM ("ism")
395 395 The contents include ISM (intimate shared memory) mappings.
396 396
397 397 CC_CONTENT_DISM ("dism")
398 398 The contents include DISM (dynamic shared memory) mappings.
399 399
400 400 CC_CONTENT_CTF ("ctf")
401 401 The contents include ctf(4) (Compact C Type Format)
402 402 information. Note, not all objects in the process may have
403 403 CTF information available.
404 404
405 405 CC_CONTENT_SYMTAB ("symtab")
406 406 The contents include the symbol table. Note, not all
407 407 objects in the process may have a symbol table available.
408 408
409 409 CC_CONTENT_ALL ("all")
410 410 This value indicates that all of the above content values
411 411 are present. Note that additional values may be added in
412 412 the future, in which case the value of the symbol will be
413 413 updated to include them. Comparisons with CC_CONTENT_ALL
414 414 should validate all the expected bits are set by an
415 415 expression such as (c & CC_CONTENT_ALL) == CC_CONTENT_ALL.
416 416
417 417 CC_CONTENT_NONE ("none")
418 418 This value indicates that there is no content present.
419 419
420 420 CC_CONTENT_DEFAULT ("default")
421 421 The content includes the following set of default values:
422 422 CC_CONTENT_STACK, CC_CONTENT_HEAP, CC_CONTENT_ISM,
423 423 CC_CONTENT_DISM, CC_CONTENT_SHM, CC_CONTENT_SHANON,
424 424 CC_CONTENT_TEXT, CC_CONTENT_DATA, CC_CONTENT_RODATA,
425 425 CC_CONTENT_ANON, CC_CONTENT_CTF, and CC_CONTENT_SYMTAB.
426 426 Note that the default may change. Comparisons with
427 427 CC_CONTENT_DEFAULT should validate that all of the expected
428 428 bits are set with an expression such as
429 429 (c & CC_CONTENT_DEFAULT) == CC_CONTENT_DEFAULT.
430 430
431 431 CC_CONTENT_INVALID
432 432 This indicates that the contents are invalid.
433 433
434 434 prfdinfo_t
435 435
436 436 The prfdinfo_t structure is used with the Pfdinfo_iter() function which
437 437 describes information about a file descriptor. The structure is defined
438 438 as follows:
439 439
440 440 typedef struct prfdinfo {
441 441 int pr_fd;
442 442 mode_t pr_mode;
443 443 uid_t pr_uid;
444 444 gid_t pr_gid;
445 445 major_t pr_major; /* think stat.st_dev */
446 446 minor_t pr_minor;
447 447 major_t pr_rmajor; /* think stat.st_rdev */
448 448 minor_t pr_rminor;
449 449 ino64_t pr_ino;
450 450 off64_t pr_offset;
451 451 off64_t pr_size;
452 452 int pr_fileflags; /* fcntl(F_GETXFL), etc */
453 453 int pr_fdflags; /* fcntl(F_GETFD), etc. */
454 454 char pr_path[MAXPATHLEN];
455 455 } prfdinfo_t;
456 456
457 457 The structure has similar information to that found in the stat structure
458 458 that's used as part of the stat family of system calls, defined in
459 459 stat(2). The member pr_fd contains the number of the file descriptor of
460 460 the file. The members pr_mode, pr_uid, pr_gid, pr_ino, and pr_size are
461 461 the same as the members st_mode, st_uid, st_gid, st_ino, and st_size in
462 462 the stat structure.
463 463
464 464 The pr_major and pr_minor members contain the major and minor numbers of
465 465 the device containing the directory for this file. This is similar to
466 466 the st_dev member of the stat structure, except that it is broken out
467 467 into its major and minor components. The pr_rmajor and pr_rminor members
468 468 are similar in spirit to pr_major and pr_minor; however, they are
469 469 equivalent to the st_rdev member of the stat structure and thus have
470 470 meaning for special character and block files.
471 471
472 472 The pr_offset member contains the current seek offset of the file
473 473 descriptor. The pr_fileflags and pr_fdflags members contain the flags
474 474 that would have been returned by a call to fcntl(2) with the arguments
475 475 F_GETXFL and F_GETFD respectively.
476 476
477 477 prsyminfo_t
478 478
479 479 The prsyminfo_t structure is used with the various symbol look up
480 480 functions Pxlookup_by_name(), Pxlookup_by_addr(), and
481 481 Pxlookup_by_addr_resolved() which describes additional information about
482 482 a symbol. The structure is defined as follows:
483 483
484 484 typedef struct prsyminfo {
485 485 const char *prs_object; /* object name */
486 486 const char *prs_name; /* symbol name */
487 487 Lmid_t prs_lmid; /* link map id */
488 488 uint_t prs_id; /* symbol id */
489 489 uint_t prs_table; /* symbol table id */
490 490 } prsyminfo_t;
491 491
492 492 The member prs_object points to a string that contains the name of the
493 493 object file, if known, that the symbol comes from. The member prs_name
494 494 points to the name of the symbol, if known. This may be unknown due to a
495 495 stripped binary that contains no symbol table. The member prs_lmid
496 496 indicates the link map identifier that the symbol was found on. For more
497 497 information on link map identifiers refer to the Linker and Libraries
498 498 Guide and dlopen(3C).
499 499
500 500 The members prs_id and prs_table can be used to determine both the symbol
501 501 table that the entry came from and which entry in the table it
502 502 corresponds to. If the value of prs_table is PR_SYMTAB then it came from
503 503 the ELF standard symbol table. However, if it is instead PR_DYNSYM, then
504 504 that indicates that it comes from the process's dynamic section.
505 505
506 506 proc_lwp_f
507 507
508 508 The proc_lwp_f is a function pointer type that is used with the
509 509 Plwp_iter() function. It is defined as typedef int proc_lwp_f(void *,
510 510 const lwpstatus_t *). The first argument is a pointer to an argument
511 511 that the user specifies, while the second has the thread's status
512 512 information and is defined in proc(4). For additional information on
513 513 using this type, see Plwp_iter(3PROC).
514 514
515 515 proc_lwp_all_f
516 516
517 517 The proc_lwp_all_f is a function pointer type that is used with the
518 518 Plwp_iter_all() function. It is defined as typedef int
519 519 proc_lwp_all_f(void *, const lwpstatus_t *, const lwpsinfo_t *). The
520 520 first argument is a pointer to an argument that the user specifies. The
521 521 second and third arguments contain the thread's status and thread-
522 522 specific ps(1) information respectively. Both structures are defined in
523 523 proc(4). For additional information on using this type, see
524 524 Plwp_iter_all(3PROC).
525 525
526 526 proc_walk_f
527 527
528 528 The proc_walk_f is a function pointer type that is used with the
529 529 proc_walk() function. It is defined as typedef int
530 530 proc_walk_f(psinfo_t *, lwpsinfo_t *, void *). The first argument
531 531 contains the process ps(1) information and the second argument contains
532 532 the representative thread's ps(1) information. Both structures are
533 533 defined in proc(4). The final argument is a pointer to an argument that
534 534 the user specifies. For more information on using this, see
535 535 proc_walk(3PROC).
536 536
537 537 proc_map_f
538 538
539 539 The proc_map_f is a function pointer type that is used with the
540 540 Pmapping_iter(), Pmapping_iter_resolved(), Pobject_iter(), and
541 541 Pobject_iter_resolved() functions. It is defined as typedef int
542 542 proc_map_f(void *, const prmap_t *, const char *). The first argument is
543 543 a pointer to an argument that the user specifies. The second argument is
544 544 describes the mapping information and is defined in proc(4). The final
545 545 argument contains the name of the mapping or object file in question.
546 546 For additional information on using this type, see Pmapping_iter(3PROC).
547 547
548 548 proc_env_f
549 549
550 550 The proc_env_f is a function pointer type that is used with the
551 551 Penv_iter() function. It is defined as typedef int proc_env_f(void *,
552 552 struct ps_prochandle *, uintptr_t, const char *). The first argument is
553 553 a pointer to an argument that the user specifies. The second argument is
554 554 a pointer to the struct ps_prochandle that the callback was passed to.
555 555 The third argument is the address of the environment variable in the
556 556 process. The fourth argument is the environment variable. Values in the
557 557 environment follow the convention of the form variable=value. For more
558 558 information on environment variables see exec(2) and environ(5). For
559 559 additional information on using this type, see Penv_iter(3PROC).
560 560
561 561 proc_sym_f
562 562
563 563 The proc_sym_f is a function pointer type that is used with the
564 564 Psmbol_iter(), Psymbol_iter_by_addr(), Psymbol_iter_by_name(), and
565 565 Psymbol_iter_by_lmid() functions. It is defined as typedef int
566 566 proc_sym_f(void *, const GElf_Sym *, const char *). The first argument
567 567 is a pointer to an argument that the user supplies. The second argument
568 568 is a pointer to the ELF symbol information in a 32-bit and 64-bit neutral
569 569 form. See elf(3ELF) and gelf(3ELF) for more information on it. The
570 570 final argument points to a character string that has the name of the
571 571 symbol. For additional information on using this type, see
572 572 Psymbol_iter(3PROC), Psymbol_iter_by_addr(3PROC),
573 573 Psymbol_iter_by_name(3PROC), and Psymbol_iter_by_lmid(3PROC).
574 574
575 575 proc_xsym_f
576 576
577 577 The proc_xsym_f is a function pointer type that is used with the
578 578 Pxsymbol_iter() function. It is defined as typedef int
579 579 proc_xsym_f(void *, const GElf_Sym *, const char *, const prsyminfo_t *).
580 580 The first three arguments are identical to those of proc_sym_f. The
581 581 final argument contains additional information about the symbol itself.
582 582 The members of the prsyminfo_t are defined earlier in this section. For
583 583 additional information on using this type, see Pxsymbol_iter(3PROC).
584 584
585 585 proc_stack_f
586 586
587 587 The proc_stack_f is a function pointer type that is used with the
588 588 Pstack_iter() function. It is defined as typedef int
589 589 proc_stack_f(void *, prgregset_t, uint_t, const long *). The first
590 590 argument is a pointer to an argument that the user specifies. The second
591 591 argument's contents are platform specific. The registers that contain
592 592 stack information, usually the stack pointer and frame pointer, will be
593 593 filled in to point to an entry. The prgregset_t is defined in proc(4).
594 594
595 595 The third argument contains the number of arguments to the current stack
596 596 frame and the fourth argument contains an array of addresses that
597 597 correspond to the arguments to that stack function. The value of the
598 598 third argument dictates the number of entries in the fourth argument.
599 599 For additional information on using this type, see Pstack_iter(3PROC).
600 600
601 601 proc_fdinfo_f
602 602
603 603 The proc_fdinfo_f is a function pointer type that is used with the
604 604 Pfdinfo_iter() function. It is defined as typedef int
605 605 proc_fdinfo_f(void *, prfdinfo_t *). The first argument is a pointer to
606 606 an argument that the user specifies. The second argument contains
607 607 information about an open file descriptor. The members of the prfdinfo_t
608 608 are defined earlier in this section. For additional information on using
609 609 this type, see Pfdinfo_iter(3PROC).
610 610
611 611 PROGRAMMING NOTES
612 612 When working with live processes, whether from the Pgrab(3PROC) or
613 613 Pcreate(3PROC) family of functions, there are some additional
614 614 considerations. Importantly, if a process calls any of the exec(2) suite
615 615 of functions, much of the state information that is obtained,
616 616 particularly that about mappings in the process will be invalid. Callers
617 617 must ensure that they call Preset_maps(3PROC) when they hold a process
618 618 handle across an exec. In addition, users of the library should
619 619 familiarize themselves with the PROGRAMMING NOTES section of the proc(4)
620 620 manual page, which discusses issues of privileges and security.
621 621
622 622 DEBUGGING
623 623 The library provides a means for obtaining additional debugging
624 624 information. The output itself is not part of the libproc library's
625 625 stable interface. Setting the environment variable LIBPROC_DEBUG to some
626 626 value will print information to standard error. For example,
627 627 LIBPROC_DEBUG=please.
628 628
629 629 LOCKING
630 630 Most functions operate on a handle to a process in the form of a struct
631 631 ps_prochandle *. Unless otherwise indicated, the library does not
632 632 provide any synchronization for different routines that are operating on
633 633 the same libproc library handle. It is up to the caller to ensure that
634 634 only a single thread is using a handle at any given time. Multiple
635 635 threads may call libproc library routines at the same time as long as
636 636 each thread is using a different handle.
637 637
638 638 Each individual function notes its MT-Level section. The MT-Level of a
639 639 routine that matches the above description will refer to this manual
640 640 page. If it does not, then it refers to the standard attributes in
641 641 attributes(5).
642 642
643 643 INTERFACE STABILITY
644 644 Uncommitted
645 645
646 646 While the library is considered an uncommitted interface, and is still
647 647 evolving, changes that break compatibility have been uncommon and this
648 648 trend is expected to continue. It is documented to allow consumers,
649 649 whether part of illumos or outside of it, to understand the libarary and
650 650 make use of it with the understanding that changes may occur which break
651 651 both source and binary compatibility.
652 652
653 653 SEE ALSO
654 654 gcore(1), mdb(1), proc(1), ps(1), coreadm(1M), exec(2), fcntl(2),
655 655 stat(2), Intro(3), dlopen(3C), elf(3ELF), ctf(4), proc(4), attributes(5),
656 656 environ(5), privileges(5)
657 657
658 658
659 659 Linkers and Libraries Guide.
660 660
661 661 Lfree(3PROC), Lgrab(3PROC), Lgrab_error(3PROC), Pcreate(3PROC),
662 662 Pcreate_agent(3PROC), Pcreate_callback(3PROC), Pcreate_error(3PROC),
663 663 Pdestroy_agent(3PROC), Pfgrab_core(3PROC), Pfree(3PROC), Pgrab(3PROC),
664 664 Pgrab_core(3PROC), Pgrab_error(3PROC), Pgrab_file(3PROC),
665 665 Pgrab_ops(3PROC), Prelease(3PROC), Preopen(3PROC), Pxcreate(3PROC)
666 666
667 667 Paddr_to_ctf(3PROC), Paddr_to_loadobj(3PROC), Paddr_to_map(3PROC),
668 668 Paddr_to_text_map(3PROC), Pasfd(3PROC), Pclearfault(3PROC),
669 669 Pclearsig(3PROC), Pcontent(3PROC), Pcred(3PROC), Pctlfd(3PROC),
670 670 Pdelbkpt(3PROC), Pdelwapt(3PROC), Pdstop(3PROC), Pexecname(3PROC),
671 671 Pfault(3PROC), Pfgcore(3PROC), Pgcore(3PROC), Pgetareg(3PROC),
672 672 Pgetauxval(3PROC), Pgetauxvec(3PROC), Pgetenv(3PROC), Pisprocdir(3PROC),
673 673 Pissyscall_prev(3PROC), Plmid(3PROC), Plmid_to_loadobj(3PROC),
674 674 Plmid_to_map(3PROC), Plookup_by_addr(3PROC), Plookup_by_name(3PROC),
675 675 Plwp_alt_stack(3PROC), Plwp_getfpregs(3PROC), Plwp_getpsinfo(3PROC),
676 676 Plwp_getregs(3PROC), Plwp_getspymaster(3PROC), Plwp_main_stack(3PROC),
677 677 Plwp_setfpregs(3PROC), Plwp_setregs(3PROC), Plwp_stack(3PROC),
678 678 Pname_to_ctf(3PROC), Pname_to_loadobj(3PROC), Pname_to_map(3PROC),
679 679 Pobjname(3PROC), Pobjname_resolved(3PROC), Pplatform(3PROC),
680 680 Ppltdest(3PROC), Ppriv(3PROC), Ppsinfo(3PROC), Pputareg(3PROC),
681 681 Prd_agent(3PROC), Pread(3PROC), Pread_string(3PROC), Preset_maps(3PROC),
682 682 Psecflags(3PROC), Psetbkpt(3PROC), Psetcred(3PROC), Psetfault(3PROC),
683 683 Psetflags(3PROC), Psetpriv(3PROC), Psetrun(3PROC), Psetsignal(3PROC),
684 684 Psetsysentry(3PROC), Psetsysexit(3PROC), Psetwapt(3PROC),
685 685 Psetzoneid(3PROC), Psignal(3PROC), Pstate(3PROC), Pstatus(3PROC),
686 686 Pstop(3PROC), Pstopstatus(3PROC), Psync(3PROC), Psysentry(3PROC),
687 687 Psysexit(3PROC), Puname(3PROC), Punsetflags(3PROC), Pupdate_maps(3PROC),
688 688 Pupdate_syms(3PROC), Pwait(3PROC), Pwrite(3PROC), Pxecbkpt(3PROC),
689 689 Pxecwapt(3PROC), Pxlookup_by_addr(3PROC),
690 690 Pxlookup_by_addr_resolved(3PROC), Pxlookup_by_name(3PROC),
691 691 Pzonename(3PROC), Pzonepath(3PROC), Pzoneroot(3PROC)
692 692
693 693 Lalt_stack(3PROC), Lclearfault(3PROC), Lclearsig(3PROC), Lctlfd(3PROC),
694 694 Ldstop(3PROC), Lgetareg(3PROC), Lmain_stack(3PROC), Lprochandle(3PROC),
695 695 Lpsinfo(3PROC), Lputareg(3PROC), Lsetrun(3PROC), Lstack(3PROC),
696 696 Lstate(3PROC), Lstatus(3PROC), Lstop(3PROC), Lsync(3PROC), Lwait(3PROC),
697 697 Lxecbkpt(3PROC), Lxecwapt(3PROC)
698 698
699 699 pr_access(3PROC), pr_close(3PROC), pr_creat(3PROC), pr_door_info(3PROC),
700 700 pr_exit(3PROC), pr_fcntl(3PROC), pr_fstat(3PROC), pr_fstat64(3PROC),
701 701 pr_fstatvfs(3PROC), pr_getitimer(3PROC), pr_getpeername(3PROC),
702 702 pr_getpeerucred(3PROC), pr_getprojid(3PROC), pr_getrctl(3PROC),
703 703 pr_getrlimit(3PROC), pr_getrlimit64(3PROC), pr_getsockname(3PROC),
704 704 pr_getsockopt(3PROC), pr_gettaskid(3PROC), pr_getzoneid(3PROC),
705 705 pr_ioctl(3PROC), pr_link(3PROC), pr_llseek(3PROC), pr_lseek(3PROC),
706 706 pr_lstat(3PROC), pr_lstat64(3PROC), pr_memcntl(3PROC), pr_meminfo(3PROC),
707 707 pr_mmap(3PROC), pr_munmap(3PROC), pr_open(3PROC),
708 708 pr_processor_bind(3PROC), pr_rename(3PROC), pr_setitimer(3PROC),
709 709 pr_setrctl(3PROC), pr_setrlimit(3PROC), pr_setrlimit64(3PROC),
710 710 pr_settaskid(3PROC), pr_sigaction(3PROC), pr_stat(3PROC),
711 711 pr_stat64(3PROC), pr_statvfs(3PROC), pr_unlink(3PROC), pr_waitid(3PROC),
712 712
713 713 Penv_iter(3PROC), Plwp_iter(3PROC), Plwp_iter_all(3PROC),
714 714 Pmapping_iter(3PROC), Pmapping_iter_resolved(3PROC), Pobject_iter(3PROC),
715 715 Pobject_iter_resolved(3PROC), Pstack_iter(3PROC), Psymbol_iter(3PROC),
716 716 Psymbol_iter_by_addr(3PROC), Psymbol_iter_by_lmid(3PROC),
717 717 Psymbol_iter_by_name(3PROC), Pxsymbol_iter(3PROC), Pfdinfo_iter(3PROC)
718 718
719 719 Perror_printf(3PROC), proc_arg_grab(3PROC), proc_arg_psinfo(3PROC),
720 720 proc_arg_xgrab(3PROC), proc_arg_xpsinfo(3PROC), proc_content2str(3PROC),
721 721 proc_finistdio(3PROC), proc_fltname(3PROC), proc_fltset2str(3PROC),
722 722 proc_flushstdio(3PROC), proc_get_auxv(3PROC), proc_get_cred(3PROC),
723 723 proc_get_priv(3PROC), proc_get_psinfo(3PROC), proc_get_status(3PROC),
724 724 proc_initstdio(3PROC), proc_lwp_in_set(3PROC),
725 725 proc_lwp_range_valid(3PROC), proc_signame(3PROC), proc_sigset2str(3PROC),
726 726 proc_str2content(3PROC), proc_str2flt(3PROC), proc_str2fltset(3PROC),
727 727 proc_str2sig(3PROC), proc_str2sigset(3PROC), proc_str2sys(3PROC),
728 728 proc_str2sysset(3PROC), proc_sysname(3PROC), proc_sysset2str(3PROC),
729 729 proc_unctrl_psinfo(3PROC), proc_walk(3PROC)
730 730
731 731 Pldt(3PROC), proc_get_ldt(3PROC),
732 732
733 733 Plwp_getgwindows(3PROC), Plwp_getxregs(3PROC), Plwp_setxregs(3PROC),
734 734
735 735 Plwp_getasrs(3PROC), Plwp_setasrs(3PROC)
736 736
737 737 illumos September 15, 2018 illumos
|
↓ open down ↓ |
654 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX