Re: core_pattern pipe documentation - draft 2

Neil Horman
2008-05-05T11:29:08Z

On Mon, May 05, 2008 at 09:19:16AM +0200, Michael Kerrisk wrote:
> Hi Neil,
>
> Below is a revised draft of the text for core_pattern. Would you be willing
> check it over?
>
> Cheers,
>
> Michael
>
> Naming of core dump files
> By default, a core dump file is named core, but the
> /proc/sys/kernel/core_pattern file (since Linux 2.6 and 2.4.21)
> can be set to define a template that is used to name core dump
> files. The template can contain % specifiers which are substi-
> tuted by the following values when a core file is created:
>
> %% a single % character
> %p PID of dumped process
> %u (numeric) real UID of dumped process
> %g (numeric) real GID of dumped process
> %s number of signal causing dump
> %t time of dump, expressed as seconds since the Epoch
> (00:00h, 1 Jan 1970, UTC)
> %h hostname (same as 'nodename' returned by uname(2))
> %e executable filename (without path prefix)
> %c core file size soft resource limit of crashing process
> (since Linux 2.6.24)
>
> A single % at the end of the template is dropped from the core
> filename, as is the combination of a % followed by any charac-
> ter other than those listed above. All other characters in the
> template become a literal part of the core filename. The tem-
> plate may include '/' characters, which are interpreted as
> delimiters for directory names. The maximum size of the
> resulting core filename is 128 bytes (64 bytes in kernels
> before 2.6.19).
> [...]
>
> Piping core dumps to a program
> Since kernel 2.6.19, Linux supports an alternate syntax for the
> /proc/sys/kernel/core_pattern file. If the first character of
> this file is a pipe symbol (|), then the remainder of the line
> is interpreted as a program to be executed. Instead of being
> written to a disk file, the core dump is given as standard
> input to the program. Note the following points:
>
> * The program must be specified using an absolute pathname (or
> a pathname relative to the root directory, /), and must
> immediately follow the '|' character.
>
> * The process created to run the program runs as user and
> group root.
>
> * Command-line arguments can be supplied to the program (since
> kernel 2.6.24), delimited by white space (up to a total line
> length of 128 bytes).
>
> * The command-line arguments can include any of the % speci-
> fiers listed above. For example, to pass the PID of the
> process that is being dumped, specify %p in an argument.
>
> [...]
> EXAMPLE
> The program below can be used to demonstrate the use of the
> pipe syntax in the /proc/sys/kernel/core_pattern file. The
> following shell session demonstrates the use of this program
> (compiled to create an executable named core_pattern_test):
>
> $ cc -o core_pattern_test core_pattern_test.c
> $ su
> Password:
> # echo "|$PWD/core_pattern_test %p UID=%u GID=%g sig=%s" > \
> /proc/sys/kernel/core_pattern
> # exit
> $ sleep 100
> type control-backslash
> Quit (core dumped)
> $ cat core.info
> argc=5
> argc[0]=</home/mtk/core_pattern_test>
> argc[1]=<20575>
> argc[2]=<UID=1000>
> argc[3]=<GID=100>
> argc[4]=<sig=3>
> Total bytes in core dump: 282624
>
> The source code of the program is as follows:
>
> /* core_pattern_test.c */
>
> #define _GNU_SOURCE
> #include <sys/stat.h>
> #include <fcntl.h>
> #include <limits.h>
> #include <stdio.h>
> #include <stdlib.h>
> #include <unistd.h>
>
> #define BUF_SIZE 1024
>
> int
> main(int argc, char *argv[])
> {
> int tot, j;
> ssize_t nread;
> char buf[BUF_SIZE];
> FILE *fp;
> char cwd[PATH_MAX];
>
> /* Change our current working directory to that of the
> crashing process */
>
> snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]);
> chdir(cwd);
>
> /* Write output to file "core.info" in that directory */
>
> fp = fopen("core.info", "w+");
> if (fp == NULL)
> exit(EXIT_FAILURE);
>
> /* Display command-line arguments given to core_pattern
> pipe program */
>
> fprintf(fp, "argc=%d\n", argc);
> for (j = 0; j < argc; j++)
> fprintf(fp, "argc[%d]=<%s>\n", j, argv[j]);
>
> /* Count bytes in standard input (the core dump) */
>
> tot = 0;
> while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0)
> tot += nread;
> fprintf(fp, "Total bytes in core dump: %d\n", tot);
>
> exit(EXIT_SUCCESS);
> }

All looks great to me, thanks!

Acked-by: Neil Horman <nhorman-2XuSBdqkA4R54TAoqtyWWQ@public.gmane.org>

--
/****************************************************
* Neil Horman <nhorman-2XuSBdqkA4R54TAoqtyWWQ@public.gmane.org>
* Software Engineer, Red Hat
****************************************************/