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