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