core_pattern pipe documentation - draft 2

[Michael Kerrisk <mtk.manpages@googlemail.com>]

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);
       }