Description¶

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).

Return Value¶

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.

Notes¶

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¶

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.

See Also¶

systemd(1), sd-varlink(3), sd_varlink_server_new(3), sd_listen_fds(3), systemd.socket(5), varlinkctl(1)