---
name: "KFAIL_POINT_CODE"
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/KFAIL_POINT_CODE"
---

# KFAIL\_POINT\_CODE(9)

fail points

## NAME

**DEBUG\_FP**, **KFAIL\_POINT\_CODE**, **KFAIL\_POINT\_CODE\_FLAGS**, **KFAIL\_POINT\_CODE\_COND**, **KFAIL\_POINT\_ERROR**, **KFAIL\_POINT\_EVAL**, **KFAIL\_POINT\_DECLARE**, **KFAIL\_POINT\_DEFINE**, **KFAIL\_POINT\_GOTO**, **KFAIL\_POINT\_RETURN**, **KFAIL\_POINT\_RETURN\_VOID**, **KFAIL\_POINT\_SLEEP\_CALLBACKS**, **fail\_point** – fail points

## SYNOPSIS

**#include \<sys/fail.h\>**

**KFAIL\_POINT\_CODE**(*parent*, *name*, *code*);

**KFAIL\_POINT\_CODE\_FLAGS**(*parent*, *name*, *flags*, *code*);

**KFAIL\_POINT\_CODE\_COND**(*parent*, *name*, *cond*, *flags*, *code*);

**KFAIL\_POINT\_ERROR**(*parent*, *name*, *error\_var*);

**KFAIL\_POINT\_EVAL**(*name*, *code*);

**KFAIL\_POINT\_DECLARE**(*name*);

**KFAIL\_POINT\_DEFINE**(*parent*, *name*, *flags*);

**KFAIL\_POINT\_GOTO**(*parent*, *name*, *error\_var*, *label*);

**KFAIL\_POINT\_RETURN**(*parent*, *name*);

**KFAIL\_POINT\_RETURN\_VOID**(*parent*, *name*);

**KFAIL\_POINT\_SLEEP\_CALLBACKS**(*parent*, *name*, *pre\_func*, *pre\_arg*, *post\_func*, *post\_arg*, *code*);

## DESCRIPTION

Fail points are used to add code points where errors may be injected in a user controlled fashion. Fail points provide a convenient wrapper around user-provided error injection code, providing a [sysctl(9)](/sysctl/9.md) MIB, and a parser for that MIB that describes how the error injection code should fire.

The base fail point macro is **KFAIL\_POINT\_CODE**() where *parent* is a sysctl tree (frequently **DEBUG\_FP** for kernel fail points, but various subsystems may wish to provide their own fail point trees), and *name* is the name of the MIB in that tree, and *code* is the error injection code. The *code* argument does not require braces, but it is considered good style to use braces for any multi-line code arguments. Inside the *code* argument, the evaluation of **RETURN\_VALUE** is derived from the **return**() value set in the sysctl MIB.

Additionally, **KFAIL\_POINT\_CODE\_FLAGS**() provides a *flags* argument which controls the fail point's behaviour. This can be used to e.g., mark the fail point's context as non-sleepable, which causes the **sleep** action to be coerced to a busy wait. The supported flags are:

- FAIL\_POINT\_USE\_TIMEOUT\_PATH

  Rather than sleeping on a **sleep**() call, just fire the post-sleep function after a timeout fires.

- FAIL\_POINT\_NONSLEEPABLE

  Mark the fail point as being in a non-sleepable context, which coerces **sleep**() calls to **delay**() calls.

Likewise, **KFAIL\_POINT\_CODE\_COND**() supplies a *cond* argument, which allows you to set the condition under which the fail point's code may fire. This is equivalent to:

```
	if (cond)
		KFAIL_POINT_CODE_FLAGS(...);
```

See SYSCTL VARIABLES below.

The remaining **KFAIL\_POINT\_\***() macros are wrappers around common error injection paths:

- **KFAIL\_POINT\_RETURN**(*parent*, *name*)

  is the equivalent of **KFAIL\_POINT\_CODE(...,** **return** **RETURN\_VALUE)**

- **KFAIL\_POINT\_RETURN\_VOID**(*parent*, *name*)

  is the equivalent of **KFAIL\_POINT\_CODE(...,** **return)**

- **KFAIL\_POINT\_ERROR**(*parent*, *name*, *error\_var*)

  is the equivalent of **KFAIL\_POINT\_CODE(...,** **error\_var** **=** **RETURN\_VALUE)**

- **KFAIL\_POINT\_GOTO**(*parent*, *name*, *error\_var*, *label*)

  is the equivalent of **KFAIL\_POINT\_CODE(...,** **{** **error\_var** **=** **RETURN\_VALUE;** **goto** **label;})**

You can also introduce fail points by separating the declaration, definition, and evaluation portions.

- **KFAIL\_POINT\_DECLARE**(*name*)

  is used to declare the **fail\_point** struct.

- **KFAIL\_POINT\_DEFINE**(*parent*, *name*, *flags*)

  defines and initializes the **fail\_point** and sets up its [sysctl(9)](/sysctl/9.md).

- **KFAIL\_POINT\_EVAL**(*name*, *code*)

  is used at the point that the fail point is executed.

## SYSCTL VARIABLES

The **KFAIL\_POINT\_\***() macros add sysctl MIBs where specified. Many base kernel MIBs can be found in the **debug.fail\_point** tree (referenced in code by **DEBUG\_FP**).

The sysctl variable may be set in a number of ways:

```
  [<pct>%][<cnt>*]<type>[(args...)][-><more terms>]
```

The \<type\> argument specifies which action to take; it can be one of:

- **off**

  Take no action (does not trigger fail point code)

- **return**

  Trigger fail point code with specified argument

- **sleep**

  Sleep the specified number of milliseconds

- **panic**

  Panic

- **break**

  Break into the debugger, or trap if there is no debugger support

- **print**

  Print that the fail point executed

- **pause**

  Threads sleep at the fail point until the fail point is set to **off**

- **yield**

  Thread yields the cpu when the fail point is evaluated

- **delay**

  Similar to sleep, but busy waits the cpu. (Useful in non-sleepable contexts.)

The \<pct\>% and \<cnt\>\* modifiers prior to \<type\> control when \<type\> is executed. The \<pct\>% form (e.g. "1.2%") can be used to specify a probability that \<type\> will execute. This is a decimal in the range (0, 100\] which can specify up to 1/10,000% precision. The \<cnt\>\* form (e.g. "5\*") can be used to specify the number of times \<type\> should be executed before this \<term\> is disabled. Only the last probability and the last count are used if multiple are specified, i.e. "1.2%2%" is the same as "2%". When both a probability and a count are specified, the probability is evaluated before the count, i.e. "2%5\*" means "2% of the time, but only 5 times total".

The operator -\> can be used to express cascading terms. If you specify \<term1\>-\>\<term2\>, it means that if \<term1\> does not ‘execute’, \<term2\> is evaluated. For the purpose of this operator, the **return**() and **print**() operators are the only types that cascade. A **return**() term only cascades if the code executes, and a **print**() term only cascades when passed a non-zero argument. A pid can optionally be specified. The fail point term is only executed when invoked by a process with a matching p\_pid.

## EXAMPLES

- **sysctl** **debug.fail\_point.foobar="2.1%return(5)"**

  21/1000ths of the time, execute *code* with RETURN\_VALUE set to 5.

- **sysctl** **debug.fail\_point.foobar="2%return(5)-\>5%return(22)"**

  2/100ths of the time, execute *code* with RETURN\_VALUE set to 5. If that does not happen, 5% of the time execute *code* with RETURN\_VALUE set to 22.

- **sysctl** **debug.fail\_point.foobar="5\*return(5)-\>0.1%return(22)"**

  For 5 times, return 5. After that, 1/1000th of the time, return 22.

- **sysctl** **debug.fail\_point.foobar="0.1%5\*return(5)"**

  Return 5 for 1 in 1000 executions, but only 5 times total.

- **sysctl** **debug.fail\_point.foobar="1%\*sleep(50)"**

  1/100th of the time, sleep 50ms.

- **sysctl** **debug.fail\_point.foobar="1\*return(5)\[pid** **1234\]"**

  Return 5 once, when pid 1234 executes the fail point.

## AUTHORS

This manual page was written by

Matthew Bryan ⟨*matthew.bryan@isilon.com*⟩ and

Zach Loafman ⟨*zml@FreeBSD.org*⟩.

## CAVEATS

It is easy to shoot yourself in the foot by setting fail points too aggressively or setting too many in combination. For example, forcing **malloc**() to fail consistently is potentially harmful to uptime.

The **sleep**() sysctl setting may not be appropriate in all situations. Currently, **fail\_point\_eval**() does not verify whether the context is appropriate for calling **msleep**(). You can force it to evaluate a **sleep** action as a **delay** action by specifying the **FAIL\_POINT\_NONSLEEPABLE** flag at the point the fail point is declared.