minicoredumper

NAME

mcd_dump_data_register_bin - register binary data to be dumped

SYNOPSIS

#include <minicoredumper.h>

int mcd_dump_data_register_bin(const char *ident,
                               unsigned long dump_scope,
                               mcd_dump_data_t *save_ptr,
                               void *data_ptr,
                               size_t data_size,
                               enum mcd_dump_data_flags flags);

Compile and link with -lminicoredumper.

DESCRIPTION

The mcd_dump_data_register_bin() function registers binary data to be dumped. ident is a string to identify the binary dump later. If non-NULL, it must be unique! If ident is NULL, the data is only dumped if this is the crashing application, in which case the data will be explicitly stored in the core(5) file. The data will only be dumped if a scope value greater than or equal to dump_scope is requested by the minicoredumper(1). If save_ptr is non-NULL, a pointer to the registered dump will be stored there. This is needed if mcd_dump_data_unregister(3) will be used. data_ptr contains a pointer to the memory location of the data to dump (or a pointer to that pointer). flags specifies how data_ptr and data_size should be interpreted when dumping data. data_size specifies the number of bytes of data to dump (or a pointer to the number).

DATA FLAGS

The flags option specifies how data_ptr and data_size should be interpreted when dumping data. It can also affect dump behavior. The flags are bitwise combined to describe the desired behavior. The flags available are:

MCD_DATA_PTR_DIRECT: data_ptr is a pointer to the data to dump.
MCD_DATA_PTR_INDIRECT: data_ptr is a pointer to a second pointer that points to the data to dump. The second pointer is evaluated at dump. See BUGS for details about the dangers of this flag.
MCD_LENGTH_DIRECT: data_size specifies the size (in bytes) of data to dump.
MCD_LENGTH_INDIRECT: data_size is a pointer to the size (in bytes) of data to dump. The pointer is evaluated at dump. See BUGS for details about the dangers of this flag.
MCD_DATA_NODUMP: Do not dump the specified data and size. Only store information about where in memory and the core(5) file this data would be stored. This information is stored in the symbol.map dump file and can be used by the coreinject(1) tool to inject data to the registered location.

RETURN VALUE

mcd_dump_data_register_bin() returns 0 on success, otherwise an error value is returned.

ERRORS

ENOMEM: Insufficient memory available to allocate internal structures.
EINVAL: data_ptr was NULL, data_size was 0, or ident was invalid.
EEXIST: A binary or text dump matching the non-NULL ident was already registered.

EXAMPLES

mcd_dump_data_t dd1;
unsigned long val1;

mcd_dump_data_register_bin("bdump1.bin", 6, &dd1, &val1, sizeof(val1),
                           MCD_DATA_PTR_DIRECT | MCD_LENGTH_DIRECT);

mcd_dump_data_t dd2;
unsigned long *val2;

val2 = malloc(sizeof(unsigned long));

mcd_dump_data_register_bin("bdump2.bin", 6, &dd2, &val2, sizeof(*val2),
                           MCD_DATA_PTR_INDIRECT | MCD_LENGTH_DIRECT);

mcd_dump_data_t dd3;
unsigned long *val3;
size_t s3;

s3 = sizeof(unsigned long);
val3 = malloc(s3);

mcd_dump_data_register_bin("bdump3.bin", 6, &dd3, &val3, (size_t)&s3,
                           MCD_DATA_PTR_INDIRECT | MCD_LENGTH_INDIRECT);

BUGS

MCD_DATA_PTR_INDIRECT and MCD_LENGTH_INDIRECT allow an application to change the size and location of data to dump during run-time. However, such changes should be performed carefully because an application can not know when a dump will occur.

The string specified in ident is also the file name of the dump file. For this reason characters such as '/' are not permitted.