DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

core(FP)


core -- Format of core image file

Description

The Operating System writes out a core image of a terminated process when various errors occur. See sigaction(S) for a list of reasons; the most common errors are memory violations, illegal instructions, and user-generated quit signals. The core image is called core and is written in the process' working directory (provided it can be; normal access controls apply). Use the file(C) command to report the command line that produced the core file and the time that command line was invoked.

A process with an effective user (group) ID different from the real user (group) ID will not produce a core image. If a file named core already exists in the process' working directory and is not a regular file or has links, no core image is produced.

The core image contains all mutable portions of the process' virtual address space plus information from the system about the state of the process. If the text segment is read-only and shared, or separated from data space, it is not dumped. Attached shared memory, shared data, and shared library data are dumped.

The core file is logically divided into a series of sections. A section either describes the core file, contains a copy of the contents of a kernel data structure, or contains a copy of the contents of the process' memory at the time of the dump.

Each section consists of a header describing the section, optional additional information about the section's contents, and the section's contents. Consecutive sections may not be physically adjacent. Whilst any optional information physically follows the header, the contents may not. The header contains the size and offset of its contents. The headers themselves form a chain.

The section header is defined in <sys/paccess.h>:

   struct coresecthead {
      uchar_t     cs_stype;  /* Type of section (CORES_xxx) */
      uchar_t     cs_hsize;  /* Size (bytes) of section header */
      ushort      cs_osize;  /* Size (bytes) of optional info */
      union {
         struct {
            short csxp_rflg; /* Associated pregion's p_flags */
            short csxp_rtyp; /* Associated pregion's p_type */
         } csx_preg;
         ulong_t  csx_magic; /* COREMAGIC_xxx for MAGIC, OFFSETS */
      } cs_x;
      ulong_t     cs_vaddr;  /* Virtual address of contents */
      ulong_t     cs_vsize;  /* Size (bytes) of contents */
      long        cs_sseek;  /* Offset of this section's contents */
      long        cs_hseek;  /* Offset of next section's header */
   };
Each coresecthead structure in a core file contains:

cs_stype
The type of section dumped (see list below).

cs_hsize
The size, in bytes, of this core section header (coresecthead structure) including this size field itself.

cs_x
The format and contents of this union depend on the section's type as described below.

cs_osize
The size, in bytes, of the optional information about this core section's contents. The format of this optional additional information depends on the type of information contained in the section. The optional information starts immediately after this coresecthead structure in the core file.

cs_vaddr
The virtual address of this section's contents in the appropriate address space.

cs_vsize
The size, in bytes, of this section's contents.

cs_sseek
The offset (from zero) in the core file of this section's contents. A section's contents may not be physically adjacent to its header and additional information.

cs_hseek
The offset (from zero) in the core file of the ``next'' section. A zero or negative offset ends the chain. The logical order of sections in a core file is unrelated to the numerical values of the section header offsets.

Should a future release or update of the system require an expanded coresecthead structure, the additional fields will be added at the end of the structure. Programs should therefore not assume that sizeof(struct coresecthead) bytes were written to the core file; the cs_hsize field contains the number of bytes that were written.

The defined cs_stype section types include:


CORES_MAGIC
If this section is dumped, it is always at offset zero. This section is always dumped unless the CORES_UAREA section (described below) could not be dumped. The cs_x.csx_magic field is either COREMAGIC_NUMBER (this core file is believed valid) or COREMAGIC_INVALID (the core file may be corrupt). This section always heads the chain, and the ``next'' section in the chain for valid core files is always the CORES_OFFSETS section (described below). The additional information is a byte containing the last error encountered when writing the core file (as defined in <sys/errno.h>), and the contents of this section are always the null terminated name of the core file (which is always `` core '' in current releases of the Operating System).

CORES_UAREA
The system's user structure (defined in <sys/user.h>) for the process. This section is always present in a valid core file. No additional information is currently defined for this section. The cs_x union is reserved for possible future use.

CORES_PREGION
Memory attached to the process' virtual address space. The cs_x.csx_preg.csxp_rtyp and cs_x.csx_preg.csxp_rflg fields contain the pregion structure's p_type and p_flags fields (respectively) for the memory attached to the process at virtual address cs_vaddr. Those fields are defined in <sys/region.h>. The type of memory is given by cs_x.csx_preg.csxp_rtyp and includes PT_STACK (the process' stack), PT_DATA (the process' data), PT_SHMEM (an attached shared memory segment), and PT_LIBDAT (data associated with a shared library). Text (PT_TEXT and PT_LIBTXT) are never dumped. Only PT_SHMEM memory has additional information -- the shmds_id structure associated with this shared memory (defined in <sys/shm.h>). No other additional information is currently defined for this section.

CORES_PROC
The system's proc structure as defined in <sys/proc.h> for this process. There is at most one such section in a valid core file. No additional information is currently defined for this section. The cs_x union is reserved for possible future use.

CORES_ITIMER
The process' interval timer values as an array of itimerval structures (defined in <sys/itimer.h>). There is at most one such section in a valid core file. No additional information is currently defined for this section. The cs_x union is reserved for possible future use.

CORES_SCOUTSNAME
The system's scoutsname structure defined in <sys/utsname.h>. There is at most one such section in a valid core file. No additional information is currently defined for this section. The cs_x union is reserved for possible future use.

CORES_OFFSETS
Always the physically last section in a valid core file, this section contains the process' coreoffsets structure defined in <sys/paccess.h>. The additional information's size is always an exact number of longwords. The last longword is always the core file offset (from zero) of this section's header, and the next-to-last longword is the number of sections in the chain (excluding the CORES_MAGIC section but including this CORES_OFFSET section itself). Only the coresecthead section may preceed this section in the chain, so this section may be considered the head of the chain. No additional longwords are currently defined. Immediately following these longwords is the coreoffsets structure (also defined in <sys/paccess.h>). That structure is always at the very end of a valid core file. The cs_x.csx_magic field is either COREMAGIC_NUMBER (the core file is believed valid) or COREMAGIC_INVALID (the core file may be corrupt).

The last longword of the coreoffsets structure is always the size of that structure itself (including that last longword):

   struct coreoffsets {
      uoff u_info;       /* interface version (C_VERSION) */
      uoff u_user;       /* offset of upage in core file */
      uoff u_ldt;        /* offset of ldt in core file  */
      uoff u_data;       /* offset of data in core file */
      uoff u_stack;      /* offset of stack in core file */
      uoff u_usize;      /* size of uarea */
      uoff u_uaddr;      /* kernel virtual address of uarea  */
      uoff u_ar0;        /* user register save area pointer */
      uoff u_fps;        /* floating point save area  */
      uoff u_fper;       /* 2.3 field */
      uoff u_fpemul;     /* separate emulator save area  */  
      uoff u_fpvalid;    /* valid save fpstate */
      uoff u_weitek;     /* flag indicating weitek usage */
      uoff u_weitek_reg; /* weitek save area */
      uoff u_ssize;      /* stack size */
      uoff u_dsize;      /* data size  */
      uoff u_tsize;      /* text size  */
      uoff u_comm;       /* name of executable */
      uoff u_ldtlimit;   /* size of ldt   */
      uoff u_sub;        /* stack upper  bound */
      uoff u_sdata;      /* 3.2 u_exdata.ux_datorg  */
      uoff u_mag;        /* u_exdata.ux_mag  */
      uoff u_sigreturn;       
      uoff u_signal;
      uoff uvstack;      /* virtual address of stack top */
      uoff uvtext;       /* virtual address of text */
      uoff size;         /* size of this structure */
   };
Some of these fields contain information about the core file's layout:

u_info
Format version number. The current version is C_VERSION, which is 2. This manual page describes the version 2 format.

u_user
Offset (from zero) in the core file of the process' user structure, which is the contents of the CORES_UAREA section. This field is identical to that section's cs_sseek

u_ldt
Offset from the beginning of the CORES_UAREA section's contents (that is, from the beginning of the dumped user structure) of the process' LDT. The number of entries in the table varies and is given by the u_ldtlimit field in the user structure, whose offset is given by the u_ldtlimit field of the coreoffsets structure.

u_data
Offset (from zero) in the core file of the PT_DATA CORES_PREGION section containing the data and BSS loaded from the process' executable file. This field is identical to that section's cs_sseek.

u_stack
Offset (from zero) in the core file of the process' stack, which is the contents of the PT_STACK CORES_PREGION section. This field is identical to that section's cs_sseek.

u_usize
The size, in bytes, of the process' user -area. This field is identical to the CORES_UAREA section's cs_vsize.

u_uaddr
The kernel's virtual address of the process' user structure. This field is identical to the CORES_UAREA section's cs_vaddr.

u_fper
Obsolete; always zero.

uvstack
The numerically highest virtual address of the process' stack. For historical reasons this does not include the last longword of the stack.

uvtext
The numerically lowest virtual address of the process' text.

The other fields in the coreoffsets structure are the offset (in bytes) from the beginning of the USERS_UAREA contents of the similarly-named fields in the dumped user structure:

Structure  
coreoffsets field user offset Comments
u_ar0 u_ar0 Kernel virtual address of process' registers
u_fps u_fps Saved FPU hardware state
u_fpemul u_fps Saved FPU emulator state
u_fpvalid u_fpvalid FPU state saved?
u_weitek u_weitek  
u_weitek_reg u_weitek_reg  
u_ssize u_ssize Pages of process' stack in core
u_dsize u_dsize Pages of process' data in core
u_tsize u_tsize Pages of process' separate/shared text
u_comm u_comm Executable file's basename
u_ldtlimit u_ldtlimit  
u_sub u_sub Lowest address in process' stack
u_sdata u_exdata.ux_datorg Process' data virtual address
u_mag u_exdata.ux_mag Executable's magic number
u_sigreturn u_sigreturn  
u_signal u_signal[0]  

               Structure
 coreoffsets field      user offset                         Comments
   u_ar0             u_ar0                Kernel virtual address of process' registers
   u_fps             u_fps                Saved FPU hardware state
   u_fpemul          u_fps                Saved FPU emulator state
   u_fpvalid         u_fpvalid            FPU state saved?
   u_weitek          u_weitek
   u_weitek_reg      u_weitek_reg
   u_ssize           u_ssize              Pages of process' stack in core
   u_dsize           u_dsize              Pages of process' data in core
   u_tsize           u_tsize              Pages of process' separate/shared text
   u_comm            u_comm               Executable file's basename
   u_ldtlimit        u_ldtlimit
   u_sub             u_sub                Lowest address in process' stack
   u_sdata           u_exdata.ux_datorg   Process' data virtual address
   u_mag             u_exdata.ux_mag      Executable's magic number
   u_sigreturn       u_sigreturn
   u_signal          u_signal[0]

The size of the core file never exceeds the process' ulimit(S) in effect at the time of the core dump. If the ulimit is insufficient to contain the entire user and coreoffsets structures plus their corresponding coresecthead headers, nothing is written to the core file. If the ulimit is too small to contain both the process' stack (PT_STACK) and data (PT_DATA) memory, only the stack is written (plus the user and coreoffsets structures); if the ulimit is too small to contain the stack, then only the user and coreoffsets sections are written. Other sections are squeezed in as the ulimit permits.

Notes

Version 1 core files contain only the first two pages of the user structure (always at offset zero), the process' stack and data memory, and the coreoffsets structure (always at the end of the core file). No other memory or information are present, and no coresecthead structures are dumped. In particular, there is no CORES_MAGIC section in a genuine version 1 core file.

The u_ldt field of the coreoffsets structure in a genuine version 1 core file may point to memory which was not actually dumped, or which was only partially dumped.

The version 2 core file format is designed so most programs expecting a version 1 core file should continue to work unchanged, although they will not be able to access the additional information present in version 2 files. However, some utilities require version 1 core files. The corex(C) command converts a version 2 core file into its version 1 equivalent. The LDT in the converted core file may -- like genuine version 1 core files -- either not be dumped or be only partially dumped.

The CORES_MAGIC section actually overlays the beginning of the CORES_UAREA section's contents so that, like version 1 core files, the user structure in version 2 core files starts at offset zero. There is no data of consequence in the overlaid bytes, being the furthermost extent of the kernel's stack.

The u_comm string in the user structure is not necessarily null-terminated.

The u_ar0 field in the coreoffsets structure is the offset in the CORES_UAREA section of the kernel's virtual address which in turn points to the process' registers. That offset is not the offset of the saved registers themselves. The dumped u_ar0 kernel virtual address refers to core dumped someplace in the CORES_UAREA section; the pointed to dumped core is arranged as described in <sys/regs.h>.

See also

Intro(S), adb(CP), corex(C), dbxtra(CP), dbXtra(CP), file(C), sdb(CP), sdget(S), setuid(S), shmctl(S), sigaction(S), signal(M), signal(S), termio(M), ulimit(S)
© 2003 File Formats for Programming (FP)
SCO OpenServer Release 5.0.7 -- 11 February 2003