// SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // // 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)); }