From 0dce12b8dd941e12e60126e3a6deeae2f577f80d Mon Sep 17 00:00:00 2001
From: Alfred Perlstein <alfred@FreeBSD.org>
Date: Tue, 2 Mar 2010 18:43:12 +0000
Subject: [PATCH] Document COMPRESS_USER_CORES, and the new %I and %H core
 formatters.

---
 share/man/man5/core.5 | 48 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/share/man/man5/core.5 b/share/man/man5/core.5
index 2a1e16bfb67..b2b57f193c1 100644
--- a/share/man/man5/core.5
+++ b/share/man/man5/core.5
@@ -68,13 +68,27 @@ the core image to.
 This filename can be absolute, or relative (which
 will resolve to the current working directory of the program
 generating it).
-Any sequence of
-.Em \&%N
-in this filename template will be replaced by the process name,
-.Em \&%P
-by the processes PID, and
-.Em \&%U
-by the UID.
+.Pp
+The following format specifiers may be used in the
+.Va kern.corefile
+sysctl to insert additional information into the resulting core file
+name:
+.Bl -tag -width "1234567890" -compact -offset "12345"
+.It Em \&%H
+Machine hostname.
+.It Em \&%I
+An index starting at zero until the sysctl
+.Em debug.num_cores
+is reached.  This can be useful for limiting the number of corefiles
+generated by a particular process.
+.It Em \&%N
+process name.
+.It Em \&%P
+processes PID.
+.It Em \&%U
+process UID.
+.El
+.Pp
 The name defaults to
 .Em \&%N.core ,
 yielding the traditional
@@ -89,6 +103,26 @@ changed to generate a core dump by setting the
 variable
 .Va kern.sugid_coredump
 to 1.
+.Pp
+Corefiles can be compressed by the kernel if the following items
+are included in the kernel configuration file:
+.Bl -tag -width "1234567890" -compact -offset "12345"
+.It options
+COMPRESS_USER_CORES
+.It devices
+gzio
+.El
+.Pp
+When COMPRESS_USER_CORES is included the following sysctls can control
+if core files will be compressed:
+.Bl -tag -width "kern.compress_user_cores_gzlevel" -compact -offset "12345"
+.It Em kern.compress_user_cores_gzlevel
+Gzip compression level.  Defaults to -1.
+.It Em kern.compress_user_cores
+Actually compress user cores.  Core files will have the suffix
+.Em .gz
+appended to them.
+.El
 .Sh EXAMPLES
 In order to store all core images in per-user private areas under
 .Pa /var/coredumps ,