Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
core(4)								       core(4)

NAME
       core - process core file

       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, regardless of	the UID	of the
	    process dumping core, the attempt to write the global core file is
	    made as the	superuser.

	 o  Core files owned by	the user nobody	will not be produced.  For ex-
	    ample, core	files generated	for the	superuser on an	NFS  directory
	    are	owned by nobody	and are, therefore, not	written.

	 o  If	the  core file pattern expands to a pathname that contains in-
	    termediate directory components that do not	exist. For example, if
	    the	 global	 pattern is set	to /var/core/%n/core.%p, and no	direc-
	    tory /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 can be	excluded due to	the core file content settings
       (see coreadm(1M)), or due to some failure. If the data is excluded  be-
       cause   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 <sys/elf.h>. The first NOTE	segment	exists for binary com-
       patibility with old programs that deal with  core  files.  It  contains
       structures defined in <sys/old_procfs.h>. 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
			       <sys/old_procfs.h>.

       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 op-
			       erating	system	as  startup information	to the
			       dynamic linker. Auxiliary vector	information is
			       defined in <sys/auxv.h>.

       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 de-
       scribing	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 <sys/old_procfs.h>.

       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 prf-
			       pregset_t    structure	 is	defined	    in
			       <sys/procfs_isa.h>.

       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 <sys/regset.h>.

       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
			       <sys/procfs_isa.h>.

       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 in-
			       formation 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
			       <sys/procfs.h>.

       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 <sys/procfs.h>.

       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 op-
			       erating system as startup  information  to  the
			       dynamic linker. Auxiliary vector	information is
			       defined in <sys/auxv.h>.

       struct utsname	       n_type: NT_UTSNAME. This	structure contains the
			       system  information  that  would	 have been re-
			       turned to the process if	it had performed a un-
			       ame(2)  system  call prior to dumping core. The
			       utsname	structure  is  defined	 in   <sys/ut-
			       sname.h>.

       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 <aasys/procfs.h>.  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  machine and only if the process has
			       set up a	Local Descriptor Table (LDT). It  con-
			       tains  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 <sys/sysi86.h>.

       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 <sys/procfs.h>. 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 <sys/procfs.h>>.

       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 <sys/regset.h>.

       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 <sys/procfs_isa.h>.

       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 <sys/regset.h>.

       Depending on the	coreadm(1M) settings, the section  header  of  an  ELF
       core  file  can contain entries for CTF,	symbol table, and string table
       sections. The sh_addr fields are	set to the base	address	of  the	 first
       mapping	of the load object that	they came from to. This	can be used to
       match those sections with the corresponding load	object.

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

       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

				  9 Aug	2005			       core(4)

NAME

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=core&sektion=4&manpath=SunOS+5.10>

home | help