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