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

FreeBSD Manual Pages

  
 
  

home | help
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 the	receipt	of  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  will	terminate and produce 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
       signal(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 super-user.

	  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  di-
	     rectory  /var/core/`uname	-n`  has  been created,	no global core
	     files will	be 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. Refer to setrlimit(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	 char-
	     acter 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
	     produce core files	as this	could  potentially  compromise	system
	     security. These processes can be explicitly granted permission to
	     produce core files	using coreadm(1M), at the risk of exposing se-
	     cure 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 writable seg-
       ments are also part of the core image.

       The program header of an	ELF core file also contains  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 will be deleted from core files in a future re-
       lease.

       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 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 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 provided by sys-
	     info(2) when invoked with the command SI_PLATFORM.

       auxv_t array
	     n_type: NT_AUXV. This entry contains the array of	auxv_t	struc-
	     tures that	was passed by the operating system as startup informa-
	     tion to the dynamic linker. Auxiliary vector information  is  de-
	     fined in <sys/auxv.h>.

       Following  these	 entries,  for	each 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 operating system, such as the general reg-
	     isters, signal dispositions, state, reason	for stopping, 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 reg-
	     isters.   The    prfpregset_t    structure	   is	 defined    in
	     <sys/procfs_isa.h>.

       gwindows_t
	     n_type:  NT_GWINDOWS.  This  entry	is present only	on a SPARC ma-
	     chine and only if the system was unable to	flush all of the  reg-
	     ister windows to the stack. It contains all of the	unspilled reg-
	     ister  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 associated 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 information of	inter-
	     est 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  de-
	     fined in <sys/procfs.h>.

       pstatus_t
	     n_type: NT_PSTATUS. This structure	contains things	of interest to
	     a debugger	from the operating system, such	 as  pending  signals,
	     state,  process-ID,  and so forth.	The pstatus_t structure	is de-
	     fined 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  provided  by  sys-
	     info(2) when invoked with the command SI_PLATFORM.

       auxv_t array
	     n_type:  NT_AUXV.	This entry contains the	array of auxv_t	struc-
	     tures that	was passed by the operating system as startup informa-
	     tion  to  the dynamic linker. Auxiliary vector information	is de-
	     fined in <sys/auxv.h>.

       struct utsname
	     n_type: NT_UTSNAME. This structure	contains the  system  informa-
	     tion  that	would have been	returned to the	process	if it had per-
	     formed a uname(2) system call prior to dumping core. The  utsname
	     structure is defined in <sys/utsname.h>.

       prcred_t
	     n_type:  NT_PRCRED.  This	structure contains the process creden-
	     tials, including the real,	saved, and effective  user  and	 group
	     IDs. The prcred_t structure is defined in <sys/procfs.h>. Follow-
	     ing 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	supplementary group.  If pr_ngroups is
	     greater than 1, there will	be pr_ngroups -	1 gid_t	items  follow-
	     ing the structure;	otherwise, there will be no additional data.

       Following these entries,	for each LWP in	the process, the new NOTE seg-
       ment contains an	entry with an lwpsinfo_t structure plus	an entry  with
       an  lwpstatus_t	structure,  plus  other	optionally-present entries de-
       scribing	the LWP, as follows:

       lwpsinfo_t
	     n_type: NT_LWPSINFO. This structure contains information  of  in-
	     terest  to	 the  ps(1)  command,  such  as	LWP status, CPU	usage,
	     "nice" value, LWP-ID, and so forth. The lwpsinfo_t	 structure  is
	     defined in	<sys/procfs.h>.

       lwpstatus_t
	     n_type:  NT_LWPSTATUS. This structure contains things of interest
	     to	a debugger from	the operating system, such as the general reg-
	     isters, 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 ma-
	     chine and only if the system was unable to	flush all of the  reg-
	     ister windows to the stack. It contains all of the	unspilled reg-
	     ister  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 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 an-
	     cillary state registers for the LWP.  The asrset_t	 structure  is
	     defined in	<sys/regset.h>.

       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),	 elf(3ELF),  a.out(4),
       proc(4),	signal(3HEAD)

       ANSI C Programmer's Guide

SunOS 5.9			  2 Jan	2001			       core(4)

NAME | DESCRIPTION | SEE ALSO

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

home | help