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>