GETCOREDUMP(3)

NAME
GetCoreDump, GetCompressedCoreDump, GetCoreDumpWith - creates a copy-on-write snapshot of the current process

SYNOPSIS

#include “google/coredumper.h”

int GetCoreDump(void);

int GetCoreDumpWith(const struct CoreDumpParameters *params);

int GetCompressedCoreDump(const struct CoredumperCompressor compressors[], struct CoredumperCompressor **selected_compressor);

DESCRIPTION
The GetCoreDump() function returns a file handle that can be read to obtain a snapshot of the current state of the calling process. This function is a convenience wrapper for GetCoreDumpWith() using the default parameters.

The GetCoreDumpWith() function returns a file handle that can be read to obtain a snapshot of the current state of the calling process using the parameters specified in the CoreDumpParameters structure. The parameters can specify any behaviour of the core dumper however the limiting values in the parameter will be ignored in this type of core dump.

The GetCompressedCoreDump() function returns a file handle to a core file that has been compressed on the fly. This function is a convenience wrapper for GetCoreDumpWith(). In compressor, the caller passes a pointer to an array of possible compressors:

    struct CoredumperCompressor {
      const char *compressor;  // File name of compressor; e.g. “gzip”
      const char *const *args; // execv()-style command line arguments
      const char *suffix;      // File name suffix; e.g. “.gz”
    };

The suffix will be ignored by the GetCoreDump() and GetCompressedCoreDump() functions, and is only needed for the WriteCoreDump() family of functions.

Array entries will be tried in sequence until an executable compressor has been found or the end of the array has been reached. The end is signalled by an entry that has been zero'd out completely. An empty string in place of the compressor name signals that no compression should be performed.

There are several pre-defined compressor descriptions available:

COREDUMPER_COMPRESSED
    Try compressing with either bzip2(1), gzip(1), or compress(1). If all of those fail, fall back on generating an uncompressed image.

COREDUMPER_BZIP2_COMPRESSED

COREDUMPER_GZIP_COMPRESSED

COREDUMPER_COMPRESS_COMPRESSED
    Try compressing with a specific compressor. Fail if no compressor could be found.

COREDUMPER_TRY_BZIP2_COMPRESSED

COREDUMPER_TRY_GZIP_COMPRESSED

COREDUMPER_TRY_COMPRESS_COMPRESSED
    Try compressing with a specific compressor. Fall back on generating an uncompressed image, if the specified compressor is unavailable.

COREDUMPER_UNCOMPRESSED
    Always create an uncompressed core file.

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

RETURN VALUE
GetCoreDump(), GetCoreDumpWith(), and GetCompressedCoreDump() all return a non-seekable file handle on success. The copy-on-write snapshot will automatically be released, when the caller close()s this file handle.

On error -1 will be returned and 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 snapshot shows up as a new child process of the current process, but memory requirements are relatively small, as most pages are shared between parent and child.

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
WriteCoreDump(3), WriteCoreDumpWith(3), WriteCoreDumpLimited(3), WriteCoreDumpLimitedByPriority(3), WriteCompressedCoreDump(3), and CoreDumpParameters(3).