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