libdspam(3)

📦 version 3.10.2, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

okay so bestie, this is the libdspam(3) manual page — the entry for libdspam, the core message processing and classification library for DSPAM. it's also got the subtitle DSPAM Core Analyis Engine Functions (spelled exactly like that, no cap 🙈).

✨ SYNOPSIS ✨

here's the whole function lineup. signatures stay exactly as-is because we do not mess with code, periodt:

#include <libdspam.h>

DSPAM_CTX *dspam_init(const char *username, const char *group,
  const char *home, int operating_mode, u_int32_t flags);

DSPAM_CTX *dspam_create(const char *username, const char *group,
  const char *home, int operating_mode, u_int32_t flags);

int dspam_addattribute(DSPAM_CTX *CTX, const char *key,
  const char *value);

int dspam_clearattributes(DSPAM_CTX *CTX);

int dspam_attach(DSPAM_CTX *CTX, void *dbh);

int dspam_process(DSPAM_CTX *CTX, const char *message);

int dspam_getsource(DSPAM_CTX *CTX, char *buf, size_t size);

int dspam_detach(DSPAM_CTX *CTX);

int dspam_destroy(DSPAM_CTX *CTX);

💅 DESCRIPTION 💅

libdspam provides core message processing and classification functionality. that's the whole vibe: it's the library doing the message-classification main character work 🫶.

dspam_init() creates and initializes a new classification context and attaches that context to whatever backend storage facility was configured. the username and group arguments provided are used to read and write information stored for the user and group specified. the home argument is used to configure libdspam's storage around the base directory specified. the operating_mode specifies the operating mode to initialize the classification context with, and it may be one of:

  • DSM_PROCESS — classify and learn the supplied message using whatever training mode is specified ✨
  • DSM_CLASSIFY — classify the supplied message only; do not learn or update any counters 🚫
  • DSM_TOOLS — no processing, attach to storage only 🧰

the flags provided further tune the classification context for a specific function. multiple flags may be OR'd together, bestie 💅.

  • DSF_UNLEARN — unlearn the message
  • DSF_BIAS — assign processor bias to unknown tokens
  • DSF_SIGNATURE — a binary signature is requested/provided
  • DSF_NOISE — apply Bayesian Noise Reduction logic
  • DSF_WHITELIST — use automatic whitelisting logic
  • DSF_MERGED — merge group metadata with user's in memory

upon successful completion, dspam_init() will return a pointer to a new classification context structure containing a copy of the configuration passed into dspam_init(), a connected storage driver handle, and a set of preliminary user control data read from storage. it's giving main character context structure, honestly 👑.

dspam_create() performs in exactly the same manner as dspam_init(), but does not attach to storage. instead, the caller must also call dspam_attach() after setting any storage-specific attributes using dspam_addattribute(). this is useful for cases where the implementor would prefer to configure storage internally rather than having libdspam read a configuration from a file 🦋.

dspam_addattribute() is called to set attributes within the classification context. some storage drivers support the use of passing specific attributes such as server connect information. the driver-independent attributes supported by DSPAM include:

  • IgnoreHeader — specify a specific header to ignore
  • LocalMX — specify a local mail exchanger to assist in correct results from dspam_getsource()

only driver-dependent attributes need be set prior to a call to dspam_attach(). driver-independent attributes may be set both before and after storage has been attached 🌈.

dspam_attach() attaches the storage interface to the classification context and alternatively established an initial connection with storage if dbh is NULL. some storage drivers support only a NULL value for dbh, while others (such as mysql_drv, pgsql_drv, and sqlite_drv) allow an open database handle to be attached. this function should only be called after an initial call to dspam_create() and should never be called if using dspam_init(), as storage is automatically attached by a call to dspam_init().

bestie, this is one of those "read the rule twice" situations: dspam_attach() is for the dspam_create() path, not the dspam_init() path 💀.

dspam_process() performs analysis of the message passed into it and will return zero on successful completion. if successful, CTX->result will be set to one of three classification results:

  • DSR_ISSPAM — message was classified as spam
  • DSR_ISINNOCENT — message was classified as nonspam
  • DSR_ISWHITELISTED — recipient was automatically whitelisted

should the call fail, one of the following errors will be returned:

  • EINVAL — an invalid call or invalid parameter used.
  • EUNKNOWN — unexpected error, such as malloc() failure
  • EFILE — error opening or writing to a file or file handle
  • ELOCK — locking failure
  • EFAILURE — the operation itself has failed

dspam_getsource() extracts the source sender from the message passed in during a call to dspam_process() and writes not more than size bytes to buf 🎀.

dspam_detach() can be called when a detachment from storage is desired, but the context is still needed. the storage driver is closed, leaving the classification context in place. once the context is no longer needed, another call to dspam_destroy() should be made. if you are closing storage and destroying the context at the same time, it is not necessary to call this function. instead you may call dspam_destroy() directly 💖.

dspam_clearattributes() is called to clear any attributes previously set using dspam_addattribute() within the classification context. it is necessary to call this function prior to replacing any attributes already written 🌸.

dspam_destroy() should be called when the context is no longer needed. if a connection was established to storage internally, the connection is closed and all data is flushed and written. if a handle was attached, the handle will remain open 🦋.

Copyright © 2002-2012 DSPAM Project All rights reserved.

for more information, see http://dspam.sourceforge.net.

🦋 SEE ALSO 🦋

xoxo, your libdspam(3) bestie 💖 — source/version: libdspam · date: Apr 17, 2010 · manual: libdspam(3). bye bestie, go classify something iconic ✨🦋

📦 where this page comes from