MCD_DUMP_DATA_REGISTER_BIN(3)

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
Register a binary dump with direct data and direct size.

    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);

Register a binary dump with indirect data and direct size.

    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);

Register a binary dump with indirect data and indirect size.

    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.

SEE ALSO
libminicoredumper(7), mcd_dump_data_unregister(3), coreinject(1)

The DiaMon Workgroup: <http://www.diamon.org>