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