|
HTML rendering created 2026-09-09 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. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | HISTORY | SEE ALSO | COLOPHON |
|
|
|
SD_VARL...ADDRESS(3) sd_varlink_server_listen_addressSD_VARL...ADDRESS(3)
sd_varlink_server_listen_address, sd_varlink_server_listen_fd,
sd_varlink_server_listen_name, sd_varlink_server_listen_auto -
Bind a Varlink server object to listening sockets
#include <systemd/sd-varlink.h>
#define SD_VARLINK_SERVER_MODE_MKDIR_0755 ...
int sd_varlink_server_listen_address(sd_varlink_server* server,
const char* address,
mode_t mode);
int sd_varlink_server_listen_fd(sd_varlink_server* server,
int fd);
int sd_varlink_server_listen_name(sd_varlink_server* server,
const char* name);
int sd_varlink_server_listen_auto(sd_varlink_server* server);
These functions add listening sockets to a Varlink server object,
as previously allocated with sd_varlink_server_new(3). Once the
server object is attached to an event loop (see
sd_varlink_server_attach_event()) it will accept incoming
connections on the configured sockets and dispatch the registered
method calls.
sd_varlink_server_listen_address() allocates a new AF_UNIX socket,
binds it to the specified address, and starts listening on it. The
address is a file system path of the socket to bind to. (Use
sd_varlink_server_listen_fd() below for sockets in the abstract
namespace, in foreign address families, or that are otherwise
already allocated.)
The mode parameter specifies the file system access mode to apply
to the socket inode, i.e. a bit mask of permission bits as in
chmod(2). Only the lower nine bits (0777) are permitted. The
special value (mode_t) -1 may be specified to pick a suitable
default: this is 0666 in the general case, but 0644 if the server
was allocated with the SD_VARLINK_SERVER_ROOT_ONLY or
SD_VARLINK_SERVER_MYSELF_ONLY flags (the reason being that it is
the "w" bit that controls connect(2) access, while leaving the "r"
bit on permits other users to read the socket's extended
attributes, which makes the socket recognizable as a Varlink
entrypoint, see sd-varlink(3)).
The constant SD_VARLINK_SERVER_MODE_MKDIR_0755 may be OR-ed into
the mode parameter (this is not supported if the mode is specified
as (mode_t) -1). If specified, and address is an absolute path,
the leading directories of the socket path are automatically
created (with access mode 0755) if they are missing.
sd_varlink_server_listen_fd() adds an already allocated and
listening socket to the server object, referenced by the file
descriptor fd. This is typically used in conjunction with socket
activation, to make use of a listening socket passed in from the
service manager, see sd_listen_fds(3). The file descriptor is
automatically switched to non-blocking mode and the close-on-exec
flag is set on it.
sd_varlink_server_listen_name() picks up sockets passed in via the
socket activation protocol whose name (as set via $LISTEN_FDNAMES,
i.e. via the FileDescriptorName= setting of the systemd.socket(5)
unit) matches the specified name. For each matching file
descriptor that refers to a listening socket
sd_varlink_server_listen_fd() is invoked; file descriptors that
refer to an already accepted connection are added as connections
via sd_varlink_server_add_connection() instead.
sd_varlink_server_listen_auto() is a convenience wrapper that
automatically determines the sockets to listen on. It first picks
up all socket activation file descriptors named "varlink" (by
calling sd_varlink_server_listen_name() with that name). In
addition, if the $SYSTEMD_VARLINK_LISTEN environment variable is
set, it is used as an additional address to listen on: if set to
"-" the Varlink protocol is spoken on standard input and output
(see sd_varlink_server_add_connection_stdio()), otherwise the
value is passed to sd_varlink_server_listen_address(). This is the
recommended way for a Varlink service to set up its listening
sockets, as it transparently supports both socket activation and
direct invocation (for testing and debugging).
On success, sd_varlink_server_listen_address() and
sd_varlink_server_listen_fd() return a non-negative integer.
sd_varlink_server_listen_name() and
sd_varlink_server_listen_auto() return the number of sockets and
file descriptors they added to the server object (which may be
zero). On failure, these calls return a negative errno-style error
code.
Errors
Returned errors may indicate the following problems:
-EINVAL
An argument is invalid. This is also returned by
sd_varlink_server_listen_address() if the mode parameter
contains bits other than the permission bits and
SD_VARLINK_SERVER_MODE_MKDIR_0755.
-EBADF
The file descriptor passed to sd_varlink_server_listen_fd() is
negative.
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.
sd_varlink_server_listen_address(), sd_varlink_server_listen_fd(),
and sd_varlink_server_listen_auto() were added in version 257.
sd_varlink_server_listen_name() was added in version 258.
systemd(1), sd-varlink(3), sd_varlink_server_new(3),
sd_listen_fds(3), systemd.socket(5), varlinkctl(1)
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 2026-08-04. (At that
time, the date of the most recent commit that was found in the
repository was 2026-08-03.) 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 262~devel SD_VARL...ADDRESS(3)
Pages that refer to this page: systemd.directives(7), systemd.index(7)
|
HTML rendering created 2026-09-09 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. |
|