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