share/man/man5/core.5

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)core.5      8.3 (Berkeley) 12/11/93
  29 .\" $FreeBSD: src/share/man/man5/core.5,v 1.8.2.5 2003/01/07 22:03:50 keramida Exp $
  30 .\" $DragonFly: src/share/man/man5/core.5,v 1.4 2006/05/26 19:39:40 swildner Exp $
  31 .\"
  32 .Dd January 9, 2002
  33 .Dt CORE 5
  34 .Os
  35 .Sh NAME
  36 .Nm core
  37 .Nd memory image file format
  38 .Sh SYNOPSIS
  39 .In sys/param.h
  40 .Sh DESCRIPTION
  41 A small number of signals which cause abnormal termination of a process
  42 also cause a record of the process's in-core state to be written
  43 to disk for later examination by one of the available debuggers.
  44 (See
  45 .Xr sigaction 2 . )
  46 This memory image is written to a file named by default
  47 .Nm programname.core
  48 in the working directory;
  49 provided the terminated process had write permission in the directory,
  50 and provided the abnormality did not cause
  51 a system crash.
  52 (In this event, the decision to save the core file is arbitrary, see
  53 .Xr savecore 8 . )
  54 .Pp
  55 The maximum size of a core file is limited by
  56 .Xr setrlimit 2 .
  57 Files which would be larger than the limit are not created.
  58 .Pp
  59 The name of the file is controlled via the
  60 .Xr sysctl 8
  61 variable
  62 .Va kern.corefile .
  63 The contents of this variable describes a filename to store
  64 the core image to.
  65 This filename can be absolute, or relative (which
  66 will resolve to the current working directory of the program
  67 generating it).
  68 Any sequence of
  69 .Em \&%N
  70 in this filename template will be replaced by the process name,
  71 .Em \&%P
  72 by the processes PID, and
  73 .Em \&%U
  74 by the UID.
  75 The name defaults to
  76 .Em \&%N.core ,
  77 yielding the traditional
  78 .Dx
  79 behaviour.
  80 .Pp
  81 By default, a process that changes user or group credentials whether
  82 real or effective will not create a corefile.
  83 This behaviour can be
  84 changed to generate a core dump by setting the
  85 .Xr sysctl 8
  86 variable
  87 .Va kern.sugid_coredump
  88 to 1.
  89 .Pp
  90 The core file consists of the
  91 .Fa u.
  92 area, whose size (in pages) is
  93 defined by the
  94 .Dv UPAGES
  95 manifest in the
  96 .In sys/param.h
  97 file.
  98 The
  99 .Fa u.
 100 area starts with a
 101 .Fa user
 102 structure as given in
 103 .In sys/user.h .
 104 The remainder of the core
 105 file consists of the data pages followed by
 106 the stack pages of the process image.
 107 The amount of data space image in the core
 108 file is given (in pages) by the
 109 variable
 110 .Fa u_dsize
 111 in the
 112 .Fa u.
 113 area.
 114 The amount of stack image in the core file is given (in pages) by the
 115 variable
 116 .Fa u_ssize
 117 in the
 118 .Fa u.
 119 area.
 120 The size of a ``page'' is given by the constant
 121 .Dv PAGE_SIZE
 122 (also from
 123 .In sys/param.h ) .
 124 .Sh EXAMPLES
 125 In order to store all core images in per-user private areas under
 126 .Pa /var/coredumps ,
 127 the following
 128 .Xr sysctl 8
 129 command can be used:
 130 .Pp
 131 .Dl sysctl kern.corefile="/var/coredumps/\&%U/\&%N.core"
 132 .Sh SEE ALSO
 133 .Xr gdb 1 ,
 134 .Xr kgdb 1 ,
 135 .Xr setrlimit 2 ,
 136 .Xr sigaction 2 ,
 137 .Xr sysctl 8
 138 .Sh HISTORY
 139 A
 140 .Nm
 141 file format appeared in
 142 .At v6 .