From b302a6bae5e4c3e942f2df12ec689dc0becb4e60 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 25 Apr 2025 19:59:49 +0200 Subject: [PATCH] man: document sd_varlink_push_fd() --- man/rules/meson.build | 1 + man/sd_varlink_push_fd.xml | 134 +++++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+) create mode 100644 man/sd_varlink_push_fd.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 0b930d3beb4..203231534d3 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -889,6 +889,7 @@ manpages = [ 'sd_uid_get_sessions', 'sd_uid_is_on_seat'], 'HAVE_PAM'], + ['sd_varlink_push_fd', '3', ['sd_varlink_push_dup_fd'], ''], ['sd_varlink_set_description', '3', ['sd_varlink_get_description'], ''], ['sd_watchdog_enabled', '3', [], ''], ['shutdown', '8', [], ''], diff --git a/man/sd_varlink_push_fd.xml b/man/sd_varlink_push_fd.xml new file mode 100644 index 00000000000..d689052768f --- /dev/null +++ b/man/sd_varlink_push_fd.xml @@ -0,0 +1,134 @@ + + + + + + + + sd_varlink_push_fd + systemd + + + + sd_varlink_push_fd + 3 + + + + sd_varlink_push_fd + sd_varlink_push_dup_fd + + Submit a file descriptor to send along with the next outgoing Varlink message + + + + + #include <systemd/sd-varlink.h> + + + int sd_varlink_push_fd + sd_varlink *link + int fd + + + + int sd_varlink_push_dup_fd + sd_varlink *link + int fd + + + + + + Description + + sd_varlink_push_fd() submits a file descriptor to send along with the next + outgoing Varlink message. Takes a Varlink connection object and a file descriptor as parameter. The file + descriptor is not duplicated, and hence ownership of the file descriptor is passed to the Varlink + connection object (only on success; on failure the caller retains ownership). Once the file descriptor + has been written to the underlying transport socket it is automatically closed. The calling application + code should not touch the file descriptor or close it on its own, otherwise it will interfere with the + Varlink protocol implementation. This call is only supported if the backing transport supports file + descriptor passing (effectively this means the functionality is supported on local + AF_UNIX only), and the concept is not part of the Varlink protocol, but simply a + feature of the underlying transport. + + sd_varlink_push_dup_fd() is identical to + sd_varlink_push_fd(), except that the file descriptor is duplicated automatically, + and the calling application code hence retains ownership of the provided file descriptor, and must close + it on its own. + + Note that file descriptor passing is only permitted after a call to + sd_varlink_set_allow_fd_passing_output() that enables it, otherwise these calls will + fail with -EPERM. + + Note that on Linux a maximum of 253 file descriptors may be enqueued on + AF_UNIX sockets at once. Attempting to enqueue more on a single Varlink message will + fail with -ENOBUFS. + + + + Return Value + + On success, sd_varlink_push_fd() and + sd_varlink_push_dup_fd() return a non-negative integer. On failure, they return a + negative errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + An argument is invalid. + + + + -EBADF + + The provided file descriptor is not valid. + + + + -EPERM + + File descriptor passing has not been enabled via + sd_varlink_set_allow_fd_passing_output(). + + + + -ENOBUFS + + The maximum of 253 file descriptors have already been submitted for the next + outgoing Varlink message, no further descriptors may be enqueued for this message. + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + + History + sd_varlink_push_fd() and sd_varlink_push_dup_fd() were added in version 257. + + + + See Also + + + systemd1 + sd-varlink3 + + + -- 2.47.3