There's already one for saving live domains:
int virDomainSave(virDomainPtr domain, const char *to);
Why not use a similar API for a function which does the equivalent of
'xm dump' ?
int virDomainDump(virDomainPtr domain, const char *to, int flags);
Create a kernel dump of the domain in the path contained in *to. This
API must fail if the domain is not in a panicked/crashed state.
If you set the lowest-bit in flags, however, you can override this
behavior: if the lowest bit is set, the domain will first be crashed
(similar to SysRq-C) - then a dump will be taken from that.
Why?
In the event that a cluster node needs to fence a Xen domain (or other
management tools, to be sure), we could use the API to generate a core
of the domain (if it panicked) to help debug the problem prior to
restarting the domain.
The 'crash-before-dump' bit is just something someone might want to use
at some point; I don't think it is absolutely necessary - but it doesn't
hurt anything either.
-- Lon