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/man5/core.5
+++ new/usr/src/man/man5/core.5
1 1 '\"
2 2 .\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" Copyright 2012 DEY Storage Systems, Inc. All rights reserved.
4 4 .\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
5 5 .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
6 -.\" Copyright 2021 Oxide Computer Company
6 +.\" Copyright 2023 Oxide Computer Company
7 7 .\" Copyright 1989 AT&T
8 8 .\"
9 9 .\" The contents of this file are subject to the terms of the
10 10 .\" Common Development and Distribution License (the "License").
11 11 .\" You may not use this file except in compliance with the License.
12 12 .\"
13 13 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
14 14 .\" or http://www.opensolaris.org/os/licensing.
15 15 .\" See the License for the specific language governing permissions
16 16 .\" and limitations under the License.
17 17 .\"
18 18 .\" When distributing Covered Code, include this CDDL HEADER in each
19 19 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
20 20 .\" If applicable, add the following below this CDDL HEADER, with the
21 21 .\" fields enclosed by brackets "[]" replaced with your own identifying
22 22 .\" information: Portions Copyright [yyyy] [name of copyright owner]
23 23 .\"
24 -.Dd August 3, 2021
24 +.Dd January 24, 2023
25 25 .Dt CORE 5
26 26 .Os
27 27 .Sh NAME
28 28 .Nm core
29 29 .Nd process core file
30 30 .Sh DESCRIPTION
31 31 The operating system writes out a core file for a process when the process is
32 32 terminated due to receiving certain signals.
33 33 A core file is a disk copy of the contents of the process address space at the
34 34 time the process received the signal, along with additional information about
35 35 the state of the process.
36 36 This information can be consumed by a debugger.
37 37 Core files can also be generated by applying the
38 38 .Xr gcore 1
39 39 utility to a running process.
40 40 .Pp
41 41 Typically, core files are produced following abnormal termination of a process
42 42 resulting from a bug in the corresponding application.
43 43 Whatever the cause, the core file itself provides invaluable information to the
44 44 programmer or support engineer to aid in diagnosing the problem.
45 45 The core file can be inspected using a debugger such as
46 46 .Xr mdb 1 ,
47 47 gdb, dbx, or or by applying one of the
48 48 .Xr proc 1
49 49 tools.
50 50 .Pp
51 51 The operating system attempts to create up to two core files for each
52 52 abnormally terminating process, using a global core file name pattern and a
53 53 per-process core file name pattern.
54 54 These patterns are expanded to determine the pathname of the resulting core
55 55 files, and can be configured by
56 56 .Xr coreadm 8 .
57 57 By default, the global core file pattern is disabled and not used, and the
58 58 per-process core file pattern is set to
59 59 .Sy core .
60 60 Therefore, by default, the operating system attempts to create a core file named
61 61 .Pa core
62 62 in the process's current working directory.
63 63 .Pp
64 64 A process terminates and produces a core file whenever it receives one of the
65 65 signals whose default disposition is to cause a core dump or the
66 66 .Xr upanic 2
67 67 system call is used.
68 68 The list of signals that result in generating a core file is shown in
69 69 .Xr signal.h 3HEAD .
70 70 Therefore, a process might not produce a core file if it has blocked or
71 71 modified the behavior of the corresponding signal.
72 72 Additionally, no core dump can be created under the following conditions:
73 73 .Bl -bullet
74 74 .It
75 75 If normal file and directory access permissions prevent the creation or
76 76 modification of the per-process core file pathname by the current process user
77 77 and group ID.
78 78 This test does not apply to the global core file pathname because, regardless of
79 79 the UID of the process dumping core, the attempt to write the global core file
80 80 is made as the superuser.
81 81 .It
82 82 Core files owned by the user
83 83 .Sy nobody
84 84 will not be produced.
85 85 For example, core files generated for the superuser on an NFS directory are
86 86 owned by
87 87 .Sy nobody
88 88 and are, therefore, not written.
89 89 .It
90 90 If the core file pattern expands to a pathname that contains intermediate
91 91 directory components that do not exist.
92 92 For example, if the global pattern is set to
93 93 .Pa /var/core/%n/core.%p ,
94 94 and no directory
95 95 .Pa /var/core/`uname -n`
96 96 has been created, no global core files are produced.
97 97 .It
98 98 If the destination directory is part of a filesystem that is mounted read-only.
99 99 .It
100 100 If the resource limit
101 101 .Dv RLIMIT_CORE
102 102 has been set to
103 103 .Sy 0
104 104 for the
105 105 process, no per-process core file is produced.
106 106 Refer to
107 107 .Xr setrlimit 2
108 108 and
109 109 .Xr ulimit 1
110 110 for more information on resource limits.
111 111 .It
112 112 If the core file name already exists in the destination directory and is not a
113 113 regular file
114 114 .Pq that is, is a symlink, block or character special-file, and so forth .
115 115 .It
116 116 If the kernel cannot open the destination file
117 117 .Dv O_EXCL ,
118 118 which can occur if same file is being created by another process simultaneously.
119 119 .It
120 120 If the process's effective user ID is different from its real user ID or if its
121 121 effective group ID is different from its real group ID.
122 122 Similarly, set-user-ID and set-group-ID programs do not produce core files as
123 123 this could potentially compromise system security.
124 124 These processes can be explicitly granted permission to produce core files using
125 125 .Xr coreadm 8 ,
126 126 at the risk of exposing secure information.
127 127 .El
128 128 .Pp
129 129 The core file contains all the process information pertinent to debugging:
130 130 contents of hardware registers, process status, and process data.
131 131 The format of a core file is object file specific.
132 132 .Pp
133 133 For ELF executable programs
134 134 .Po
135 135 see
136 136 .Xr a.out 5
137 137 .Pc ,
138 138 the core file generated is also an ELF file, containing ELF program and file
139 139 headers.
140 140 The
141 141 .Fa e_type
142 142 field in the file header has type
143 143 .Dv ET_CORE .
144 144 The program header contains an entry for every segment that was part of the
145 145 process address space, including shared library segments.
146 146 The contents of the mappings specified by
147 147 .Xr coreadm 8
148 148 are also part of the core image.
149 149 Each program header has its
150 150 .Fa p_memsz
151 151 field set to the size of the mapping.
152 152 The program headers that represent mappings whose data is included in the core
153 153 file have their
154 154 .Fa p_filesz
155 155 field set the same as
156 156 .Fa p_memsz ,
157 157 otherwise
158 158 .Fa p_filesz
159 159 is
160 160 .Sy zero .
161 161 .Pp
162 162 A mapping's data can be excluded due to the core file content settings
163 163 .Po
164 164 see
165 165 .Xr coreadm 8
166 166 .Pc ,
167 167 due to a failure, or due to a signal received after core dump initiation but
168 168 before its completion.
169 169 If the data is excluded because of a failure, the program header entry will
170 170 have the
171 171 .Dv PF_SUNW_FAILURE
172 172 flag set in its
173 173 .Fa p_flags
174 174 field; if the data is excluded because of a signal, the segment's
175 175 .Fa p_flags
176 176 field will have the
177 177 .Dv PF_SUNW_KILLED
178 178 flag set.
179 179 .Pp
180 180 The program headers of an
181 181 .Sy ELF
182 182 core file also contain entries for two
183 183 .Sy NOTE
184 184 segments, each containing several note entries as described below.
185 185 The note entry header and core file note type
|
↓ open down ↓ |
151 lines elided |
↑ open up ↑ |
186 186 .Pq Fa n_type
187 187 definitions are contained in
188 188 .In sys/elf.h .
189 189 The first
190 190 .Sy NOTE
191 191 segment exists for binary compatibility with old programs that deal with core
192 192 files.
193 193 It contains structures defined in
194 194 .In sys/old_procfs.h .
195 195 New programs should recognize and skip this
196 -.Sy BNOTE
196 +.Sy NOTE
197 197 segment, advancing instead to the new
198 198 .Sy NOTE
199 199 segment.
200 200 The old
201 201 .Sy NOTE
202 202 segment is deleted from core files in a future release.
203 203 .Pp
204 204 The old
205 205 .Sy NOTE
206 206 segment contains the following entries.
207 207 Each has entry name
208 208 .Sy "CORE"
209 209 and presents the contents of a system structure:
210 210 .Bl -tag -width prpsinfo_t
211 211 .It Vt prpsinfo_t
212 212 .Fa n_type :
213 213 .Dv NT_PRPSINFO .
214 214 This entry contains information of interest to the
215 215 .Xr ps 1
216 216 command, such as process status, CPU usage, nice value, controlling terminal,
217 217 user-ID, process-ID, the name of the executable, and so forth.
218 218 The
219 219 .Vt prpsinfo_t
220 220 structure is defined in
221 221 .In sys/old_procfs.h .
222 222 .It Vt char[]
223 223 .Fa n_type :
224 224 .Dv NT_PLATFORM .
225 225 This entry contains a string describing the specific model of the hardware
226 226 platform on which this core file was created.
227 227 This information is the same as provided by
228 228 .Xr sysinfo 2
229 229 when invoked with the command
230 230 .Dv SI_PLATFORM .
231 231 .It Vt auxv_t[]
232 232 .Fa n_type :
233 233 .Dv NT_AUXV .
234 234 This entry contains the array of
235 235 .Vt Bauxv_t
236 236 structures that was passed by the operating system as startup information to
237 237 the dynamic linker.
238 238 Auxiliary vector information is defined in
239 239 .In sys/auxv.h .
240 240 .El
241 241 .Pp
242 242 Following these entries, for each active (non-zombie) light-weight process
243 243 .Pq LWP
244 244 in the process, the old
245 245 .Sy NOTE
246 246 segment contains an entry with a
247 247 .Vt prstatus_t
248 248 structure, plus other optionally-present entries describing the LWP, as follows:
249 249 .Bl -tag -width "prfpregset_t"
250 250 .It Vt prstatus_t
251 251 .Fa n_type :
252 252 .Dv NT_PRSTATUS .
253 253 This structure contains things of interest to a debugger from the operating
|
↓ open down ↓ |
47 lines elided |
↑ open up ↑ |
254 254 system, such as the general registers, signal dispositions, state, reason for
255 255 stopping, process-ID, and so forth.
256 256 The
257 257 .Vt prstatus_t
258 258 structure is defined in
259 259 .In sys/old_procfs.h .
260 260 .It Vt prfpregset_t
261 261 .Fa n_type :
262 262 .Dv NT_PRFPREG .
263 263 This entry is present only if the
264 -.Sy BLWP
264 +.Sy LWP
265 265 used the floating-point hardware.
266 266 It contains the floating-point registers.
267 267 The
268 268 .Vt prfpregset_t
269 269 structure is defined in
270 270 .In sys/procfs_isa.h .
271 271 .It Vt gwindows_t
272 272 .Fa n_type :
273 273 .Dv NT_GWINDOWS .
274 274 This entry is present only on a SPARC machine and only if the system was unable
275 275 to flush all of the register windows to the stack.
276 276 It contains all of the unspilled register windows.
277 277 The
278 278 .Vt gwindows_t
279 279 structure is defined in
280 280 .In sys/regset.h .
281 281 .It Vt prxregset_t
282 282 .Fa n_type :
283 283 .Dv NT_PRXREG .
284 -This entry is present only if the machine has extra register state associated
285 -with it.
286 -It contains the extra register state.
287 -The
284 +This entry is no longer included in core files, but is of historical note
285 +because in the past it was included on SPARC-based systems.
286 +While since then the
288 287 .Vt prxregset_t
289 -structure is defined in
290 -.Vt sys/procfs_isa.h .
288 +and extended register sets have been defined on other architectures, they do not
289 +emit this in the old note section because there is no binary compatibility.
291 290 .El
292 291 .Pp
293 292 The new
294 293 .Sy NOTE
295 294 segment contains the following entries.
296 295 Each has entry name
297 296 .Sy "CORE"
298 297 and presents the contents of a system structure:
299 298 .Bl -tag -width prxregset_t
300 299 .It Vt psinfo_t
301 300 .Fa n_type :
302 301 .Dv NT_PSINFO .
303 302 This structure contains information of interest to the
304 303 .Xr ps 1
305 304 command, such as process status, CPU usage, nice value, controlling terminal,
306 305 user-ID, process-ID, the name of the executable, and so forth.
307 306 The
308 307 .Vt psinfo_t
309 308 structure is defined in
310 309 .In sys/procfs.h
311 310 .It Vt pstatus_t
312 311 .Fa n_type :
313 312 .Dv NT_PSTATUS .
314 313 This structure contains things of interest to a debugger from the operating
315 314 system, such as pending signals, state, process-ID, and so forth.
316 315 The
317 316 .Vt pstatus_t
318 317 structure is defined in
319 318 .In sys/procfs.h .
320 319 .It Vt char[]
321 320 .Fa n_type :
322 321 .Dv NT_PLATFORM .
323 322 This entry contains a string describing the specific model of the hardware
324 323 platform on which this core file was created.
325 324 This information is the same as provided by
326 325 .Xr sysinfo 2
327 326 when invoked with the command
328 327 .Dv SI_PLATFORM .
329 328 .It auxv_t[]
330 329 .Fa n_type :
331 330 .Dv NT_AUXV .
332 331 This entry contains the array of
333 332 .Vt auxv_t
334 333 structures that was passed by the operating system as startup information to
335 334 the dynamic linker.
336 335 Auxiliary vector information is defined in
337 336 .In sys/auxv.h .
338 337 .It Vt struct utsname
339 338 .Fa n_type :
340 339 .Dv NT_UTSNAME .
341 340 This structure contains the system information that would have been returned
342 341 to the process if it had performed a
343 342 .Xr uname 2
344 343 system call prior to dumping core.
345 344 The
346 345 .Vt utsname
347 346 structure is defined in
348 347 .In sys/utsname.h .
349 348 .It pcred_t
350 349 .Fa n_type :
351 350 .Dv NT_PRCRED .
352 351 This structure contains the process credentials, including the real, saved,
353 352 and effective user and group IDs.
354 353 The
355 354 .Vt pcred_t
356 355 structure is defined in
357 356 .In sys/procfs.h .
358 357 Following the structure is an optional array of supplementary group IDs.
359 358 The total number of supplementary group IDs is given by the
360 359 .Fa pr_ngroups
361 360 member of the
362 361 .Vt pcred_t
363 362 structure, and the structure includes space for one supplementary group.
364 363 If
365 364 .Fa pr_ngroups
366 365 is greater than 1, there is
367 366 .So
368 367 .Fa pr_ngroups
369 368 - 1
370 369 .Sc
371 370 .Fa gid_t
372 371 items following the structure; otherwise, there is no additional data.
373 372 .It Vt char[]
374 373 .Fa n_type :
375 374 .Dv NT_ZONENAME .
376 375 This entry contains a string which describes the name of the zone in
377 376 which the process was running.
378 377 See
379 378 .Xr zones 7 .
380 379 The information is the same as provided by
381 380 .Xr getzonenamebyid 3C
382 381 when invoked with the numerical ID returned by
383 382 .Xr getzoneid 3C .
384 383 .It Vt prfdinfo_core_t
385 384 .Fa n_type :
386 385 .Dv NT_FDINFO .
387 386 This structure contains information about any open file descriptors, including
388 387 the path, flags, and
389 388 .Xr stat 2
390 389 information.
391 390 The
392 391 .Vt prfdinfo_core_t
393 392 structure is defined in
394 393 .In sys/procfs.h .
395 394 .It Vt struct ssd[]
396 395 .Fa n_type :
397 396 .Dv NT_LDT .
398 397 This entry is present only on an 32-bit x86 machine and only if the process has
399 398 set up a Local Descriptor Table
400 399 .Pq LDT .
401 400 It contains an array of structures of type
402 401 .Vt struct ssd ,
403 402 each of which was typically used to set up the
404 403 .Sy %gs
405 404 segment register to be used to fetch the address of the current thread
406 405 information structure in a multithreaded process.
407 406 The
408 407 .Vt ssd
409 408 structure is defined in
410 409 .In sys/sysi86.h .
411 410 .It Vt core_content_t
412 411 .Fa n_type :
413 412 .Dv NT_CONTENT .
414 413 This optional entry indicates which parts of the process image are specified
415 414 to be included in the core file.
416 415 See
417 416 .Xr coreadm 8 .
418 417 .It Vt prsecflags_t
419 418 .Fa n_type :
420 419 .Dv NT_SECFLAGS .
421 420 This entry contains the process security-flags, see
422 421 .Xr security-flags 7 ,
423 422 .Xr proc 5 ,
424 423 and
425 424 .Xr psecflags 1
426 425 for more information.
427 426 .It Vt prupanic_t
428 427 .Fa n_type :
429 428 .Dv NT_UPANIC .
430 429 This entry is included if a process terminated through the
431 430 .Xr upanic 2
432 431 system call.
433 432 It is defined in
434 433 .In sys/procfs.h .
435 434 .Pp
436 435 The
437 436 .Fa pru_version
438 437 member indicates the current revision of the structure, which is expected to be
439 438 .Dv PRUPANIC_VERSION_1
440 439 .Pq 1 .
441 440 The
442 441 .Fa pru_flags
443 442 member will be set to the bitwise-inclusive-OR of the following fields:
444 443 .Bl -tag -offset indent -width PRUPANIC_FLAG_MSG_TRUNC
445 444 .It Dv PRUPANIC_FLAG_MSG_VALID
446 445 Indicates that
447 446 .Fa pru_data
448 447 member has valid contents and that the process provided a message in the
449 448 .Xr upanic 2
450 449 call .
451 450 .It Dv PRUPANIC_FLAG_MSG_ERROR
452 451 Indicates that the calling process attempted to include a message; however, the
453 452 provided address of the message did not point to valid memory.
454 453 .It Dv PRUPANIC_FLAG_MSG_TRUNC
455 454 Indicates that the calling process included a message; however, the message it
456 455 wanted to provide was larger than the current message length.
457 456 .El
458 457 The
459 458 .Fa pru_data
460 459 array contains binary data that the terminating process used to indicate that
461 460 the reason why it panicked.
462 461 This member should be ignored if the
463 462 .Dv PRUPANIC_FLAG_MSG_VALID
464 463 flag is not set in
465 464 .Fa pru_flags .
466 465 While it is recommended that processes terminate with an ASCII string, consumers
467 466 of this should not assume that the binary data is made of of printable
468 467 characters.
469 468 .El
470 469 .Pp
471 470 For each active and zombie
472 471 .Sy LWP
473 472 in the process,
474 473 the new
475 474 .Sy NOTE
476 475 segment contains an entry with an
477 476 .Vt lwpsinfo_t
478 477 structure plus, for a non-zombie LWP, an entry with an
479 478 .Vt lwpstatus_t
480 479 structure, plus other optionally-present entries describing the LWP, as follows.
481 480 A zombie LWP is a non-detached LWP that has terminated but has not yet been
482 481 reaped by another LWP in the same process.
483 482 .Bl -tag -width "prxregset_t"
484 483 .It Vt lwpsinfo_t
485 484 .Fa n_type :
486 485 .Dv NT_LWPSINFO .
487 486 This structure contains information of interest to the
488 487 .Xr ps 1
489 488 command, such as LWP status, CPU usage, nice value, LWP-ID, and so forth.
490 489 The
491 490 .Vt lwpsinfo_t
492 491 structure is defined in
493 492 .In sys/procfs.h .
494 493 This is the only entry present for a zombie LWP.
495 494 .It lwpstatus_t
496 495 .Fa n_type :
497 496 .Dv NT_LWPSTATUS .
498 497 This structure contains things of interest to a debugger from the operating
499 498 system, such as the general registers, the floating point registers, state,
500 499 reason for stopping, LWP-ID, and so forth.
501 500 The
502 501 .Vt lwpstatus_t
503 502 structure is defined in
504 503 .In sys/procfs.h .
505 504 .Vt gwindows_t
506 505 .Fa n_type :
507 506 .Dv NT_GWINDOWS .
508 507 This entry is present only on a SPARC machine and only if the system was unable
509 508 to flush all of the register windows to the stack.
510 509 It contains all of the unspilled register windows.
511 510 The
512 511 .Vt gwindows_t
513 512 structure is defined in
|
↓ open down ↓ |
213 lines elided |
↑ open up ↑ |
514 513 .In sys/regset.h .
515 514 .It Vt prxregset_t
516 515 .Fa n_type :
517 516 .Dv NT_PRXREG .
518 517 This entry is present only if the machine has extra register state associated
519 518 with it.
520 519 It contains the extra register state.
521 520 The
522 521 .Vt prxregset_t
523 522 structure is defined in
524 -.In sys/procfs_isa.h .
523 +.In sys/procfs_isa.h ;
524 +however applications should include
525 +.In procfs.h
526 +to get access to it.
527 +On most architectures the
528 +.Vt prxregset_t
529 +is opaque and is made up of multiple structures because it can vary in length.
530 +.Xr proc 5
531 +discusses the structure of the extended register set for each supported
532 +architecture.
525 533 .It Vt asrset_t
526 534 \fB\fBasrset_t\fR\fR
527 535 .Fa n_type :
528 536 .Dv NT_ASRS .
529 537 This entry is present only on a SPARC V9 machine and only if the process is a
530 538 64-bit process.
531 539 It contains the ancillary state registers for the LWP.
532 540 The
533 541 .Vt asrset_t asrset_t
534 542 structure is defined in
535 543 .In sys/regset.h .
536 544 .It Vt psinfo_t
537 545 .Fa n_type :
538 546 .Dv NT_SPYMASTER .
539 547 This entry is present only for an agent LWP and contains the
540 548 .Vt psinfo_t
541 549 of the process that created the agent LWP.
542 550 See the
543 551 .Xr proc 5
544 552 description of the
545 553 .Sy spymaster
546 554 entry for more details.
547 555 .El
548 556 .Pp
549 557 Depending on the
550 558 .Xr coreadm 8
551 559 settings, the section header of an ELF core file can contain entries for CTF,
552 560 DWARF debug information, symbol table, and string table sections.
553 561 The
554 562 .Fa sh_addr
555 563 fields are set to the base address of the first mapping of the load object that
556 564 they came from to.
557 565 This can be used to match those sections with the corresponding load object.
558 566 .Pp
559 567 The size of the core file created by a process can be controlled by the user
560 568 .Po
561 569 see
562 570 .Xr getrlimit 2
563 571 .Pc
564 572 .Sh SEE ALSO
565 573 .Xr elfdump 1 ,
566 574 .Xr gcore 1 ,
567 575 .Xr mdb 1 ,
568 576 .Xr proc 1 ,
569 577 .Xr ps 1 ,
570 578 .Xr getrlimit 2 ,
571 579 .Xr setrlimit 2 ,
572 580 .Xr setuid 2 ,
573 581 .Xr sysinfo 2 ,
574 582 .Xr uname 2 ,
575 583 .Xr upanic 2 ,
576 584 .Xr getzoneid 3C ,
577 585 .Xr getzonenamebyid 3C ,
578 586 .Xr elf 3ELF ,
579 587 .Xr signal.h 3HEAD ,
580 588 .Xr a.out 5 ,
581 589 .Xr proc 5 ,
582 590 .Xr security-flags 7 ,
583 591 .Xr zones 7 ,
584 592 .Xr coreadm 8
|
↓ open down ↓ |
50 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX