Something went wrong. Try again.
A Zig library for writing structured log messages directly to the systemd journal over its native datagram socket.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122// SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie <jeff@ocjtech.us>//// SPDX-License-Identifier: MIT
//! Ancillary data for `sendmsg`, which is how a file descriptor crosses from//! one process to another. `Message` uses it to hand journald the sealed//! memfd holding the entry.//!//! The layout is the kernel's: a `cmsghdr` giving the length, the level and//! the type, then padding up to the alignment of `cmsghdr`, then the payload.//! `CMSG_LEN` is the header plus the payload and is what `cmsg_len` carries;//! `CMSG_SPACE` rounds that up to the alignment and is what a buffer has to//! reserve, since the kernel walks from one control message to the next in//! those steps.//!//! See `include/linux/socket.h` in the kernel source for the macros these//! mirror.
const std = @import("std");const assert = std.debug.assert;
const linux = std.os.linux;const cmsghdr = linux.cmsghdr;
/// `CMSG_ALIGN`: round up to the alignment the kernel steps in.fn alignLen(len: usize) usize { return std.mem.alignForward(usize, len, @alignOf(cmsghdr));}
/// A buffer holding exactly one control message carrying a `T`.pub fn ControlMessage(comptime T: type) type { return extern struct { const Self = @This();
/// Where the payload starts, the header having been padded out. const data_offset = alignLen(@sizeOf(cmsghdr));
/// `CMSG_LEN`: what `cmsg_len` is set to, and the least a receiver /// can have written and still have delivered the payload. pub const content_len = data_offset + @sizeOf(T);
/// `CMSG_SPACE`: what the buffer reserves, and what `msg_controllen` /// is set to when sending. pub const space = alignLen(content_len);
comptime { // The kernel aligns on `sizeof(size_t)`. If that ever stops // matching the alignment of the header, `alignLen` is padding to // the wrong boundary and every offset below it is wrong. assert(@alignOf(cmsghdr) == @sizeOf(usize)); assert(data_offset >= @sizeOf(cmsghdr)); assert(space >= content_len); }
bytes: [space]u8 align(@alignOf(cmsghdr)),
pub fn init(level: i32, @"type": i32, value: T) Self { var self: Self = undefined; // Only the header and the payload are written; the padding // between and after them is never read, by the kernel or by // anyone else. self.header().* = .{ .len = content_len, .level = level, .type = @"type", }; self.data().* = value; return self; }
pub fn header(self: *Self) *cmsghdr { return @ptrCast(self); }
pub fn data(self: *Self) *align(@alignOf(cmsghdr)) T { return @ptrCast(@alignCast(self.bytes[data_offset..])); }
/// For `msghdr.control` when sending. pub fn ptr(self: *const Self) *const anyopaque { return @ptrCast(&self.bytes); }
/// For `msghdr.control` when receiving. pub fn mutablePtr(self: *Self) *anyopaque { return @ptrCast(&self.bytes); }
/// For `msghdr.controllen`. pub fn len(self: *const Self) usize { _ = self; return space; } };}
test "the layout matches the kernel's CMSG_LEN and CMSG_SPACE" { const CM = ControlMessage(linux.fd_t);
// On a 64 bit target: a 16 byte header, a 4 byte payload, so CMSG_LEN is // 20 and CMSG_SPACE rounds it to 24. try std.testing.expectEqual(CM.data_offset + @sizeOf(linux.fd_t), CM.content_len); try std.testing.expectEqual(std.mem.alignForward(usize, CM.content_len, @alignOf(cmsghdr)), CM.space); try std.testing.expectEqual(CM.space, @sizeOf(CM)); try std.testing.expect(@alignOf(CM) >= @alignOf(cmsghdr));}
test "init writes the header and the payload where the kernel looks for them" { var cm: ControlMessage(linux.fd_t) = .init(linux.SOL.SOCKET, linux.SCM.RIGHTS, 42);
try std.testing.expectEqual(@as(usize, @TypeOf(cm).content_len), cm.header().len); try std.testing.expectEqual(@as(i32, linux.SOL.SOCKET), cm.header().level); try std.testing.expectEqual(@as(i32, linux.SCM.RIGHTS), cm.header().type); try std.testing.expectEqual(@as(linux.fd_t, 42), cm.data().*);
// The payload has to start after the padded header, not immediately // after its last field, or the kernel reads the padding as the fd. const base: [*]const u8 = @ptrCast(&cm.bytes); const payload: [*]const u8 = @ptrCast(cm.data()); try std.testing.expectEqual(@TypeOf(cm).data_offset, @intFromPtr(payload) - @intFromPtr(base));}