1WRITECOREDUMP(3) Library Functions Manual WRITECOREDUMP(3)
2
6 WriteCoreDump, WriteCoreDumpWith, WriteCoreDumpLimited, WriteCore‐
7 DumpLimitedByPriority, WriteCompressedCoreDump - writes a snapshot of
8 the current process
9
11 #include “google/coredumper.h”
12 int WriteCoreDump(const char *file_name);
14 int WriteCoreDumpWith(const char *file_name, const struct CoreDump‐
16 Parameters *params);
17 int WriteCoreDumpLimited(const char *file_name, size_t max_length);
19 int WriteCoreDumpLimitedByPriority(const char *file_name, size_t
21 max_length);
22 int WriteCompressedCoreDump(const char *file_name, size_t max_length,
24 const struct CoredumperCompressor
25 compressors[], struct CoredumperCompressor
26 **selected_compressor);
27
29 The WriteCoreDump() function writes a core file to file_name. The
30 calling process continues running after the file has been written. This
31 is a convenience wrapper for WriteCoreDumpWith() using the default
32 parameters.
33 The WriteCoreDumpWith() function writes a core file to file_name using
35 the parameters specified in the CoreDumpParameters() structure. This
36 allows for various combinations of configurations.
37 The WriteCoreDumpLimited() function restricts the maximum length of the
39 written file. This is similar to what setting calling setrlimit(2) does
40 for system-generated core files. This is a convenience wrapper for
41 WriteCoreDumpWith().
42 The WriteCoreDumpLimitedByPriority() function restricts the maximum
44 length of the written file, however it does so by prioritizing smaller
45 memory segments. This means that the core file is not truncated at the
46 end of the file, as in WriteCoreDumpLimited(), but individual memory
47 segments in the core file are truncated with the largest segments trun‐
48 cated first. This is a convenience wrapper for WriteCoreDumpWith().
49 The WriteCompressedCoreDump() function attempts to compress the core
51 file on the fly, if a suitable compressor could be located.
52 If selected_compressor is non-NULL, it will be set to the actual Core‐
54 dumperCompressor object used.
55 The filename automatically has a suitable suffix appended to it. Nor‐
57 mally this would be “.bz2” for bzip2(1) compression, “.gz” for gzip(1)
58 compression, or “.Z” for compress(1) compression. This behavior can be
59 changed by defining custom CoredumperCompressor descriptions. This is a
60 convenience wrapper for WriteCoreDumpWith(). See the manual page for
61 GetCoreDump(3) for more details.
62
64 WriteCoreDump(), WriteCoreDumpWith(), WriteCoreDumpLimited(),
65 WriteCoreDumpLimitedByPriority(), and WriteCompressedCoreDump() return
66 zero on success and -1 on failure. In case of failure, errno will be
67 set appropriately.
68
70 The most common reason for failure is for another process to already
71 use the debugging API that is needed to generate the core files. This
72 could, for instance, be gdb(1), or strace(1).
73
75 The coredumper functions momentarily suspend all threads, while creat‐
76 ing a COW (copy-on-write) copy of the process's address space.
77 The functions are neither reentrant nor async signal safe. Callers
79 should wrap a mutex around their invocation, if necessary.
80 The current implementation tries very hard to behave reasonably when
82 called from a signal handler, but no guarantees are made that this will
83 always work. Most importantly, it is the caller's responsibility to
84 make sure that there are never more than one instance of functions from
85 the GetCoreDump() or WriteCoreDump() family executing concurrently.
86
88 GetCoreDump(3), GetCoreDumpWith(3), GetCompressedCoreDump(3), and Core‐
89 DumpParameters(3).
90 Feb 15, 2007 WRITECOREDUMP(3)