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

# blacklist(3)

Blacklistd notification library

## NAME

**blacklist\_open**, **blacklist\_open2**, **blacklist\_close**, **blacklist\_r**, **blacklist**, **blacklist\_sa**, **blacklist\_sa\_r** – Blacklistd notification library

## LIBRARY

library “libblacklist”

## SYNOPSIS

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

*struct* *blacklist* *\**\

**blacklist\_open**(*void*);

*struct* *blacklist* *\**\

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

*void*\

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

*int*\

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

*int*\

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

*int*\

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

*int*\

**blacklist\_sa\_r**(*struct blacklist \*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 [blacklistd(8)](/blacklistd/8.md) about successful and failed remote connections so that blacklistd can block or release port access to prevent Denial of Service attacks.

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

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

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

The **blacklist**() function sends a message to [blacklistd(8)](/blacklistd/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:

- BLACKLIST\_AUTH\_FAIL

  There was an unsuccessful authentication attempt.

- BLACKLIST\_AUTH\_OK

  A user successfully authenticated.

- BLACKLIST\_ABUSIVE\_BEHAVIOR

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

- BLACKLIST\_BAD\_USER

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

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

The **blacklist\_sa**() and **blacklist\_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 [blacklistd(8)](/blacklistd/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 **blacklist\_open**() returns a cookie on success and NULL on failure setting errno to an appropriate value.

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

## NOTES

The library “libblacklist” has been renamed to [libblocklist(3)](/libblocklist/3.md).

## SEE ALSO

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

## AUTHORS

Christos Zoulas