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 22, 2010
  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.num_cores
  82 is reached.  This can be useful for limiting the number of corefiles
  83 generated by a particular process.
  84 .It Em \&%N
  85 process name.
  86 .It Em \&%P
  87 processes PID.
  88 .It Em \&%U
  89 process UID.
  90 .El
  91 .Pp
  92 The name defaults to
  93 .Em \&%N.core ,
  94 yielding the traditional
  95 .Fx
  96 behaviour.
  97 .Pp
  98 By default, a process that changes user or group credentials whether
  99 real or effective will not create a corefile.
 100 This behaviour can be
 101 changed to generate a core dump by setting the
 102 .Xr sysctl 8
 103 variable
 104 .Va kern.sugid_coredump
 105 to 1.
 106 .Pp
 107 Corefiles can be compressed by the kernel if the following items
 108 are included in the kernel configuration file:
 109 .Bl -tag -width "1234567890" -compact -offset "12345"
 110 .It options
 111 COMPRESS_USER_CORES
 112 .It devices
 113 gzio
 114 .El
 115 .Pp
 116 When COMPRESS_USER_CORES is included the following sysctls can control
 117 if core files will be compressed:
 118 .Bl -tag -width "kern.compress_user_cores_gzlevel" -compact -offset "12345"
 119 .It Em kern.compress_user_cores_gzlevel
 120 Gzip compression level.  Defaults to -1.
 121 .It Em kern.compress_user_cores
 122 Actually compress user cores.  Core files will have the suffix
 123 .Em .gz
 124 appended to them.
 125 .El
 126 .Sh EXAMPLES
 127 In order to store all core images in per-user private areas under
 128 .Pa /var/coredumps ,
 129 the following
 130 .Xr sysctl 8
 131 command can be used:
 132 .Pp
 133 .Dl sysctl kern.corefile=/var/coredumps/\&%U/\&%N.core
 134 .Sh SEE ALSO
 135 .Xr gdb 1 ,
 136 .Xr kgdb 1 ,
 137 .Xr setrlimit 2 ,
 138 .Xr sigaction 2 ,
 139 .Xr sysctl 8
 140 .Sh HISTORY
 141 A
 142 .Nm
 143 file format appeared in
 144 .At v6 .