1GETCOREDUMP(3)             Library Functions Manual             GETCOREDUMP(3)
2
3
4

NAME

6       GetCoreDump,  GetCompressedCoreDump,  GetCoreDumpWith - creates a copy-
7       on-write snapshot of the current process
8

SYNOPSIS

10       #include “google/coredumper.h”
11
12       int GetCoreDump(void);
13
14       int GetCoreDumpWith(const struct CoreDumpParameters *params);
15
16       int GetCompressedCoreDump(const struct CoredumperCompressor
17                                 compressors[], struct CoredumperCompressor
18                                 **selected_compressor);
19

DESCRIPTION

21       The GetCoreDump() function returns a file handle that can  be  read  to
22       obtain  a  snapshot  of  the current state of the calling process. This
23       function is a  convenience  wrapper  for  GetCoreDumpWith()  using  the
24       default parameters.
25
26       The  GetCoreDumpWith()  function returns a file handle that can be read
27       to obtain a snapshot of the current state of the calling process  using
28       the  parameters  specified  in  the  CoreDumpParameters  structure. The
29       parameters can specify any behaviour of the  core  dumper  however  the
30       limiting  values  in the parameter will be ignored in this type of core
31       dump.
32
33       The GetCompressedCoreDump() function returns a file handle  to  a  core
34       file  that  has  been  compressed on the fly. This function is a conve‐
35       nience wrapper for GetCoreDumpWith(). In compressor, the caller  passes
36       a pointer to an array of possible compressors:
37
38              struct CoredumperCompressor {
39                const char *compressor;  // File name of compressor; e.g. “gzip”
40                const char *const *args; // execv()-style command line arguments
41                const char *suffix;      // File name suffix; e.g. “.gz”
42              };
43
44       The  suffix will be ignored by the GetCoreDump() and GetCompressedCore‐
45       Dump() functions, and is only needed for the WriteCoreDump() family  of
46       functions.
47
48       Array  entries will be tried in sequence until an executable compressor
49       has been found or the end of the array has been  reached.  The  end  is
50       signalled  by  an  entry  that has been zero'd out completely. An empty
51       string in place of the compressor  name  signals  that  no  compression
52       should be performed.
53
54       There are several pre-defined compressor descriptions available:
55
56       COREDUMPER_COMPRESSED
57                  Try  compressing  with  either  bzip2(1),  gzip(1),  or com‐
58                  press(1).  If all of those fail, fall back on generating  an
59                  uncompressed image.
60
61       COREDUMPER_BZIP2_COMPRESSED
62
63       COREDUMPER_GZIP_COMPRESSED
64
65       COREDUMPER_COMPRESS_COMPRESSED
66                  Try  compressing with a specific compressor. Fail if no com‐
67                  pressor could be found.
68
69       COREDUMPER_TRY_BZIP2_COMPRESSED
70
71       COREDUMPER_TRY_GZIP_COMPRESSED
72
73       COREDUMPER_TRY_COMPRESS_COMPRESSED
74                  Try compressing with a specific  compressor.  Fall  back  on
75                  generating  an uncompressed image, if the specified compres‐
76                  sor is unavailable.
77
78       COREDUMPER_UNCOMPRESSED
79                  Always create an uncompressed core file.
80
81       If selected_compressor is non-NULL, it will be set to the actual  Core‐
82       dumperCompressor object used.
83

RETURN VALUE

85       GetCoreDump(),   GetCoreDumpWith(),   and  GetCompressedCoreDump()  all
86       return a non-seekable file handle on success. The  copy-on-write  snap‐
87       shot will automatically be released, when the caller close()s this file
88       handle.
89
90       On error -1 will be returned and errno will be set appropriately.
91

ERRORS

93       The most common reason for failure is for another  process  to  already
94       use  the  debugging API that is needed to generate the core files. This
95       could, for instance, be gdb(1), or strace(1).
96

NOTES

98       The coredumper functions momentarily suspend all threads, while  creat‐
99       ing  a  COW  (copy-on-write)  copy  of the process's address space. The
100       snapshot shows up as a new child process of the  current  process,  but
101       memory  requirements  are  relatively  small,  as most pages are shared
102       between parent and child.
103
104       The functions are neither reentrant  nor  async  signal  safe.  Callers
105       should wrap a mutex around their invocation, if necessary.
106
107       The  current  implementation  tries very hard to behave reasonably when
108       called from a signal handler, but no guarantees are made that this will
109       always  work.  Most  importantly,  it is the caller's responsibility to
110       make sure that there are never more than one instance of functions from
111       the GetCoreDump() or WriteCoreDump() family executing concurrently.
112

SEE ALSO

114       WriteCoreDump(3),     WriteCoreDumpWith(3),    WriteCoreDumpLimited(3),
115       WriteCoreDumpLimitedByPriority(3),   WriteCompressedCoreDump(3),    and
116       CoreDumpParameters(3).
117
118
119
120                                 Feb 15, 2007                   GETCOREDUMP(3)
Impressum