unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

core(4)                          File Formats                          core(4)



NAME
       core - process core file

DESCRIPTION
       The  operating  system  writes  out  a core file for a process when the
       process is terminated due to receiving certain signals. A core file  is
       a  disk  copy  of the contents of the process address space at the time
       the process received the  signal,  along  with  additional  information
       about  the  state of the process. This information can be consumed by a
       debugger. Core files can also be generated  by  applying  the  gcore(1)
       utility to a running process.

       Typically,  core files are produced following abnormal termination of a
       process resulting from a bug in the corresponding application. Whatever
       the  cause, the core file itself provides invaluable information to the
       programmer or support engineer to aid in diagnosing  the  problem.  The
       core file can be inspected using a debugger such as dbx(1) or mdb(1) or
       by applying one of the proc(1) tools.

       The operating system attempts to create up to two core files  for  each
       abnormally  terminating  process, using a global core file name pattern
       and a per-process core file name pattern. These patterns  are  expanded
       to  determine the pathname of the resulting core files, and can be con-
       figured by coreadm(1M). By default, the global  core  file  pattern  is
       disabled  and not used, and the per-process core file pattern is set to
       core. Therefore, by default, the operating system attempts to create  a
       core file named core in the process's current working directory.

       A  process terminates and produces a core file whenever it receives one
       of the signals whose default disposition is to cause a core  dump.  The
       list  of signals that result in generating a core file is shown in sig-
       nal.h(3HEAD). Therefore, a process might not produce a core file if  it
       has blocked or modified the behavior of the corresponding signal. Addi-
       tionally, no core dump can be created under the following conditions:

         o  If normal file and directory access permissions prevent  the  cre-
            ation or modification of the per-process core file pathname by the
            current process user and group ID. This test does not apply to the
            global  core  file pathname because the global core file is always
            written as the superuser.

         o  If the core file pattern  expands  to  a  pathname  that  contains
            intermediate  directory components that do not exist. For example,
            if the global pattern  is  set  to  /var/core/%n/core.%p,  and  no
            directory  /var/core/`uname  -n`  has been created, no global core
            files are produced.

         o  If the destination directory is  part  of  a  filesystem  that  is
            mounted read-only.

         o  If  the  resource  limit  RLIMIT_CORE  has  been  set to 0 for the
            process, no per-process core file is  produced.   Refer  to  setr-
            limit(2) and ulimit(1) for more information on resource limits.

         o  If  the core file name already exists in the destination directory
            and is not a regular file (that is, is a symlink, block or charac-
            ter special-file, and so forth).

         o  If  the  kernel cannot open the destination file O_EXCL, which can
            occur if same file is being created by another process  simultane-
            ously.

         o  If the process's effective user ID is different from its real user
            ID or if its effective group ID is different from its  real  group
            ID.   Similarly, set-user-ID and set-group-ID programs do not pro-
            duce core files as this could potentially compromise system  secu-
            rity. These processes can be explicitly granted permission to pro-
            duce core files using coreadm(1M), at the risk of exposing  secure
            information.


       The  core file contains all the process information pertinent to debug-
       ging: contents of hardware registers, process status, and process data.
       The format of a core file is object file specific.

       For  ELF executable programs (see a.out(4)), the core file generated is
       also an ELF file, containing ELF program and file headers.  The  e_type
       field  in the file header has type ET_CORE. The program header contains
       an entry for every segment that was part of the process address  space,
       including shared library segments.  The contents of the mappings speci-
       fied by coreadm(1M) are also part  of  the  core  image.  Each  program
       header  has  its p_memsz field set to the size of the mapping. The pro-
       gram headers that represent mappings whose data is included in the core
       file  have  their  p_filesz  field  set  the same as p_memsz, otherwise
       p_filesz is zero.

       A mapping's data may be excluded due to the core file content  settings
       (see  coreadm(1M)),  or  due  to  some failure. If the data is excluded
       because  of  a  failure,  the  program  header  entry  will  have   the
       PF_SUNW_FAILURE flag set in its p_flags field.

       The  program  headers  of an ELF core file also contain entries for two
       NOTE segments, each containing several note entries as described below.
       The  note entry header and core file note type (n_type) definitions are
       contained in <&lt;sys/elf.h>&gt;. The first NOTE segment exists for binary com-
       patibility  with  old  programs  that deal with core files. It contains
       structures defined in <&lt;sys/old_procfs.h>&gt;. New programs should recognize
       and  skip this NOTE segment, advancing instead to the new NOTE segment.
       The old NOTE segment is deleted from core files in a future release.

       The old NOTE segment contains the following  entries.  Each  has  entry
       name "CORE" and presents the contents of a system structure:

       prpsinfo_t              n_type: NT_PRPSINFO. This entry contains infor-
                               mation of interest to the ps(1)  command,  such
                               as  process  status,  CPU  usage, "nice" value,
                               controlling terminal, user-ID, process-ID,  the
                               name  of  the  executable,  and  so  forth. The
                               prpsinfo_t    structure    is    defined     in
                               <&lt;sys/old_procfs.h>&gt;.



       char array              n_type:  NT_PLATFORM.  This  entry  contains  a
                               string describing the  specific  model  of  the
                               hardware  platform  on which this core file was
                               created. This information is the same  as  pro-
                               vided  by sysinfo(2) when invoked with the com-
                               mand SI_PLATFORM.



       auxv_t array            n_type: NT_AUXV. This entry contains the  array
                               of  auxv_t  structures  that  was passed by the
                               operating system as startup information to  the
                               dynamic linker. Auxiliary vector information is
                               defined in <&lt;sys/auxv.h>&gt;.



       Following these entries,  for  each  active  (non-zombie)  light-weight
       process  (LWP)  in  the process, the old NOTE segment contains an entry
       with a prstatus_t  structure,  plus  other  optionally-present  entries
       describing the LWP, as follows:

       prstatus_t              n_type:  NT_PRSTATUS.  This  structure contains
                               things of interest to a debugger from the oper-
                               ating  system,  such  as the general registers,
                               signal dispositions, state,  reason  for  stop-
                               ping,  process-ID, and so forth. The prstatus_t
                               structure is defined in <&lt;sys/old_procfs.h>&gt;.



       prfpregset_t            n_type: NT_PRFPREG. This entry is present  only
                               if  the  LWP  used the floating-point hardware.
                               It contains the floating-point  registers.  The
                               prfpregset_t    structure    is    defined   in
                               <&lt;sys/procfs_isa.h>&gt;.



       gwindows_t              n_type: NT_GWINDOWS. This entry is present only
                               on  a  SPARC machine and only if the system was
                               unable to flush all of the register windows  to
                               the  stack.  It  contains  all of the unspilled
                               register windows. The gwindows_t  structure  is
                               defined in <&lt;sys/regset.h>&gt;.



       prxregset_t             n_type:  NT_PRXREG.  This entry is present only
                               if the machine has extra register state associ-
                               ated  with  it.  It contains the extra register
                               state. The prxregset_t structure is defined  in
                               <&lt;sys/procfs_isa.h>&gt;.



       The  new  NOTE  segment  contains the following entries. Each has entry
       name "CORE" and presents the contents of a system structure:

       psinfo_t                n_type:  NT_PSINFO.  This  structure   contains
                               information  of  interest to the ps(1) command,
                               such  as  process  status,  CPU  usage,  "nice"
                               value,  controlling terminal, user-ID, process-
                               ID, the name of the executable, and  so  forth.
                               The    psinfo_t   structure   is   defined   in
                               <&lt;sys/procfs.h>&gt;.



       pstatus_t               n_type:  NT_PSTATUS.  This  structure  contains
                               things of interest to a debugger from the oper-
                               ating system, such as pending  signals,  state,
                               process-ID,  and so forth. The pstatus_t struc-
                               ture is defined in <&lt;sys/procfs.h>&gt;.



       char array              n_type:  NT_PLATFORM.  This  entry  contains  a
                               string  describing  the  specific  model of the
                               hardware platform on which this core  file  was
                               created.  This  information is the same as pro-
                               vided by sysinfo(2) when invoked with the  com-
                               mand SI_PLATFORM.



       auxv_t array            n_type:  NT_AUXV. This entry contains the array
                               of auxv_t structures that  was  passed  by  the
                               operating  system as startup information to the
                               dynamic linker. Auxiliary vector information is
                               defined in <&lt;sys/auxv.h>&gt;.



       struct utsname          n_type: NT_UTSNAME. This structure contains the
                               system  information  that   would   have   been
                               returned  to  the process if it had performed a
                               uname(2) system call prior to dumping core. The
                               utsname     structure     is     defined     in
                               <&lt;sys/utsname.h>&gt;.



       prcred_t                n_type: NT_PRCRED. This structure contains  the
                               process credentials, including the real, saved,
                               and effective user and group IDs. The  prcred_t
                               structure  is defined in <&lt;aasys/procfs.h>&gt;. Fol-
                               lowing the structure is an  optional  array  of
                               supplementary  group  IDs.  The total number of
                               supplementary  group  IDs  is  given   by   the
                               pr_ngroups  member  of  the prcred_t structure,
                               and the structure includes space for  one  sup-
                               plementary group. If pr_ngroups is greater than
                               1, there is pr_ngroups - 1 gid_t items  follow-
                               ing the structure; otherwise, there is no addi-
                               tional data.



       char array              n_type:  NT_ZONENAME.  This  entry  contains  a
                               string  which describes the name of the zone in
                               which the process was  running.  See  zones(5).
                               The information is the same as provided by get-
                               zonenamebyid(3C) when invoked with the  numeri-
                               cal ID returned by getzoneid(3C).



       struct ssd array        n_type:  NT_LDT.  This entry is present only on
                               an 32-bit x86 machine and only if  the  process
                               has  set  up a Local Descriptor Table (LDT). It
                               contains an array of structures of type  struct
                               ssd, each of which was typically used to set up
                               the %gs segment register to be  used  to  fetch
                               the  address  of the current thread information
                               structure in a multithreaded process.  The  ssd
                               structure is defined in <&lt;sys/sysi86.h>&gt;.



       core_content_t          n_type:  NT_CONTENT.  This optional entry indi-
                               cates which parts  of  the  process  image  are
                               specified  to be included in the core file. See
                               coreadm(1M).



       Following these entries, for each active and zombie LWP in the process,
       the  new  NOTE  segment  contains an entry with an lwpsinfo_t structure
       plus, for a non-zombie LWP, an entry  with  an  lwpstatus_t  structure,
       plus other optionally-present entries describing the LWP, as follows. A
       zombie LWP is a non-detached LWP that has terminated but  has  not  yet
       been reaped by another LWP in the same process.

       lwpsinfo_t      n_type:  NT_LWPSINFO.  This structure contains informa-
                       tion of interest to the ps(1) command, such as LWP sta-
                       tus, CPU usage, "nice" value, LWP-ID, and so forth. The
                       lwpsinfo_t structure is defined in <&lt;sys/procfs.h>&gt;. This
                       is the only entry present for a zombie LWP.



       lwpstatus_t     n_type: NT_LWPSTATUS. This structure contains things of
                       interest to a debugger from the operating system,  such
                       as the general registers, the floating point registers,
                       state, reason for stopping, LWP-ID, and so  forth.  The
                       lwpstatus_t structure is defined in <&lt;sys/procfs.h>&gt;>&gt;.



       gwindows_t      n_type:  NT_GWINDOWS.  This  entry is present only on a
                       SPARC machine and only if  the  system  was  unable  to
                       flush all of the register windows to the stack. It con-
                       tains all of the unspilled register windows. The  gwin-
                       dows_t structure is defined in <&lt;sys/regset.h>&gt;.



       prxregset_t     n_type:  NT_PRXREG.  This  entry is present only if the
                       machine has extra register state associated with it. It
                       contains  the  extra  register  state.  The prxregset_t
                       structure is defined in <&lt;sys/procfs_isa.h>&gt;.



       asrset_t        n_type: NT_ASRS. This entry is present only on a  SPARC
                       V9 machine and only if the process is a 64-bit process.
                       It contains the ancillary state registers for the  LWP.
                       The asrset_t structure is defined in <&lt;sys/regset.h>&gt;.



       The size of the core file created by a process may be controlled by the
       user (see getrlimit(2)).

SEE ALSO
       gcore(1), mdb(1),  proc(1),  ps(1),  coreadm(1M),  getrlimit(2),  setr-
       limit(2),  setuid(2),  sysinfo(2),  uname(2), getzonenamebyid(3C), get-
       zoneid(3C), elf(3ELF), signal.h(3HEAD), a.out(4), proc(4), zones(5)

       ANSI C Programmer's Guide



SunOS 5.10                        18 Feb 2004                          core(4)