1 '\" te
   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 1989 AT&T
   6 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   8 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   9 .TH CORE 4 "Jun 6, 2016"
  10 .SH NAME
  11 core \- process core file
  12 .SH DESCRIPTION
  13 .LP
  14 The operating system writes out a core file for a process when the process is
  15 terminated due to receiving certain signals. A core file is a disk copy of the
  16 contents of the process address space at the time the process received the
  17 signal, along with additional information about the state of the process. This
  18 information can be consumed by a debugger. Core files can also be generated by
  19 applying the \fBgcore\fR(1) utility to a running process.
  20 .sp
  21 .LP
  22 Typically, core files are produced following abnormal termination of a process
  23 resulting from a bug in the corresponding application. Whatever the cause, the
  24 core file itself provides invaluable information to the programmer or support
  25 engineer to aid in diagnosing the problem. The core file can be inspected using
  26 a debugger such as \fBdbx\fR(1) or \fBmdb\fR(1) or by applying one of the
  27 \fBproc\fR(1) tools.
  28 .sp
  29 .LP
  30 The operating system attempts to create up to two core files for each
  31 abnormally terminating process, using a global core file name pattern and a
  32 per-process core file name pattern. These patterns are expanded to determine
  33 the pathname of the resulting core files, and can be configured by
  34 \fBcoreadm\fR(1M). By default, the global core file pattern is disabled and not
  35 used, and the per-process core file pattern is set to \fBcore\fR. Therefore, by
  36 default, the operating system attempts to create a core file named \fBcore\fR
  37 in the process's current working directory.
  38 .sp
  39 .LP
  40 A process terminates and produces a core file whenever it receives one of the
  41 signals whose default disposition is to cause a core dump. The list of signals
  42 that result in generating a core file is shown in \fBsignal.h\fR(3HEAD).
  43 Therefore, a process might not produce a core file if it has blocked or
  44 modified the behavior of the corresponding signal. Additionally, no core dump
  45 can be created under the following conditions:
  46 .RS +4
  47 .TP
  48 .ie t \(bu
  49 .el o
  50 If normal file and directory access permissions prevent the creation or
  51 modification of the per-process core file pathname by the current process user
  52 and group ID. This test does not apply to the global core file pathname
  53 because, regardless of the UID of the process dumping core, the attempt to
  54 write the global core file is made as the superuser.
  55 .RE
  56 .RS +4
  57 .TP
  58 .ie t \(bu
  59 .el o
  60 Core files owned by the user \fBnobody\fR will not be produced. For example,
  61 core files generated for the superuser on an NFS directory are owned by
  62 \fBnobody\fR and are, therefore, not written.
  63 .RE
  64 .RS +4
  65 .TP
  66 .ie t \(bu
  67 .el o
  68 If the core file pattern expands to a pathname that contains intermediate
  69 directory components that do not exist. For example, if the global pattern is
  70 set to \fB/var/core/%n/core.%p\fR, and no directory \fB/var/core/`uname -n`\fR
  71 has been created, no global core files are produced.
  72 .RE
  73 .RS +4
  74 .TP
  75 .ie t \(bu
  76 .el o
  77 If the destination directory is part of a filesystem that is mounted read-only.
  78 .RE
  79 .RS +4
  80 .TP
  81 .ie t \(bu
  82 .el o
  83 If the resource limit \fBRLIMIT_CORE\fR has been set to \fB0\fR for the
  84 process, no per-process core file is produced. Refer to \fBsetrlimit\fR(2) and
  85 \fBulimit\fR(1) for more information on resource limits.
  86 .RE
  87 .RS +4
  88 .TP
  89 .ie t \(bu
  90 .el o
  91 If the core file name already exists in the destination directory and is not a
  92 regular file (that is, is a symlink, block or character special-file, and so
  93 forth).
  94 .RE
  95 .RS +4
  96 .TP
  97 .ie t \(bu
  98 .el o
  99 If the kernel cannot open the destination file \fBO_EXCL\fR, which can occur if
 100 same file is being created by another process simultaneously.
 101 .RE
 102 .RS +4
 103 .TP
 104 .ie t \(bu
 105 .el o
 106 If the process's effective user ID is different from its real user ID or if its
 107 effective group ID is different from its real group ID. Similarly, set-user-ID
 108 and set-group-ID programs do not produce core files as this could potentially
 109 compromise system security. These processes can be explicitly granted
 110 permission to produce core files using \fBcoreadm\fR(1M), at the risk of
 111 exposing secure information.
 112 .RE
 113 .sp
 114 .LP
 115 The core file contains all the process information pertinent to debugging:
 116 contents of hardware registers, process status, and process data. The format of
 117 a core file is object file specific.
 118 .sp
 119 .LP
 120 For ELF executable programs (see \fBa.out\fR(4)), the core file generated is
 121 also an ELF file, containing ELF program and file headers. The \fBe_type\fR
 122 field in the file header has type \fBET_CORE\fR. The program header contains an
 123 entry for every segment that was part of the process address space, including
 124 shared library segments. The contents of the mappings specified by
 125 \fBcoreadm\fR(1M) are also part of the core image. Each program header has its
 126 \fBp_memsz\fR field set to the size of the mapping. The program headers that
 127 represent mappings whose data is included in the core file have their
 128 \fBp_filesz\fR field set the same as \fBp_memsz\fR, otherwise \fBp_filesz\fR is
 129 \fBzero\fR.
 130 .sp
 131 .LP
 132 A mapping's data can be excluded due to the core file content settings (see
 133 \fBcoreadm\fR(1M)), due to a failure, or due to a signal received after
 134 core dump initiation but before its completion. If the data is excluded
 135 because of a failure, the program header entry will have the
 136 \fBPF_SUNW_FAILURE\fR flag
 137 set in its \fBp_flags\fR field; if the data is excluded because of a signal,
 138 the segment's \fBp_flags\fR field will have the \fBPF_SUNW_KILLED\fR
 139 flag set.
 140 .sp
 141 .LP
 142 The program headers of an \fBELF\fR core file also contain entries for two
 143 \fBNOTE\fR segments, each containing several note entries as described below.
 144 The note entry header and core file note type (\fBn_type\fR) definitions are
 145 contained in <\fBsys/elf.h\fR>. The first \fBNOTE\fR segment exists for binary
 146 compatibility with old programs that deal with core files. It contains
 147 structures defined in <\fBsys/old_procfs.h\fR>. New programs should recognize
 148 and skip this \fBNOTE\fR segment, advancing instead to the new \fBNOTE\fR
 149 segment. The old \fBNOTE\fR segment is deleted from core files in a future
 150 release.
 151 .sp
 152 .LP
 153 The old \fBNOTE\fR segment contains the following entries. Each has entry name
 154 \fB"CORE"\fR and presents the contents of a system structure:
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBprpsinfo_t\fR\fR
 159 .ad
 160 .RS 16n
 161 \fBn_type\fR: \fBNT_PRPSINFO\fR. This entry contains information of interest to
 162 the \fBps\fR(1) command, such as process status, \fBCPU\fR usage, \fBnice\fR
 163 value, controlling terminal, user-ID, process-ID, the name of the executable,
 164 and so forth. The \fBprpsinfo_t\fR structure is defined in
 165 <\fBsys/old_procfs.h\fR>.
 166 .RE
 167 
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBchar\fR array\fR
 172 .ad
 173 .RS 16n
 174 \fBn_type\fR: \fBNT_PLATFORM\fR. This entry contains a string describing the
 175 specific model of the hardware platform on which this core file was created.
 176 This information is the same as provided by \fBsysinfo\fR(2) when invoked with
 177 the command \fBSI_PLATFORM\fR.
 178 .RE
 179 
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBauxv_t\fR array\fR
 184 .ad
 185 .RS 16n
 186 \fBn_type\fR: \fBNT_AUXV\fR. This entry contains the array of \fBauxv_t\fR
 187 structures that was passed by the operating system as startup information to
 188 the dynamic linker. Auxiliary vector information is defined in
 189 <\fBsys/auxv.h\fR>.
 190 .RE
 191 
 192 .sp
 193 .LP
 194 Following these entries, for each active (non-zombie) light-weight process
 195 (LWP) in the process, the old \fBNOTE\fR segment contains an entry with a
 196 \fBprstatus_t\fR structure, plus other optionally-present entries describing
 197 the LWP, as follows:
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fBprstatus_t\fR\fR
 202 .ad
 203 .RS 16n
 204 \fBn_type\fR: \fBNT_PRSTATUS\fR. This structure contains things of interest to
 205 a debugger from the operating system, such as the general registers, signal
 206 dispositions, state, reason for stopping, process-ID, and so forth. The
 207 \fBprstatus_t\fR structure is defined in <\fBsys/old_procfs.h\fR>.
 208 .RE
 209 
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fBprfpregset_t\fR\fR
 214 .ad
 215 .RS 16n
 216 \fBn_type\fR: \fBNT_PRFPREG\fR. This entry is present only if the \fBLWP\fR
 217 used the floating-point hardware. It contains the floating-point registers. The
 218 \fBprfpregset_t\fR structure is defined in <\fBsys/procfs_isa.h\fR>.
 219 .RE
 220 
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBgwindows_t\fR\fR
 225 .ad
 226 .RS 16n
 227 \fBn_type\fR: \fBNT_GWINDOWS\fR. This entry is present only on a SPARC machine
 228 and only if the system was unable to flush all of the register windows to the
 229 stack. It contains all of the unspilled register windows. The \fBgwindows_t\fR
 230 structure is defined in <\fBsys/regset.h\fR>.
 231 .RE
 232 
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBprxregset_t\fR\fR
 237 .ad
 238 .RS 16n
 239 \fBn_type\fR: \fBNT_PRXREG\fR. This entry is present only if the machine has
 240 extra register state associated with it. It contains the extra register state.
 241 The \fBprxregset_t\fR structure is defined in <\fBsys/procfs_isa.h\fR>.
 242 .RE
 243 
 244 .sp
 245 .LP
 246 The new \fBNOTE\fR segment contains the following entries. Each has entry name
 247 "\fBCORE\fR" and presents the contents of a system structure:
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fBpsinfo_t\fR\fR
 252 .ad
 253 .RS 20n
 254 \fBn_type\fR: \fBNT_PSINFO\fR. This structure contains information of interest
 255 to the \fBps\fR(1) command, such as process status, \fBCPU\fR usage, \fBnice\fR
 256 value, controlling terminal, user-ID, process-ID, the name of the executable,
 257 and so forth. The \fBpsinfo_t\fR structure is defined in <\fBsys/procfs.h\fR>.
 258 .RE
 259 
 260 .sp
 261 .ne 2
 262 .na
 263 \fB\fBpstatus_t\fR\fR
 264 .ad
 265 .RS 20n
 266 \fBn_type\fR: \fBNT_PSTATUS\fR. This structure contains things of interest to a
 267 debugger from the operating system, such as pending signals, state, process-ID,
 268 and so forth. The \fBpstatus_t\fR structure is defined in <\fBsys/procfs.h\fR>.
 269 .RE
 270 
 271 .sp
 272 .ne 2
 273 .na
 274 \fB\fBchar\fR array\fR
 275 .ad
 276 .RS 20n
 277 \fBn_type\fR: \fBNT_PLATFORM\fR. This entry contains a string describing the
 278 specific model of the hardware platform on which this core file was created.
 279 This information is the same as provided by \fBsysinfo\fR(2) when invoked with
 280 the command \fBSI_PLATFORM\fR.
 281 .RE
 282 
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fBauxv_t\fR array\fR
 287 .ad
 288 .RS 20n
 289 \fBn_type\fR: \fBNT_AUXV\fR. This entry contains the array of \fBauxv_t\fR
 290 structures that was passed by the operating system as startup information to
 291 the dynamic linker. Auxiliary vector information is defined in
 292 <\fBsys/auxv.h\fR>.
 293 .RE
 294 
 295 .sp
 296 .ne 2
 297 .na
 298 \fB\fBstruct utsname\fR\fR
 299 .ad
 300 .RS 20n
 301 \fBn_type\fR: \fBNT_UTSNAME\fR. This structure contains the system information
 302 that would have been returned to the process if it had performed a
 303 \fBuname\fR(2) system call prior to dumping core. The \fButsname\fR structure
 304 is defined in <\fBsys/utsname.h\fR>.
 305 .RE
 306 
 307 .sp
 308 .ne 2
 309 .na
 310 \fB\fBprcred_t\fR\fR
 311 .ad
 312 .RS 20n
 313 \fBn_type\fR: \fBNT_PRCRED\fR. This structure contains the process credentials,
 314 including the real, saved, and effective user and group IDs. The \fBprcred_t\fR
 315 structure is defined in <\fBsys/procfs.h\fR>. Following the structure is an
 316 optional array of supplementary group IDs. The total number of supplementary
 317 group IDs is given by the \fBpr_ngroups\fR member of the \fBprcred_t\fR
 318 structure, and the structure includes space for one supplementary group. If
 319 \fBpr_ngroups\fR is greater than 1, there is \fBpr_ngroups - 1\fR \fBgid_t\fR
 320 items following the structure; otherwise, there is no additional data.
 321 .RE
 322 
 323 .sp
 324 .ne 2
 325 .na
 326 \fB\fBchar array\fR\fR
 327 .ad
 328 .RS 20n
 329 \fBn_type\fR: \fBNT_ZONENAME\fR. This entry contains a string which describes
 330 the name of the zone in which the process was running. See \fBzones\fR(5). The
 331 information is the same as provided by \fBgetzonenamebyid\fR(3C) when invoked
 332 with the numerical ID returned by \fBgetzoneid\fR(3C).
 333 .RE
 334 
 335 .sp
 336 .ne 2
 337 .na
 338 \fB\fBprfdinfo_t\fR\fR
 339 .ad
 340 .RS 20n
 341 \fBn_type\fR: \fBNT_FDINFO\fR. This structure contains information about
 342 any open file descriptors, including the path, flags, and
 343 \fBstat\fR(2) information.  The \fBprfdinfo_t\fR structure is defined in
 344 <\fBsys/procfs.h\fR>.
 345 .RE
 346 
 347 .sp
 348 .ne 2
 349 .na
 350 \fB\fBstruct ssd\fR array\fR
 351 .ad
 352 .RS 20n
 353 \fBn_type\fR: \fBNT_LDT\fR. This entry is present only on an 32-bit x86 machine
 354 and only if the process has set up a Local Descriptor Table (LDT). It contains
 355 an array of structures of type \fBstruct ssd\fR, each of which was typically
 356 used to set up the \fB%gs\fR segment register to be used to fetch the address
 357 of the current thread information structure in a multithreaded process. The
 358 \fBssd\fR structure is defined in <\fBsys/sysi86.h\fR>.
 359 .RE
 360 
 361 .sp
 362 .ne 2
 363 .na
 364 \fB\fBcore_content_t\fR\fR
 365 .ad
 366 .RS 20n
 367 \fBn_type\fR: \fBNT_CONTENT\fR. This optional entry indicates which parts of
 368 the process image are specified to be included in the core file. See
 369 \fBcoreadm\fR(1M).
 370 .RE
 371 
 372 .sp
 373 .LP
 374 Following these entries, for each active and zombie \fBLWP\fR in the process,
 375 the new \fBNOTE\fR segment contains an entry with an \fBlwpsinfo_t\fR structure
 376 plus, for a non-zombie LWP, an entry with an \fBlwpstatus_t\fR structure, plus
 377 other optionally-present entries describing the LWP, as follows. A zombie LWP
 378 is a non-detached LWP that has terminated but has not yet been reaped by
 379 another LWP in the same process.
 380 .sp
 381 .ne 2
 382 .na
 383 \fB\fBlwpsinfo_t\fR\fR
 384 .ad
 385 .RS 15n
 386 \fBn_type\fR: \fBNT_LWPSINFO\fR. This structure contains information of
 387 interest to the \fBps\fR(1) command, such as \fBLWP\fR status, \fBCPU\fR usage,
 388 \fBnice\fR value, \fBLWP-ID\fR, and so forth. The \fBlwpsinfo_t\fR structure is
 389 defined in <\fBsys/procfs.h\fR>. This is the only entry present for a zombie
 390 LWP.
 391 .RE
 392 
 393 .sp
 394 .ne 2
 395 .na
 396 \fB\fBlwpstatus_t\fR\fR
 397 .ad
 398 .RS 15n
 399 \fBn_type\fR: \fBNT_LWPSTATUS\fR. This structure contains things of interest to
 400 a debugger from the operating system, such as the general registers, the
 401 floating point registers, state, reason for stopping, \fBLWP-ID\fR, and so
 402 forth. The \fBlwpstatus_t\fR structure is defined in <\fBsys/procfs.h>\fR>.
 403 .RE
 404 
 405 .sp
 406 .ne 2
 407 .na
 408 \fB\fBgwindows_t\fR\fR
 409 .ad
 410 .RS 15n
 411 \fBn_type\fR: \fBNT_GWINDOWS\fR. This entry is present only on a SPARC machine
 412 and only if the system was unable to flush all of the register windows to the
 413 stack. It contains all of the unspilled register windows. The \fBgwindows_t\fR
 414 structure is defined in \fB<sys/regset.h>\fR\&.
 415 .RE
 416 
 417 .sp
 418 .ne 2
 419 .na
 420 \fB\fBprxregset_t\fR\fR
 421 .ad
 422 .RS 15n
 423 \fBn_type\fR: \fBNT_PRXREG\fR. This entry is present only if the machine has
 424 extra register state associated with it. It contains the extra register state.
 425 The \fBprxregset_t\fR structure is defined in \fB<sys/procfs_isa.h>\fR\&.
 426 .RE
 427 
 428 .sp
 429 .ne 2
 430 .na
 431 \fB\fBasrset_t\fR\fR
 432 .ad
 433 .RS 15n
 434 \fBn_type\fR: \fBNT_ASRS\fR. This entry is present only on a SPARC V9 machine
 435 and only if the process is a 64-bit process. It contains the ancillary state
 436 registers for the \fBLWP.\fR The \fBasrset_t\fR structure is defined in
 437 \fB<sys/regset.h>\fR\&.
 438 .RE
 439 
 440 .sp
 441 .ne 2
 442 .na
 443 \fB\fBpsinfo_t\fR\fR
 444 .ad
 445 .RS 15n
 446 \fBn_type\fR: \fBNT_SPYMASTER\fR. This entry is present only for an agent
 447 LWP and contains the \fBpsinfo_t\fR of the process that created the agent
 448 LWP. See the \fBproc\fR(4) description of the \fBspymaster\fR entry for
 449 more details.
 450 .RE
 451 
 452 .sp
 453 .ne 2
 454 .na
 455 \fB\fBprsecflags_t\fR\fR
 456 .ad
 457 .RS 15n
 458 \fBn_type\fR: \fbNT_SECFLAGS\fR.  This entry contains the process
 459 security-flags, see \fBsecurity-flags\fR(5), \fBproc\fR(4), and
 460 \fBpsecflags\fR(1M) for more information.
 461 .RE
 462 
 463 .sp
 464 .LP
 465 Depending on the \fBcoreadm\fR(1M) settings, the section header of an ELF core
 466 file can contain entries for CTF, symbol table, and string table sections. The
 467 \fBsh_addr\fR fields are set to the base address of the first mapping of the
 468 load object that they came from to. This can be used to match those sections
 469 with the corresponding load object.
 470 .sp
 471 .LP
 472 The size of the core file created by a process can be controlled by the user
 473 (see \fBgetrlimit\fR(2)).
 474 .SH SEE ALSO
 475 .LP
 476 \fBelfdump\fR(1), \fBgcore\fR(1), \fBmdb\fR(1), \fBproc\fR(1), \fBps\fR(1),
 477 \fBcoreadm\fR(1M), \fBgetrlimit\fR(2), \fBsetrlimit\fR(2), \fBsetuid\fR(2),
 478 \fBsysinfo\fR(2), \fBuname\fR(2), \fBgetzonenamebyid\fR(3C),
 479 \fBgetzoneid\fR(3C), \fBelf\fR(3ELF), \fBsignal.h\fR(3HEAD), \fBa.out\fR(4),
 480 \fBproc\fR(4), \fBzones\fR(5), \fBsecurity-flags\fR(5)
 481 .sp
 482 .LP
 483 \fIANSI C Programmer's Guide\fR