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