NCAP(3)

💖 NCAP(3) 💖 — network data capture, but make it a whole vibe

okay bestie so this is a Library Functions Manual page, section 3, and it's literally the gateway to grabbing network data like a boss. sit down, hydrate, let's go 🫶

---

✨ NAME ✨

ncap — network data capture 💅

---

🌸 SYNOPSIS 🌸

#include <ncap.h>

ncap_t
ncap_create(int maxmsgsize);

---

🦋 DESCRIPTION 🦋

The ncap library is a high level interface for network data capture. And when I say the source of your network data can be a lot of things, I mean it — it can be live traffic, or it can be files stuffed with previously captured or generated data. Those files can be in ncap format (defined below, keep scrolling babe) or in pcap(3) format, and they can be either normal binary files or network sockets. versatility? iconic. periodt.

The ncap_create() function returns a brand new ncap object (a structure) that comes with a bunch of methods (function pointers) you can reference to add data sources, poll for data, loop while collecting data, and so on. main character energy fr fr.

maxmsgsize is the size of the largest message (in portable binary export format) you're expecting to handle — usually this is 70000, so you've got room for a 64Kbyte payload plus all the ncap message header overhead. 💀 if you skimp on this, that's on you.

ncap_create() returns NULL if an error occurs, and in that case errno will be set to indicate the error cause. noted. 🙈

The ncap_t data structure is defined in the <ncap.h> include file, which defines at least the following symbols:

typedef enum { ncap_success = 0, ncap_failure } ncap_result_e;
typedef void (*ncap_callback_t)(ncap_t, void *, ncap_msg_ct);
typedef struct ncap *ncap_t;
struct ncap {
        char *          errstr;
        ncap_result_e   (*add_if)(ncap_t, const char *name,
                                  const char *bpf, int promisc,
                                  const int vlans[], int nvlan,
                                  int *fdes);
        ncap_result_e   (*drop_if)(ncap_t, int fdes);
        ncap_result_e   (*add_nf)(ncap_t, int fdes, const char *);
        ncap_result_e   (*drop_nf)(ncap_t, int fdes);
        ncap_result_e   (*add_pf)(ncap_t, FILE *, const char *);
        ncap_result_e   (*drop_pf)(ncap_t, FILE *);
        ncap_result_e   (*add_dg)(ncap_t, int fdes);
        ncap_result_e   (*drop_dg)(ncap_t, int fdes);
        ncap_result_e   (*filter)(ncap_t, const char *);
        ncap_result_e   (*collect)(ncap_t, int polling,
                                   ncap_callback_t,
                                   void *closure);
        void            (*stop)(ncap_t);
        struct ncap_msg (*cons)(ncap_t, struct timespec,
                                unsigned, unsigned,
                                ncap_np_e, ncap_np_ct,
                                ncap_tp_e, ncap_tp_ct,
                                size_t, const u_char *);
        int             (*match)(ncap_t, ncap_msg_ct);
        ncap_result_e   (*write)(ncap_t, ncap_msg_ct, int fdes);
        ncap_result_e   (*fwrite)(ncap_t, ncap_msg_ct, FILE *);
        ncap_result_e   (*send)(ncap_t, ncap_msg_ct, int fdes,
                                int flags);
        void            (*destroy)(ncap_t);
};

The elements of ncap_t are defined as follows — buckle up, there's a lot and I'm listing every single one:

• errstr — a pointer to a text string describing the most recent error condition. If no error has happened, this string will be empty, but it will never be NULL. so you can always safely peek at it, slay.
• add_if — adds a network interface as a data source. Interface naming rules are the same as in pcap(3). You can hand it a bpf(4) program (in text form) to filter the data source in the kernel, which cuts down on how much data this object ends up collecting. ⚠️ it is an error to specify a non-NULL bpf program if an NCAP filter has already been installed — pick a lane bestie. The interface can be made promiscuous, in which case it's eligible to receive data for which this system is neither the source nor the destination, if the attached network and interface support this mode. You can also pass a list of VLANs, in which case tagged 802.1Q frames become eligible and will be collected if their tag number is on the provided list. Special case: if the list contains only VLAN tag number zero (0), then all tagged frames will be eligible. And the file descriptor opened for this interface can be returned so you can use it with select(2) or in drop_if as defined below. 👑
• drop_if — removes the designated interface from further consideration or data collection. bye girl 💅
• add_nf — adds a previously opened NCAP file as a data source.
• drop_nf — drops an NCAP file as a data source.
• add_pf — adds a previously opened PCAP file as a data source.
• drop_pf — drops a PCAP file as a data source.
• add_dg — adds a previously opened datagram socket as a data source.
• drop_dg — drops a datagram socket as a data source.
• watch_fd — adds a file descriptor to the set watched by collect, so that a readability event on this descriptor will result in the designated watcher callback being activated with the supplied closure.
• drop_fd — removes a file descriptor from the set being watched by collect.
• filter — installs an NCAP filter, specified as ASCII text. ⚠️ it is an error to install a filter if any interface has been added with a supplied BPF program. (symmetry with add_if, you see the vision 🧚)
• collect — runs the data collection engine, either once (if polling) or continuously (until stop() is called). Each collected message gets formatted into an ncap_msg structure and, if no filter has been installed or if the message matches the installed filter, it's passed to the supplied callback along with the supplied closure. the moment we've all been waiting for ✨
• stop — can be called from inside a collect() callback or from inside an operating system signal handler, and it will end the loop inside collect(). emergency exit but make it cute.
• cons — returns an ncap_msg structure filled in according to the arguments. Pro tip: it's wise to use this rather than doing inline initialization, in case new fields get added to the ncap_msg structure later on. future-proofing is self care 🌸
• match — tests a supplied message against any installed filter. Returns TRUE if no filter is installed or if the message matches the installed filter, else FALSE.
• write, fwrite, send — exports an ncap_msg structure to a file descriptor, file pointer, or datagram socket in portable binary format. If no message is supplied (e.g., NULL), a "file header" is output, containing a magic number and the ncap library version number. A file header must be the first thing in an ncap file, and should be sent periodically on a datagram socket. And if the result is ncap_failure, then errno will have been set by an underlying failed system call. 😭
• destroy — releases all resources held by this ncap object, including heap memory and underlying pcap(3) objects. ⚠️ Standard I/O files as provided to add_pf() are not closed here — those are the caller's responsibility. clean up after yourself bestie.

---

🎀 Message Formats 🎀

An in-memory ncap message has the following structure:

typedef enum { ncap_ip4 = 0, ncap_ip6 } ncap_np_e;
typedef union ncap_np *ncap_np_t;
typedef const union ncap_np *ncap_np_ct;
union ncap_np {
        struct {
                struct in_addr src, dst;
        } ip4;
        struct {
                struct in6_addr src, dst;
        } ip6;
};

typedef enum { ncap_udp = 0, ncap_tcp } ncap_tp_e;
typedef union ncap_tp *ncap_tp_t;
typedef const union ncap_tp *ncap_tp_ct;
union ncap_tp {
        struct {
                unsigned        sport, dport;
        } udp;
        struct {
                unsigned        sport, dport;
                unsigned        offset;
                unsigned        flags;
        } tcp;
};
#define ncap_tcp_syn    0x0001  /* first segment */
#define ncap_tcp_fin    0x0002  /* last segment */
#define ncap_tcp_rst    0x0004  /* session reset */
#define ncap_tcp_sum    0x0008  /* checksum failed */

typedef struct ncap_msg *ncap_msg_t;
typedef const struct ncap_msg *ncap_msg_ct;
struct ncap_msg {
        /* Fixed part. */
        struct timespec ts;
        unsigned        user1, user2;
        ncap_np_e       np;
        ncap_tp_e       tp;
        size_t          paylen;
        /* Variable part. */
        union ncap_np   npu;
        union ncap_tp   tpu;
        const u_char *  payload;
};

The portable binary export format of an ncap message is as follows:

Fixed part (size is 28):
        uint32_t        message length (includes self, padding)
        uint32_t        sec, nsec
        uint32_t        user1, user2
        uint16_t        network union type (includes padding)
        uint16_t        transport union type (includes padding)
        uint32_t        payload length (no padding)

Variable part (size is always evenly divisible by 4):
        u_char []       network union
        u_char []       transport union
        u_char []       payload

Reliable streams of portable binary format ncap messages should begin with a "file header", and datagram streams should include a "file header" every so often for receiver synchronization. A "file header" has the following structure:

• magic — 4 octets having the value of ASCII `"NCAP".
• vers — 4 octets having the network byte order of the ncap version (currently 0x00 0x00 0x00 0x2a).

---

🌈 SEE ALSO 🌈

select(2), sendmsg(2), writev(2), pcap(3), fdopen(3), bpf(4)

---

💀 BUGS 💀

ncap filters are not implemented yet, so for now, use bpf(3) filters in add_if(). yeah. that's the whole thing. we move. 🙈

📜 LICENSE 📜

okay bestie, it's legal o'clock 🕰️✨ i know, i know, nobody's thrilled about the fine print, but this is literally the receipts for why you're allowed to touch this code at all. so let's give it the respect it deserves, fr fr 🫶

First up, the credit line — and yes, you have to keep this exact:

• Copyright (c) 2007 by Internet Systems Consortium, Inc. ("ISC")

Then the part that's basically a green light:

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

Translation for the group chat: do literally whatever you want with it 💅 — use it, copy it, remix it, ship it, and you don't owe anybody a single coin. The one condition? Don't be shady and delete the credit. The copyright notice and this permission notice have to ride along in all copies. That's it. That's the whole ask. iconic behavior tbh 👑

---

and now the dramatic part. the all-caps part. the "please don't sue us" part 😭 it's shouting because lawyers love shouting:

THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

so what's the vibe check on that? it comes as-is. no promises, no guarantees, no implied warranties of merchantability or fitness — ISC is not out here swearing it'll be perfect for your specific situation. 🙈 and if something goes sideways? if you lose use, data, or profits, or catch a special, direct, indirect, or consequential damage? whether it's dressed up as contract, negligence, or other tortious action, arising out of or in connection with the use or performance of this software — ISC is not liable. not even a little. 😭

basically: it's free, it's as-is, no warranty, no refunds, and ISC is not your emergency contact if things get weird. use it, love it, but own your own chaos, bestie 💖

---

and that's a wrap on this page!! 🎀 this manual page came to you via Debian, dated August, 2007, and it's NCAP(3) — section 3, the library-calls corner of the manual, iykyk. go forth and ncap responsibly, my love 🌈✨ bye bestie!! 💜🦋