Print this page
| 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 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 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
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 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
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 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 284 This entry is no longer included in core files, but is of historical note
285 285 because in the past it was included on SPARC-based systems.
286 286 While since then the
287 287 .Vt prxregset_t
288 288 and extended register sets have been defined on other architectures, they do not
289 289 emit this in the old note section because there is no binary compatibility.
290 290 .El
291 291 .Pp
292 292 The new
293 293 .Sy NOTE
294 294 segment contains the following entries.
295 295 Each has entry name
296 296 .Sy "CORE"
297 297 and presents the contents of a system structure:
298 298 .Bl -tag -width prxregset_t
299 299 .It Vt psinfo_t
300 300 .Fa n_type :
301 301 .Dv NT_PSINFO .
302 302 This structure contains information of interest to the
303 303 .Xr ps 1
304 304 command, such as process status, CPU usage, nice value, controlling terminal,
305 305 user-ID, process-ID, the name of the executable, and so forth.
306 306 The
307 307 .Vt psinfo_t
308 308 structure is defined in
309 309 .In sys/procfs.h
310 310 .It Vt pstatus_t
311 311 .Fa n_type :
312 312 .Dv NT_PSTATUS .
313 313 This structure contains things of interest to a debugger from the operating
314 314 system, such as pending signals, state, process-ID, and so forth.
315 315 The
316 316 .Vt pstatus_t
317 317 structure is defined in
318 318 .In sys/procfs.h .
319 319 .It Vt char[]
320 320 .Fa n_type :
321 321 .Dv NT_PLATFORM .
322 322 This entry contains a string describing the specific model of the hardware
323 323 platform on which this core file was created.
324 324 This information is the same as provided by
325 325 .Xr sysinfo 2
326 326 when invoked with the command
327 327 .Dv SI_PLATFORM .
328 328 .It auxv_t[]
329 329 .Fa n_type :
330 330 .Dv NT_AUXV .
331 331 This entry contains the array of
332 332 .Vt auxv_t
333 333 structures that was passed by the operating system as startup information to
334 334 the dynamic linker.
335 335 Auxiliary vector information is defined in
336 336 .In sys/auxv.h .
337 337 .It Vt struct utsname
338 338 .Fa n_type :
339 339 .Dv NT_UTSNAME .
340 340 This structure contains the system information that would have been returned
341 341 to the process if it had performed a
342 342 .Xr uname 2
343 343 system call prior to dumping core.
344 344 The
345 345 .Vt utsname
346 346 structure is defined in
347 347 .In sys/utsname.h .
348 348 .It pcred_t
349 349 .Fa n_type :
350 350 .Dv NT_PRCRED .
351 351 This structure contains the process credentials, including the real, saved,
352 352 and effective user and group IDs.
353 353 The
354 354 .Vt pcred_t
355 355 structure is defined in
356 356 .In sys/procfs.h .
357 357 Following the structure is an optional array of supplementary group IDs.
358 358 The total number of supplementary group IDs is given by the
359 359 .Fa pr_ngroups
360 360 member of the
361 361 .Vt pcred_t
362 362 structure, and the structure includes space for one supplementary group.
363 363 If
364 364 .Fa pr_ngroups
365 365 is greater than 1, there is
366 366 .So
367 367 .Fa pr_ngroups
368 368 - 1
369 369 .Sc
370 370 .Fa gid_t
371 371 items following the structure; otherwise, there is no additional data.
372 372 .It Vt char[]
373 373 .Fa n_type :
374 374 .Dv NT_ZONENAME .
375 375 This entry contains a string which describes the name of the zone in
376 376 which the process was running.
377 377 See
378 378 .Xr zones 7 .
379 379 The information is the same as provided by
380 380 .Xr getzonenamebyid 3C
381 381 when invoked with the numerical ID returned by
382 382 .Xr getzoneid 3C .
383 383 .It Vt prfdinfo_core_t
384 384 .Fa n_type :
385 385 .Dv NT_FDINFO .
386 386 This structure contains information about any open file descriptors, including
387 387 the path, flags, and
388 388 .Xr stat 2
389 389 information.
390 390 The
391 391 .Vt prfdinfo_core_t
392 392 structure is defined in
393 393 .In sys/procfs.h .
394 394 .It Vt struct ssd[]
395 395 .Fa n_type :
396 396 .Dv NT_LDT .
397 397 This entry is present only on an 32-bit x86 machine and only if the process has
398 398 set up a Local Descriptor Table
399 399 .Pq LDT .
400 400 It contains an array of structures of type
401 401 .Vt struct ssd ,
402 402 each of which was typically used to set up the
403 403 .Sy %gs
404 404 segment register to be used to fetch the address of the current thread
405 405 information structure in a multithreaded process.
406 406 The
407 407 .Vt ssd
408 408 structure is defined in
409 409 .In sys/sysi86.h .
410 410 .It Vt core_content_t
411 411 .Fa n_type :
412 412 .Dv NT_CONTENT .
413 413 This optional entry indicates which parts of the process image are specified
414 414 to be included in the core file.
415 415 See
416 416 .Xr coreadm 8 .
417 417 .It Vt prsecflags_t
418 418 .Fa n_type :
419 419 .Dv NT_SECFLAGS .
420 420 This entry contains the process security-flags, see
421 421 .Xr security-flags 7 ,
422 422 .Xr proc 5 ,
423 423 and
424 424 .Xr psecflags 1
425 425 for more information.
426 426 .It Vt prupanic_t
427 427 .Fa n_type :
428 428 .Dv NT_UPANIC .
429 429 This entry is included if a process terminated through the
430 430 .Xr upanic 2
431 431 system call.
432 432 It is defined in
433 433 .In sys/procfs.h .
434 434 .Pp
435 435 The
436 436 .Fa pru_version
437 437 member indicates the current revision of the structure, which is expected to be
438 438 .Dv PRUPANIC_VERSION_1
439 439 .Pq 1 .
440 440 The
441 441 .Fa pru_flags
442 442 member will be set to the bitwise-inclusive-OR of the following fields:
443 443 .Bl -tag -offset indent -width PRUPANIC_FLAG_MSG_TRUNC
444 444 .It Dv PRUPANIC_FLAG_MSG_VALID
445 445 Indicates that
446 446 .Fa pru_data
447 447 member has valid contents and that the process provided a message in the
448 448 .Xr upanic 2
449 449 call .
450 450 .It Dv PRUPANIC_FLAG_MSG_ERROR
451 451 Indicates that the calling process attempted to include a message; however, the
452 452 provided address of the message did not point to valid memory.
453 453 .It Dv PRUPANIC_FLAG_MSG_TRUNC
454 454 Indicates that the calling process included a message; however, the message it
455 455 wanted to provide was larger than the current message length.
456 456 .El
457 457 The
458 458 .Fa pru_data
459 459 array contains binary data that the terminating process used to indicate that
460 460 the reason why it panicked.
461 461 This member should be ignored if the
462 462 .Dv PRUPANIC_FLAG_MSG_VALID
463 463 flag is not set in
464 464 .Fa pru_flags .
465 465 While it is recommended that processes terminate with an ASCII string, consumers
466 466 of this should not assume that the binary data is made of of printable
467 467 characters.
468 468 .El
469 469 .Pp
470 470 For each active and zombie
471 471 .Sy LWP
472 472 in the process,
473 473 the new
474 474 .Sy NOTE
475 475 segment contains an entry with an
476 476 .Vt lwpsinfo_t
477 477 structure plus, for a non-zombie LWP, an entry with an
478 478 .Vt lwpstatus_t
479 479 structure, plus other optionally-present entries describing the LWP, as follows.
480 480 A zombie LWP is a non-detached LWP that has terminated but has not yet been
481 481 reaped by another LWP in the same process.
482 482 .Bl -tag -width "prxregset_t"
483 483 .It Vt lwpsinfo_t
484 484 .Fa n_type :
485 485 .Dv NT_LWPSINFO .
486 486 This structure contains information of interest to the
487 487 .Xr ps 1
488 488 command, such as LWP status, CPU usage, nice value, LWP-ID, and so forth.
489 489 The
490 490 .Vt lwpsinfo_t
491 491 structure is defined in
492 492 .In sys/procfs.h .
493 493 This is the only entry present for a zombie LWP.
494 494 .It lwpstatus_t
495 495 .Fa n_type :
496 496 .Dv NT_LWPSTATUS .
497 497 This structure contains things of interest to a debugger from the operating
498 498 system, such as the general registers, the floating point registers, state,
499 499 reason for stopping, LWP-ID, and so forth.
500 500 The
501 501 .Vt lwpstatus_t
502 502 structure is defined in
503 503 .In sys/procfs.h .
504 504 .Vt gwindows_t
505 505 .Fa n_type :
506 506 .Dv NT_GWINDOWS .
507 507 This entry is present only on a SPARC machine and only if the system was unable
508 508 to flush all of the register windows to the stack.
509 509 It contains all of the unspilled register windows.
510 510 The
511 511 .Vt gwindows_t
512 512 structure is defined in
513 513 .In sys/regset.h .
514 514 .It Vt prxregset_t
515 515 .Fa n_type :
516 516 .Dv NT_PRXREG .
517 517 This entry is present only if the machine has extra register state associated
518 518 with it.
519 519 It contains the extra register state.
520 520 The
521 521 .Vt prxregset_t
522 522 structure is defined in
523 523 .In sys/procfs_isa.h ;
524 524 however applications should include
525 525 .In procfs.h
526 526 to get access to it.
527 527 On most architectures the
528 528 .Vt prxregset_t
529 529 is opaque and is made up of multiple structures because it can vary in length.
530 530 .Xr proc 5
531 531 discusses the structure of the extended register set for each supported
532 532 architecture.
533 533 .It Vt asrset_t
534 534 \fB\fBasrset_t\fR\fR
535 535 .Fa n_type :
536 536 .Dv NT_ASRS .
537 537 This entry is present only on a SPARC V9 machine and only if the process is a
538 538 64-bit process.
539 539 It contains the ancillary state registers for the LWP.
540 540 The
541 541 .Vt asrset_t asrset_t
542 542 structure is defined in
543 543 .In sys/regset.h .
544 544 .It Vt psinfo_t
545 545 .Fa n_type :
546 546 .Dv NT_SPYMASTER .
547 547 This entry is present only for an agent LWP and contains the
548 548 .Vt psinfo_t
549 549 of the process that created the agent LWP.
550 550 See the
551 551 .Xr proc 5
552 552 description of the
553 553 .Sy spymaster
554 554 entry for more details.
555 555 .El
556 556 .Pp
557 557 Depending on the
558 558 .Xr coreadm 8
559 559 settings, the section header of an ELF core file can contain entries for CTF,
560 560 DWARF debug information, symbol table, and string table sections.
561 561 The
562 562 .Fa sh_addr
563 563 fields are set to the base address of the first mapping of the load object that
564 564 they came from to.
565 565 This can be used to match those sections with the corresponding load object.
566 566 .Pp
567 567 The size of the core file created by a process can be controlled by the user
568 568 .Po
569 569 see
570 570 .Xr getrlimit 2
571 571 .Pc
572 572 .Sh SEE ALSO
573 573 .Xr elfdump 1 ,
574 574 .Xr gcore 1 ,
575 575 .Xr mdb 1 ,
576 576 .Xr proc 1 ,
577 577 .Xr ps 1 ,
578 578 .Xr getrlimit 2 ,
579 579 .Xr setrlimit 2 ,
580 580 .Xr setuid 2 ,
581 581 .Xr sysinfo 2 ,
582 582 .Xr uname 2 ,
583 583 .Xr upanic 2 ,
584 584 .Xr getzoneid 3C ,
585 585 .Xr getzonenamebyid 3C ,
586 586 .Xr elf 3ELF ,
587 587 .Xr signal.h 3HEAD ,
588 588 .Xr a.out 5 ,
589 589 .Xr proc 5 ,
590 590 .Xr security-flags 7 ,
591 591 .Xr zones 7 ,
592 592 .Xr coreadm 8
|
↓ open down ↓ |
592 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX