core(FP) 6 January 1993 core(FP) Name 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 con- trols apply). 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 ker- nel 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 addi- tional information about the section's contents, and the section's con- tents. 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 struc- ture) 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 informa- tion depends on the type of information contained in the section. The optional information starts immediately after this coresecthead struc- ture 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 cshsize field contains the number of bytes that were written. The defined csstype section types include: CORES_MAGIC If this section is dumped, it is always at offset zero. This section is always dumped unless the CORESUAREA section (described below) could not be dumped. The csx.csxmagic field is either COREMAGICNUMBER (this core file is believed valid) or COREMAGICINVALID (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 CORESOFFSETS 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 con- tents 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 csx union is reserved for possible future use. CORES_PREGION Memory attached to the process' virtual address space. The csx.csxpreg.csxprtyp and csx.csxpreg.csxprflg fields contain the pregion structure's ptype and pflags fields (respectively) for the memory attached to the process at virtual address csvaddr. Those fields are defined in <sys/region.h>. The type of memory is given by csx.csxpreg.csxprtyp and includes PTSTACK (the process' stack), PTDATA (the process' data), PTSHMEM (an attached shared memory seg- ment), and PTLIBDAT (data associated with a shared library). Text (PTTEXT and PTLIBTXT) are never dumped. Only PTSHMEM memory has additional information -- the shmdsid structure associated with this shared memory (defined in <sys/shm.h>). No other additional informa- tion is currently defined for this section. CORES_PROC The system's proc structure as defined in <sys/proc.h> for this pro- cess. There is at most one such section in a valid core file. No additional information is currently defined for this section. The csx 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 csx 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 in- formation is currently defined for this section. The csx 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 CORESMAGIC section but including this CORESOFFSET section itself). Only the coresect- head 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 struc- ture is always at the very end of a valid core file. The csx.csxmagic field is either COREMAGICNUMBER (the core file is believed valid) or COREMAGICINVALID (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 CVERSION, 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 CORESUAREA section. This field is identical to that section's cssseek u_ldt Offset from the beginning of the CORESUAREA 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 uldtlimit field in the user structure, whose offset is given by the uldtlimit field of the coreoffsets structure. u_data Offset (from zero) in the core file of the PTDATA CORESPREGION sec- tion containing the data and BSS loaded from the process' executable file. This field is identical to that section's cssseek. u_stack Offset (from zero) in the core file of the process' stack, which is the contents of the PTSTACK CORESPREGION section. This field is identical to that section's cssseek. u_usize The size, in bytes, of the process' user -area. This field is identi- cal to the CORESUAREA section's csvsize. u_uaddr The kernel's virtual address of the process' user structure. This field is identical to the CORESUAREA section's csvaddr. 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 USERSUAREA contents of the similarly-named fields in the dumped user structure: Structure coreoffsets user Comments field offset ____________________________________________________________________________________ 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 (PTSTACK) and data (PTDATA) 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 struc- ture (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 CORESMAGIC section in a genuine ver- sion 1 core file. The uldt 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 ver- sion 1 core files -- either not be dumped or be only partially dumped. The CORESMAGIC section actually overlays the beginning of the CORESUAREA 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 ucomm string in the user structure is not necessarily null- terminated. The uar0 field in the coreoffsets structure is the offset in the CORESUAREA 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 uar0 kernel virtual address refers to core dumped someplace in the CORESUAREA section; the pointed to dumped core is arranged as described in <sys/regs.h>. See also Intro(S), adb(CP), codeview(CP), corex(C), dbxtra(CP), dbXtra(CP), sdb(CP), sdget(S), setuid(S), shmctl(S), sigaction(S), signal(S), termio(M), ulimit(S)