---
name: "blocklist"
section: "3"
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/blocklist"
---

# blocklist(3)

Blocklistd notification library

## NAME

**blocklist\_open**, **blocklist\_open2**, **blocklist\_close**, **blocklist\_r**, **blocklist**, **blocklist\_sa**, **blocklist\_sa\_r** – Blocklistd notification library

## LIBRARY

library “libblocklist”

## SYNOPSIS

**#include \<blocklist.h\>**

*struct* *blocklist* *\**\

**blocklist\_open**(*void*);

*struct* *blocklist* *\**\

**blocklist\_open2**(*void (\*logger)(int, struct syslog\_data \*, va\_list)*);

*void*\

**blocklist\_close**(*struct blocklist \*cookie*);

*int*\

**blocklist**(*int action*, *int fd*, *const char \*msg*);

*int*\

**blocklist\_r**(*struct blocklist \*cookie*, *int action*, *int fd*, *const char \*msg*);

*int*\

**blocklist\_sa**(*int action*, *int fd*, *const struct sockaddr \*sa*, *socklen\_t salen*, *const char \*msg*);

*int*\

**blocklist\_sa\_r**(*struct blocklist \*cookie*, *int action*, *int fd*, *const struct sockaddr \*sa*, *socklen\_t salen*, *const char \*msg*);

## DESCRIPTION

These functions can be used by daemons to notify [blocklistd(8)](/blocklistd/8.md) about successful and failed remote connections so that blocklistd can block or release port access to prevent Denial of Service attacks.

The function **blocklist\_open**() creates the necessary state to communicate with [blocklistd(8)](/blocklistd/8.md) and returns a pointer to it, or NULL on failure.

The function **blocklist\_open2**() is similar to **blocklist\_open**() but allows a *logger* to be specified. If the *logger* is NULL, then no logging is performed.

The **blocklist\_close**() function frees all memory and resources used.

The **blocklist**() function sends a message to [blocklistd(8)](/blocklistd/8.md), with an integer *action* argument specifying the type of notification, a file descriptor *fd* specifying the accepted file descriptor connected to the client, and an optional message in the *msg* argument.

The *action* parameter can take these values:

- BLOCKLIST\_AUTH\_FAIL

  There was an unsuccessful authentication attempt.

- BLOCKLIST\_AUTH\_OK

  A user successfully authenticated.

- BLOCKLIST\_ABUSIVE\_BEHAVIOR

  The sending daemon has detected abusive behavior from the remote system. The remote address should be blocked as soon as possible.

- BLOCKLIST\_BAD\_USER

  The sending daemon has determined the username presented for authentication is invalid. The [blocklistd(8)](/blocklistd/8.md) daemon compares the username to a configured list of forbidden usernames and blocks the address immediately if a forbidden username matches. (The BLOCKLIST\_BAD\_USER support is not currently available.)

The **blocklist\_r**() function is more efficient because it keeps the blocklist state around.

The **blocklist\_sa**() and **blocklist\_sa\_r**() functions can be used with unconnected sockets, where [getpeername(2)](/getpeername/2.md) will not work, the server will pass the peer name in the message.

In all cases the file descriptor passed in the *fd* argument must be pointing to a valid socket so that [blocklistd(8)](/blocklistd/8.md) can establish ownership of the local endpoint using [getsockname(2)](/getsockname/2.md).

By default, [syslogd(8)](/syslogd/8.md) is used for message logging. The internal **bl\_create**() function can be used to create the required internal state and specify a custom logging function.

## RETURN VALUES

The function **blocklist\_open**() returns a cookie on success and NULL on failure setting errno to an appropriate value.

The functions **blocklist**(), **blocklist\_sa**(), and **blocklist\_sa\_r**() return 0 on success and -1 on failure setting errno to an appropriate value.

## SEE ALSO

[blocklistd.conf(5)](/blocklistd.conf/5.md), [blocklistd(8)](/blocklistd/8.md)

## AUTHORS

Christos Zoulas