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 November 22, 2012
  36 .Dt CORE 5
  37 .Os
  38 .Sh NAME
  39 .Nm core
  40 .Nd memory image file format
  41 .Sh SYNOPSIS
  42 .In 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.
  68 This filename can be absolute, or relative (which
  69 will resolve to the current working directory of the program
  70 generating it).
  71 .Pp
  72 The following format specifiers may be used in the
  73 .Va kern.corefile
  74 sysctl to insert additional information into the resulting core file
  75 name:
  76 .Bl -tag -width "1234567890" -compact -offset "12345"
  77 .It Em \&%H
  78 Machine hostname.
  79 .It Em \&%I
  80 An index starting at zero until the sysctl
  81 .Em debug.ncores
  82 is reached.
  83 This can be useful for limiting the number of corefiles
  84 generated by a particular process.
  85 .It Em \&%N
  86 process name.
  87 .It Em \&%P
  88 processes PID.
  89 .It Em \&%U
  90 process UID.
  91 .El
  92 .Pp
  93 The name defaults to
  94 .Em \&%N.core ,
  95 yielding the traditional
  96 .Fx
  97 behaviour.
  98 .Pp
  99 By default, a process that changes user or group credentials whether
 100 real or effective will not create a corefile.
 101 This behaviour can be
 102 changed to generate a core dump by setting the
 103 .Xr sysctl 8
 104 variable
 105 .Va kern.sugid_coredump
 106 to 1.
 107 .Pp
 108 Corefiles can be compressed by the kernel if the following items
 109 are included in the kernel configuration file:
 110 .Bl -tag -width "1234567890" -compact -offset "12345"
 111 .It options
 112 COMPRESS_USER_CORES
 113 .It devices
 114 gzio
 115 .El
 116 .Pp
 117 When COMPRESS_USER_CORES is included the following sysctls can control
 118 if core files will be compressed:
 119 .Bl -tag -width "kern.compress_user_cores_gzlevel" -compact -offset "12345"
 120 .It Em kern.compress_user_cores_gzlevel
 121 Gzip compression level.
 122 Defaults to -1.
 123 .It Em kern.compress_user_cores
 124 Actually compress user cores.
 125 Core files will have the suffix
 126 .Em .gz
 127 appended to them.
 128 .El
 129 .Sh EXAMPLES
 130 In order to store all core images in per-user private areas under
 131 .Pa /var/coredumps ,
 132 the following
 133 .Xr sysctl 8
 134 command can be used:
 135 .Pp
 136 .Dl sysctl kern.corefile=/var/coredumps/\&%U/\&%N.core
 137 .Sh SEE ALSO
 138 .Xr gdb 1 ,
 139 .Xr kgdb 1 ,
 140 .Xr setrlimit 2 ,
 141 .Xr sigaction 2 ,
 142 .Xr sysctl 8
 143 .Sh HISTORY
 144 A
 145 .Nm
 146 file format appeared in
 147 .At v6 .