1 CORE(4)                 File Formats and Configurations                CORE(4)
   2 
   3 
   4 
   5 NAME
   6        core - process core file
   7 
   8 DESCRIPTION
   9        The operating system writes out a core file for a process when the
  10        process is terminated due to receiving certain signals. A core file is
  11        a disk copy of the contents of the process address space at the time
  12        the process received the signal, along with additional information
  13        about the state of the process. This information can be consumed by a
  14        debugger. Core files can also be generated by applying the gcore(1)
  15        utility to a running process.
  16 
  17 
  18        Typically, core files are produced following abnormal termination of a
  19        process resulting from a bug in the corresponding application. Whatever
  20        the cause, the core file itself provides invaluable information to the
  21        programmer or support engineer to aid in diagnosing the problem. The
  22        core file can be inspected using a debugger such as dbx(1) or mdb(1) or
  23        by applying one of the proc(1) tools.
  24 
  25 
  26        The operating system attempts to create up to two core files for each
  27        abnormally terminating process, using a global core file name pattern
  28        and a per-process core file name pattern. These patterns are expanded
  29        to determine the pathname of the resulting core files, and can be
  30        configured by coreadm(1M). By default, the global core file pattern is
  31        disabled and not used, and the per-process core file pattern is set to
  32        core. Therefore, by default, the operating system attempts to create a
  33        core file named core in the process's current working directory.
  34 
  35 
  36        A process terminates and produces a core file whenever it receives one
  37        of the signals whose default disposition is to cause a core dump. The
  38        list of signals that result in generating a core file is shown in
  39        signal.h(3HEAD).  Therefore, a process might not produce a core file if
  40        it has blocked or modified the behavior of the corresponding signal.
  41        Additionally, no core dump can be created under the following
  42        conditions:
  43 
  44            o      If normal file and directory access permissions prevent the
  45                   creation or modification of the per-process core file
  46                   pathname by the current process user and group ID. This test
  47                   does not apply to the global core file pathname because,
  48                   regardless of the UID of the process dumping core, the
  49                   attempt to write the global core file is made as the
  50                   superuser.
  51 
  52            o      Core files owned by the user nobody will not be produced.
  53                   For example, core files generated for the superuser on an
  54                   NFS directory are owned by nobody and are, therefore, not
  55                   written.
  56 
  57            o      If the core file pattern expands to a pathname that contains
  58                   intermediate directory components that do not exist. For
  59                   example, if the global pattern is set to
  60                   /var/core/%n/core.%p, and no directory /var/core/`uname -n`
  61                   has been created, no global core files are produced.
  62 
  63            o      If the destination directory is part of a filesystem that is
  64                   mounted read-only.
  65 
  66            o      If the resource limit RLIMIT_CORE has been set to 0 for the
  67                   process, no per-process core file is produced. Refer to
  68                   setrlimit(2) and ulimit(1) for more information on resource
  69                   limits.
  70 
  71            o      If the core file name already exists in the destination
  72                   directory and is not a regular file (that is, is a symlink,
  73                   block or character special-file, and so forth).
  74 
  75            o      If the kernel cannot open the destination file O_EXCL, which
  76                   can occur if same file is being created by another process
  77                   simultaneously.
  78 
  79            o      If the process's effective user ID is different from its
  80                   real user ID or if its effective group ID is different from
  81                   its real group ID. Similarly, set-user-ID and set-group-ID
  82                   programs do not produce core files as this could potentially
  83                   compromise system security. These processes can be
  84                   explicitly granted permission to produce core files using
  85                   coreadm(1M), at the risk of exposing secure information.
  86 
  87 
  88        The core file contains all the process information pertinent to
  89        debugging: contents of hardware registers, process status, and process
  90        data. The format of a core file is object file specific.
  91 
  92 
  93        For ELF executable programs (see a.out(4)), the core file generated is
  94        also an ELF file, containing ELF program and file headers. The e_type
  95        field in the file header has type ET_CORE. The program header contains
  96        an entry for every segment that was part of the process address space,
  97        including shared library segments. The contents of the mappings
  98        specified by coreadm(1M) are also part of the core image. Each program
  99        header has its p_memsz field set to the size of the mapping. The
 100        program headers that represent mappings whose data is included in the
 101        core file have their p_filesz field set the same as p_memsz, otherwise
 102        p_filesz is zero.
 103 
 104 
 105        A mapping's data can be excluded due to the core file content settings
 106        (see coreadm(1M)), due to a failure, or due to a signal received after
 107        core dump initiation but before its completion. If the data is excluded
 108        because of a failure, the program header entry will have the
 109        PF_SUNW_FAILURE flag set in its p_flags field; if the data is excluded
 110        because of a signal, the segment's p_flags field will have the
 111        PF_SUNW_KILLED flag set.
 112 
 113 
 114        The program headers of an ELF core file also contain entries for two
 115        NOTE segments, each containing several note entries as described below.
 116        The note entry header and core file note type (n_type) definitions are
 117        contained in <sys/elf.h>. The first NOTE   segment exists for binary
 118        compatibility with old programs that deal with core files. It contains
 119        structures defined in <sys/old_procfs.h>. New programs should recognize
 120        and skip this NOTE segment, advancing instead to the new NOTE segment.
 121        The old NOTE segment is deleted from core files in a future release.
 122 
 123 
 124        The old NOTE segment contains the following entries. Each has entry
 125        name "CORE" and presents the contents of a system structure:
 126 
 127        prpsinfo_t
 128                        n_type: NT_PRPSINFO. This entry contains information of
 129                        interest to the ps(1) command, such as process status,
 130                        CPU usage, nice value, controlling terminal, user-ID,
 131                        process-ID, the name of the executable, and so forth.
 132                        The prpsinfo_t structure is defined in
 133                        <sys/old_procfs.h>.
 134 
 135 
 136        char array
 137                        n_type: NT_PLATFORM. This entry contains a string
 138                        describing the specific model of the hardware platform
 139                        on which this core file was created.  This information
 140                        is the same as provided by sysinfo(2) when invoked with
 141                        the command SI_PLATFORM.
 142 
 143 
 144        auxv_t array
 145                        n_type: NT_AUXV. This entry contains the array of
 146                        auxv_t structures that was passed by the operating
 147                        system as startup information to the dynamic linker.
 148                        Auxiliary vector information is defined in
 149                        <sys/auxv.h>.
 150 
 151 
 152 
 153        Following these entries, for each active (non-zombie) light-weight
 154        process (LWP) in the process, the old NOTE segment contains an entry
 155        with a prstatus_t structure, plus other optionally-present entries
 156        describing the LWP, as follows:
 157 
 158        prstatus_t
 159                        n_type: NT_PRSTATUS. This structure contains things of
 160                        interest to a debugger from the operating system, such
 161                        as the general registers, signal dispositions, state,
 162                        reason for stopping, process-ID, and so forth. The
 163                        prstatus_t structure is defined in <sys/old_procfs.h>.
 164 
 165 
 166        prfpregset_t
 167                        n_type: NT_PRFPREG. This entry is present only if the
 168                        LWP used the floating-point hardware. It contains the
 169                        floating-point registers. The prfpregset_t structure is
 170                        defined in <sys/procfs_isa.h>.
 171 
 172 
 173        gwindows_t
 174                        n_type: NT_GWINDOWS. This entry is present only on a
 175                        SPARC machine and only if the system was unable to
 176                        flush all of the register windows to the stack. It
 177                        contains all of the unspilled register windows. The
 178                        gwindows_t structure is defined in <sys/regset.h>.
 179 
 180 
 181        prxregset_t
 182                        n_type: NT_PRXREG. This entry is present only if the
 183                        machine has extra register state associated with it. It
 184                        contains the extra register state.  The prxregset_t
 185                        structure is defined in <sys/procfs_isa.h>.
 186 
 187 
 188 
 189        The new NOTE segment contains the following entries. Each has entry
 190        name "CORE" and presents the contents of a system structure:
 191 
 192        psinfo_t
 193                            n_type: NT_PSINFO. This structure contains
 194                            information of interest to the ps(1) command, such
 195                            as process status, CPU usage, nice value,
 196                            controlling terminal, user-ID, process-ID, the name
 197                            of the executable, and so forth. The psinfo_t
 198                            structure is defined in <sys/procfs.h>.
 199 
 200 
 201        pstatus_t
 202                            n_type: NT_PSTATUS. This structure contains things
 203                            of interest to a debugger from the operating
 204                            system, such as pending signals, state, process-ID,
 205                            and so forth. The pstatus_t structure is defined in
 206                            <sys/procfs.h>.
 207 
 208 
 209        char array
 210                            n_type: NT_PLATFORM. This entry contains a string
 211                            describing the specific model of the hardware
 212                            platform on which this core file was created.  This
 213                            information is the same as provided by sysinfo(2)
 214                            when invoked with the command SI_PLATFORM.
 215 
 216 
 217        auxv_t array
 218                            n_type: NT_AUXV. This entry contains the array of
 219                            auxv_t structures that was passed by the operating
 220                            system as startup information to the dynamic
 221                            linker. Auxiliary vector information is defined in
 222                            <sys/auxv.h>.
 223 
 224 
 225        struct utsname
 226                            n_type: NT_UTSNAME. This structure contains the
 227                            system information that would have been returned to
 228                            the process if it had performed a uname(2) system
 229                            call prior to dumping core. The utsname structure
 230                            is defined in <sys/utsname.h>.
 231 
 232 
 233        prcred_t
 234                            n_type: NT_PRCRED. This structure contains the
 235                            process credentials, including the real, saved, and
 236                            effective user and group IDs. The prcred_t
 237                            structure is defined in <sys/procfs.h>. Following
 238                            the structure is an optional array of supplementary
 239                            group IDs. The total number of supplementary group
 240                            IDs is given by the pr_ngroups member of the
 241                            prcred_t structure, and the structure includes
 242                            space for one supplementary group. If pr_ngroups is
 243                            greater than 1, there is pr_ngroups - 1 gid_t items
 244                            following the structure; otherwise, there is no
 245                            additional data.
 246 
 247 
 248        char array
 249                            n_type: NT_ZONENAME. This entry contains a string
 250                            which describes the name of the zone in which the
 251                            process was running. See zones(5). The information
 252                            is the same as provided by getzonenamebyid(3C) when
 253                            invoked with the numerical ID returned by
 254                            getzoneid(3C).
 255 
 256 
 257        prfdinfo_t
 258                            n_type: NT_FDINFO. This structure contains
 259                            information about any open file descriptors,
 260                            including the path, flags, and stat(2) information.
 261                            The prfdinfo_t structure is defined in
 262                            <sys/procfs.h>.
 263 
 264 
 265        struct ssd array
 266                            n_type: NT_LDT. This entry is present only on an
 267                            32-bit x86 machine and only if the process has set
 268                            up a Local Descriptor Table (LDT). It contains an
 269                            array of structures of type struct ssd, each of
 270                            which was typically used to set up the %gs segment
 271                            register to be used to fetch the address of the
 272                            current thread information structure in a
 273                            multithreaded process. The ssd structure is defined
 274                            in <sys/sysi86.h>.
 275 
 276 
 277        core_content_t
 278                            n_type: NT_CONTENT. This optional entry indicates
 279                            which parts of the process image are specified to
 280                            be included in the core file. See coreadm(1M).
 281 
 282 
 283 
 284        Following these entries, for each active and zombie LWP in the process,
 285        the new NOTE segment contains an entry with an lwpsinfo_t structure
 286        plus, for a non-zombie LWP, an entry with an lwpstatus_t structure,
 287        plus other optionally-present entries describing the LWP, as follows. A
 288        zombie LWP is a non-detached LWP that has terminated but has not yet
 289        been reaped by another LWP in the same process.
 290 
 291        lwpsinfo_t
 292                       n_type: NT_LWPSINFO. This structure contains information
 293                       of interest to the ps(1) command, such as LWP status,
 294                       CPU usage, nice value, LWP-ID, and so forth. The
 295                       lwpsinfo_t structure is defined in <sys/procfs.h>. This
 296                       is the only entry present for a zombie LWP.
 297 
 298 
 299        lwpstatus_t
 300                       n_type: NT_LWPSTATUS. This structure contains things of
 301                       interest to a debugger from the operating system, such
 302                       as the general registers, the floating point registers,
 303                       state, reason for stopping, LWP-ID, and so forth. The
 304                       lwpstatus_t structure is defined in <sys/procfs.h>>.
 305 
 306 
 307        gwindows_t
 308                       n_type: NT_GWINDOWS. This entry is present only on a
 309                       SPARC machine and only if the system was unable to flush
 310                       all of the register windows to the stack. It contains
 311                       all of the unspilled register windows. The gwindows_t
 312                       structure is defined in <sys/regset.h>.
 313 
 314 
 315        prxregset_t
 316                       n_type: NT_PRXREG. This entry is present only if the
 317                       machine has extra register state associated with it. It
 318                       contains the extra register state.  The prxregset_t
 319                       structure is defined in <sys/procfs_isa.h>.
 320 
 321 
 322        asrset_t
 323                       n_type: NT_ASRS. This entry is present only on a SPARC
 324                       V9 machine and only if the process is a 64-bit process.
 325                       It contains the ancillary state registers for the LWP.
 326                       The asrset_t structure is defined in <sys/regset.h>.
 327 
 328 
 329        psinfo_t
 330                       n_type: NT_SPYMASTER. This entry is present only for an
 331                       agent LWP and contains the psinfo_t of the process that
 332                       created the agent LWP. See the proc(4) description of
 333                       the spymaster entry for more details.
 334 
 335 
 336        prsecflags_t
 337                       n_type: NT_SECFLAGS.  This entry contains the process
 338                       security-flags, see security-flags(5), proc(4), and
 339                       psecflags(1M) for more information.
 340 
 341 
 342 
 343        Depending on the coreadm(1M) settings, the section header of an ELF
 344        core file can contain entries for CTF, symbol table, and string table
 345        sections. The sh_addr fields are set to the base address of the first
 346        mapping of the load object that they came from to. This can be used to
 347        match those sections with the corresponding load object.
 348 
 349 
 350        The size of the core file created by a process can be controlled by the
 351        user (see getrlimit(2)).
 352 
 353 SEE ALSO
 354        elfdump(1), gcore(1), mdb(1), proc(1), ps(1), coreadm(1M),
 355        getrlimit(2), setrlimit(2), setuid(2), sysinfo(2), uname(2),
 356        getzonenamebyid(3C), getzoneid(3C), elf(3ELF), signal.h(3HEAD),
 357        a.out(4), proc(4), zones(5), security-flags(5)
 358 
 359 
 360        ANSI C Programmer's Guide
 361 
 362 
 363 
 364                                  June 6, 2016                          CORE(4)