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>