set.imageModule

Builds a set from a set image, a file a tool writes in userspace.

A set image is the set’s own arrays behind a 16-byte header, so set.fromdata builds the set over the bytes the file was read into, and nothing is copied, sorted or indexed in the kernel: a set costs its file’s size. The file is little-endian throughout:

a 16-byte header: the ASCII bytes LSET; a u16 version, 1; u16 flags, whose bit 0 says the file carries labels and whose other bits are 0; a u32 n, the number of members; and a u32 len, the bytes the members take;
u32 off[n+1], member i being bytes off[i] up to off[i+1] of the members;
u32 labels[n], only when bit 0 is set, each in [1, 2³²); the members of a file without labels carry 1;
the members, concatenated without separators in len bytes, strictly increasing compared byte by byte, the shorter first on a tie, so sorted and unique.

Its size is exactly 16 + 4(n+1) + 4n + len, the 4n only with labels. This module checks the header and the size, and set.fromdata makes no lookup read outside the file: members out of order or repeated, offsets that decrease or reach past it and a label of 0 make the lookups answer wrong, the error of the tool that wrote the file. A later layout takes another version; this one reads version 1.

Usage

local image = require("set.image")

local blocked = image.load("/etc/lunatik/blocked.set", 64 << 20)
local label = blocked:match("ads.example.com")

Functions

load (path, maxbytes)

Reads a set image and builds a set over it, in one allocation of the file’s size.

Functions in detail

load (path, maxbytes)

Reads a set image and builds a set over it, in one allocation of the file’s size.

Parameters

path string the file.
maxbytes integer the largest file it reads, in bytes, from 1 up to INT_MAX.

Returns

set

Raises

what data.load raises, its errno among them; after the path and : , the rule the file breaks: not a set image for one shorter than the header or without its magic,

unsupported
   version

, unknown flags or size mismatch; or what set.fromdata raises.