man7.org > Linux > man-pages

Linux/UNIX system programming training

sd_varlink_push_fd(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | HISTORY | SEE ALSO | COLOPHON 

SD_VARLINK_PUSH_FD(3)       sd_varlink_push_fd      SD_VARLINK_PUSH_FD(3)

NAME         top

       sd_varlink_push_fd, sd_varlink_push_dup_fd - Submit a file
       descriptor to send along with the next outgoing Varlink message

SYNOPSIS         top

       #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         top

       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         top

       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.

NOTES         top

       Functions described here are available as a shared library, which
       can be compiled against and linked to with the
       libsystemd pkg-config(1) file.

       The code described here uses getenv(3), which is declared to be
       not multi-thread-safe. This means that the code calling the
       functions described here must not call setenv(3) from a parallel
       thread. It is recommended to only do calls to setenv() from an
       early phase of the program when no other threads have been
       started.

HISTORY         top

       sd_varlink_push_fd() and sd_varlink_push_dup_fd() were added in
       version 257.

SEE ALSO         top

       systemd(1), sd-varlink(3)

COLOPHON         top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have a
       bug report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2025-08-11.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there is
       a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

systemd 258~rc2                                     SD_VARLINK_PUSH_FD(3)

Pages that refer to this page: systemd.directives(7),  systemd.index(7)

HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface.

For details of in-depth Linux/UNIX system programming training courses that I teach, look here.

Hosting by jambit GmbH.

Cover of TLPI