---
name: "__pmNotifyThrottle"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/__pmNotifyThrottle"
---

# \_\_pmNotifyThrottle(3)

control diagnostic output message \`flooding''

## NAME

**\_\_pmNotifyThrottle**, **\_\_pmResetNotifyThrottle** - control diagnostic output message \`flooding''

## C SYNOPSIS

**#include \<pcp/pmapi.h\>**\
 **#include \<pcp/libpcp.h\>**

**int \_\_pmNotifyThrottle(char \****key***, int** *subkey***);**\
 **int \_\_pmResetNotifyThrottle(char \****key***, int** *subkey***);**

**cc ... -lpcp**

## CAVEAT

This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and they may not work, or may provide different semantics at some point in the future.

## DESCRIPTION

When the same error condition occurs over and over, like in a DoS attack, or catastrophic networking failure, or bad system configuration, or software botch, there is a risk that a PCP application could generate a large number of identical diagnostic messages, filling up a log file and hence a filesystem. **\_\_pmNotifyThrottle** is intended to be used as a guard that can detect repeated calls for the same error condition and allow the caller to stop issuing messages when repeated badness happens.

The error condition is identified by *key* and *subkey*, and the most common use case would be for these to be **\_\_FILE\_\_** and **\_\_LINE\_\_** at the point where **\_\_pmNotifyThrottle** is called.

For each unique *key* and *subkey* pair **\_\_pmNotifyThrottle** maintains a count of the number of times it has been called in the life of the calling process.

The return values are 0 if the throttle limit for *key* and *subkey* has not been reached, else 1 if the throttle limit has been reached, else 2 if the throttle limit has been exceeded.

The same throttle limit as applied across all error conditions and set by the environment variable **PCP\_NOTIFY\_THROTTLE** else a default of 10 if the environment variable is not set, although this can be subsequently modified by calling **\_\_pmResetNotifyThrottle**.

**\_\_pmResetNotifyThrottle** may be used to reset the counter for an error condition to zero, so that diagnostic output can be resumed if the caller determines it is safe to do so. If *limit* is greater than zero then the limit for the error condition is also reset, otherwise the limit is unchanged.

Calling **\_\_pmResetNotifyThrottle** with a *key* value of NULL will reset the counters (and possibly limits) for **all** error conditions, and in this case if *limit* is greater than zero the default limit for any new error conditions is also set (over-riding the default setting or the value initialized from the **PCP\_NOTIFY\_THROTTLE** environment variable).

**\_\_pmResetNotifyThrottle** will return -ENOENT if *key* and *subkey* does not match an existing error condition, else the return value is the sum of the number of times the limit has been exceeded across all selected error conditions.

## EXAMPLE

The following is a simple throttle that stops reporting errors after 10 trips.

```
if ((sts = __pmNotifyThrottle(__FILE__, __LINE__)) < 2) {
    fprintf(stderr, "Some error message\n");
    if (sts == 1)
	fprintf(stderr, "[further messages will be suppressed]\n");
}
```

The more sophisticated example below throttles messages, but enables them again after 10 minutes.

```
int    lineno;
time_t first_throttle;
...
lineno = __LINE__ + 1;
if ((sts = __pmNotifyThrottle(__FILE__, lineno)) < 2) {
    pmNotifyErr(LOG_INFO, "Some error message");
    if (sts == 1) {
	first_throttle = time(NULL);
	pmNotifyErr(LOG_INFO, "[further messages will be suppressed]");
    }
}
else if (sts == 2) {
    if (time(NULL) - first_throttle >= 600) {
	sts = __pmResetNotifyThrottle(__FILE__, lineno, -1);
	pmNotifyErr(LOG_INFO, "[%d messages were suppressed]", sts);
    }
}
```

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md) and [**pmOpenLog**(3)](/pmOpenLog/3.md).