NAME
coredumper_register, coredumper_unregister – loadable user coredumper support
SYNOPSIS
#include <sys/ucoredump.h>
void
coredumper_register(struct coredumper *cd);
void
coredumper_unregister(struct coredumper *cd);
int
coredumper_probe_fn(struct thread *td);
int
coredumper_handle_fn(struct thread *td, off_t limit);
/* Incomplete, but the useful members are depicted here. */
struct coredumper {
const char *cd_name;
coredumper_probe_fn *cd_probe;
coredumper_handle_fn *cd_handle;
};
int
coredump_init_fn(const struct coredump_writer *, const struct coredump_params *);
int
coredump_write_fn(const struct coredump_writer *, const void *, size_t, off_t, enum uio_seg, struct ucred *, size_t *, struct thread *);
int
coredump_extend_fn(const struct coredump_writer *, off_t, struct ucred *);
struct coredump_writer {
void *ctx;
coredump_init_fn *init_fn;
coredump_write_fn *write_fn;
coredump_extend_fn *extend_fn;
};
DESCRIPTION
The coredumper_register mechanism provides a path for kernel modules to register a new user process core dumper. The expected use of coredumper_register is for a module to define the fields of the struct coredumper listed above, then call coredumper_register() at MOD_LOAD time. A corresponding coredumper_unregister() should be called at MOD_UNLOAD time. Note that coredumper_unregister() will block until the specified coredumper is no longer processing coredumps.
When a user process is preparing to start dumping core, the kernel will execute the cd_probe() function for each coredumper currently registered. The cd_probe() function is expected to return either -1 if it would decline to dump the process, or a priority level greater than 0. The coredumper with the highest priority will handle the coredump. The following default priorities are defined:
- COREDUMPER_NOMATCH
-
This dumper declines dumping the process.
- COREDUMPER_GENERIC
-
This dumper will dump the process at the lowest priority. This priority is not recommended, as the default vnode dumper will bid at COREDUMPER_GENERIC as well.
- COREDUMPER_SPECIAL
-
This dumper provides special behavior, and will dump the process at a higher priority.
- COREDUMPER_HIGHPRIORITY
-
This dumper would prefer to handle this coredump. This may be used by, for instance, a custom or vendor-specific coredump mechanism that wishes to preempt others.
Note that this system has been designed such that the cd_probe() function can examine the process in question and make an informed decision. Different processes being dumped could probe at different priorities in the same coredumper.
Once the highest priority coredumper has been selected, the cd_handle() function will be invoked. The cd_handle() will receive both the thread and the RLIMIT_CORE setrlimit(2) limit. The proc lock will be held on entry, and should be unlocked before the handler returns. The limit is typically passed to the sv_coredump() that belongs to the process's p_sysent.
The cd_handle() function should return either 0 if the dump was successful, or an appropriate errno(2) otherwise.
Customized Coredump Writers
Custom coredumpers can define their own coredump_writer to pass to sv_coredump().
The ctx member is opaque and only to be used by the coredumper itself.
The init_fn function, if it's provided, will be called by the sv_coredump() implementation before any data is to be written. This allows the writer implementation to record any coredump parameters that it might need to capture, or setup the object to be written to.
The write_fn function will be called by the sv_coredump() implementation to write out data. The extend_fn function will be called to enlarge the coredump, in the sense that a hole is created in any difference between the current size and the new size. For convenience, the core_vn_write() and core_vn_extend() functions used by the vnode coredumper are exposed in ⟨sys/ucordumper.h⟩, and the coredump_vnode_ctx defined there should be populated with the vnode to write to.
SEE ALSO
AUTHORS
This manual page was written by Kyle Evans ⟨[email protected]⟩.