MCD_DUMP_DATA_REGISTER_TEXT(3)

NAME
mcd_dump_data_register_text, mcd_vdump_data_register_text - register text data to be dumped

SYNOPSIS
#include <minicoredumper.h>

int mcd_dump_data_register_text(const char *ident,
                                unsigned long dump_scope,
                                mcd_dump_data_t *save_ptr,
                                const char *fmt, ...);

int mcd_vdump_data_register_text(const char *ident,
                                 unsigned long dump_scope,
                                 mcd_dump_data_t *save_ptr,
                                 const char *fmt,
                                 va_list ap);

Compile and link with -lminicoredumper.

DESCRIPTION
The mcd_dump_data_register_text() function registers text data to be dumped. ident is a string to identify the text dump later. It must be non-NULL. If the ident is not unique, the text dump is appended to previously registered text dumps with the same ident. 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. fmt is a printf(3) format string used to print the text data to a dump file. The remaining arguments are pointer arguments specified by fmt. Each pointer argument must be of a type that is appropriate for the associated length modifier and conversion specifier in fmt. Since the arguments are always pointers, the syntax for these arguments matches that of scanf(3).

The mcd_vdump_data_register_text() function is equivalent to the function mcd_dump_data_register_text() except that it is called with a va_list instead of a variable number of arguments. These functions do not call the va_end macro. Because they invoke the va_arg macro, the value of ap is undefined after the call. See stdarg(3).

RETURN VALUE
mcd_dump_data_register_text() and mcd_vdump_data_register_text() return 0 on success, otherwise an error value is returned.

ERRORS

ENOMEM
    Insufficient memory available to allocate internal structures.

EINVAL
    ident was invalid or fmt was NULL.

EEXIST
    A binary dump matching ident was already registered.

EXAMPLE
Register a text dump with 2 different sized variables.

    mcd_dump_data_t dd;
    unsigned long val1;
    unsigned char val2;

    mcd_dump_data_register_text("tdump.txt", 6, &dd,
                                "val1=0x%lx val2=0x%hhx\n",
                                &val1, &val2);

BUGS
When dumping, each pointer argument is typecasted based on the length modifier and conversion specifier associated with that argument. If this does not match the true type of the variable, the dumped text may be invalid.

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

SEE ALSO
libminicoredumper(7), mcd_dump_data_unregister(3)

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