COREDUMPERPARAMETERS(3)

NAME
ClearCoreDumpParameters, SetCoreDumpLimited, SetCoreDumpCompressed, SetCoreDumpLimitedByPriority, SetCoreDumpNotes, SetCoreDumpCallback - functions to initialize and set fields in a CoreDumpParameters structure.

SYNOPSIS

#include “google/coredumper.h”

void ClearCoreDumpParameters(struct CoreDumpParameters *params);

int SetCoreDumpLimited(struct CoreDumpParameters *params, size_t max_length);

int SetCoreDumpLimitedByPriority(struct CoreDumpParameters *params, size_t max_length);

int SetCoreDumpCompressed(struct CoreDumpParameters *params, const struct CoredumpCompressor *compressors, struct CoredumperCompressor **selected_compressor);

int SetCoreDumpNotes(struct CoreDumpParameters *params, struct CoredumperNote *notes, int note_count);

int SetCoreDumpCallback(struct CoreDumpParameters *params, int (*callback_fn)(void*), void* callback_arg);

DESCRIPTION
These functions must be used to set the attributes in a CoreDumpParameters structure. Combinations of these functions may be used together. For instance to produce a compressed core dump with additional notes you should call ClearCoreDumpParameters(), SetCoreDumpCompressed(), and SetCoreDumpNotes().

The ClearCoreDumpParameters() function clears the given core dumper parameters structure to its default values.

The SetCoreDumpLimited() function sets the attributes in params to produce core files of at most max_length bytes when called with WriteCoreDumpWith(). This must not be used with SetCoreDumpLimitedByPriority().

The SetCoreDumpLimitedByPriority() function sets the attributes in params to produce core files of at most max_length bytes when called with WriteCoreDumpWith(). This differs from normal limiting by truncating the largest memory segments first as opposed to truncating the whole core file. This must not be used with SetCoreDumpLimited() or SetCoreDumpCompressed().

The SetCoreDumpCompressed() function sets the attributes in params to produce a compressed core dump when called with GetCoreDumpWith() or WriteCoreDumpWith(). Its arguments match the ones passed to GetCompressedCoreDump().

The SetCoreDumpNotes() function sets the attributes in params to add additional notes to core dumps when called with GetCoreDumpWith() or WriteCoreDumpWith(). The notes are specified as an array of the CoredumperNote structure:

    struct CoredumperNote {
      const char *name;               // The vendor name
      unsigned int type;              // A vendor specific type
      unsigned int description_size;  // The size of the description field
      const void *description;        // The note data
    };

The name, including a terminating null character, will be 4 byte aligned. The type is a user chosen value. The description_size specifies the amount of bytes to write from the description pointer in memory to the core dump note. The description will be padded to be 4 byte aligned.

The SetCoreDumpCallback() function sets the attributes in params to add a callback function that will be invoked after all threads in the process have been suspended but before any actual core is dumped. The argument provided will be passed to the callback function and is otherwise unused by the coredumper library.

If the callback function returns 0, then the core will continue to be dumped. If the callback function returns non-0, then the core dump will be failed.

RETURN VALUE

On success 0 will be returned. On error -1 will be returned and errno will be set appropriately.

ERRORS
The most common reason for an error is that incompatable parameters are combined.

SEE ALSO
GetCoreDump(3), GetCoreDumpWith(3), GetCompressedCoreDump(3), WriteCoreDump(3), WriteCoreDumpWith(3), WriteCoreDumpLimited(3), WriteCoreDumpLimitedByPriority(3), and WriteCompressedCoreDump(3).