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