--- name: "sd_varlink_server_listen_address" section: "3" platform: "linux" package: "systemd-libs" version: "262.1-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/sd_varlink_server_listen_address" --- # sd\_varlink\_server\_listen\_address(3) Bind a Varlink server object to listening sockets ## NAME 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 ## SYNOPSIS ``` #include ``` ``` #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***);** ## DESCRIPTION These functions add listening sockets to a Varlink server object, as previously allocated with [**sd\_varlink\_server\_new**(3)](/sd_varlink_server_new/3.md). 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)](/chmod/2.md). 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)](/connect/2.md) 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)](/sd-varlink/3.md)). 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)](/sd_listen_fds/3.md). 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)](/systemd.socket/5.md) 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. ### 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. ## NOTES Functions described here are available as a shared library, which can be compiled against and linked to with the **libsystemd** [**pkg-config**(1)](/pkg-config/1.md) file. The code described here uses [**getenv**(3)](/getenv/3.md), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call [**setenv**(3)](/setenv/3.md) 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)](/systemd/1.md), [**sd-varlink**(3)](/sd-varlink/3.md), [**sd\_varlink\_server\_new**(3)](/sd_varlink_server_new/3.md), [**sd\_listen\_fds**(3)](/sd_listen_fds/3.md), [**systemd.socket**(5)](/systemd.socket/5.md), [**varlinkctl**(1)](/varlinkctl/1.md)