1GETCOREDUMP(3) Library Functions Manual GETCOREDUMP(3)
2
3
4
6 GetCoreDump, GetCompressedCoreDump, GetCoreDumpWith - creates a copy-
7 on-write snapshot of the current process
8
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
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
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
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
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
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)