WRITECOREDUMP(3)

NAME
WriteCoreDump, WriteCoreDumpWith, WriteCoreDumpLimited, WriteCoreDumpLimitedByPriority, WriteCompressedCoreDump - writes a snapshot of the current process

SYNOPSIS

#include “google/coredumper.h”

int WriteCoreDump(const char *file_name);

int WriteCoreDumpWith(const char *file_name, const struct CoreDumpParameters *params);

int WriteCoreDumpLimited(const char *file_name, size_t max_length);

int WriteCoreDumpLimitedByPriority(const char *file_name, size_t max_length);

int WriteCompressedCoreDump(const char *file_name, size_t max_length, const struct CoredumperCompressor compressors[], struct CoredumperCompressor **selected_compressor);

DESCRIPTION
The WriteCoreDump() function writes a core file to file_name. The calling process continues running after the file has been written. This is a convenience wrapper for WriteCoreDumpWith() using the default parameters.

The WriteCoreDumpWith() function writes a core file to file_name using the parameters specified in the CoreDumpParameters() structure. This allows for various combinations of configurations.

The WriteCoreDumpLimited() function restricts the maximum length of the written file. This is similar to what setting calling setrlimit(2) does for system-generated core files. This is a convenience wrapper for WriteCoreDumpWith().

The WriteCoreDumpLimitedByPriority() function restricts the maximum length of the written file, however it does so by prioritizing smaller memory segments. This means that the core file is not truncated at the end of the file, as in WriteCoreDumpLimited(), but individual memory segments in the core file are truncated with the largest segments truncated first. This is a convenience wrapper for WriteCoreDumpWith().

The WriteCompressedCoreDump() function attempts to compress the core file on the fly, if a suitable compressor could be located.

If selected_compressor is non-NULL, it will be set to the actual CoredumperCompressor object used.

The filename automatically has a suitable suffix appended to it. Normally this would be “.bz2” for bzip2(1) compression, “.gz” for gzip(1) compression, or “.Z” for compress(1) compression. This behavior can be changed by defining custom CoredumperCompressor descriptions. This is a convenience wrapper for WriteCoreDumpWith(). See the manual page for GetCoreDump(3) for more details.

RETURN VALUE
WriteCoreDump(), WriteCoreDumpWith(), WriteCoreDumpLimited(), WriteCoreDumpLimitedByPriority(), and WriteCompressedCoreDump() return zero on success and -1 on failure. In case of failure, errno will be set appropriately.

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

NOTES
The coredumper functions momentarily suspend all threads, while creating a COW (copy-on-write) copy of the process's address space.

The functions are neither reentrant nor async signal safe. Callers should wrap a mutex around their invocation, if necessary.

The current implementation tries very hard to behave reasonably when called from a signal handler, but no guarantees are made that this will always work. Most importantly, it is the caller's responsibility to make sure that there are never more than one instance of functions from the GetCoreDump() or WriteCoreDump() family executing concurrently.

SEE ALSO
GetCoreDump(3), GetCoreDumpWith(3), GetCompressedCoreDump(3), and CoreDumpParameters(3).