---
name: "coredumper_register"
section: "9"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/coredumper_register"
---

# coredumper\_register(9)

loadable user coredumper support

## 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)](/setrlimit/2.md) *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)](/errno/2.md) 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

[setrlimit(2)](/setrlimit/2.md), [core(5)](/core/5.md)

## AUTHORS

This manual page was written by Kyle Evans ⟨*kevans@FreeBSD.org*⟩.