'\" t
.TH "SD_VARLINK_SERVER_LISTEN_ADDRESS" "3" "" "systemd 262" "sd_varlink_server_listen_address"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "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
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-varlink\&.h>
.fi
.ft
.sp
.ft B
.nf
#define SD_VARLINK_SERVER_MODE_MKDIR_0755 \&...
.fi
.ft
.HP \w'int\ sd_varlink_server_listen_address('u
.BI "int sd_varlink_server_listen_address(sd_varlink_server*\ " "server" ", const\ char*\ " "address" ", mode_t\ " "mode" ");"
.HP \w'int\ sd_varlink_server_listen_fd('u
.BI "int sd_varlink_server_listen_fd(sd_varlink_server*\ " "server" ", int\ " "fd" ");"
.HP \w'int\ sd_varlink_server_listen_name('u
.BI "int sd_varlink_server_listen_name(sd_varlink_server*\ " "server" ", const\ char*\ " "name" ");"
.HP \w'int\ sd_varlink_server_listen_auto('u
.BI "int sd_varlink_server_listen_auto(sd_varlink_server*\ " "server" ");"
.SH "DESCRIPTION"
.PP
These functions add listening sockets to a Varlink server object, as previously allocated with
\fBsd_varlink_server_new\fR(3)\&. Once the server object is attached to an event loop (see
\fBsd_varlink_server_attach_event()\fR) it will accept incoming connections on the configured sockets and dispatch the registered method calls\&.
.PP
\fBsd_varlink_server_listen_address()\fR
allocates a new
\fBAF_UNIX\fR
socket, binds it to the specified
\fIaddress\fR, and starts listening on it\&. The
\fIaddress\fR
is a file system path of the socket to bind to\&. (Use
\fBsd_varlink_server_listen_fd()\fR
below for sockets in the abstract namespace, in foreign address families, or that are otherwise already allocated\&.)
.PP
The
\fImode\fR
parameter specifies the file system access mode to apply to the socket inode, i\&.e\&. a bit mask of permission bits as in
\fBchmod\fR(2)\&. Only the lower nine bits (\fB0777\fR) are permitted\&. The special value
\fB(mode_t) \-1\fR
may be specified to pick a suitable default: this is
\fB0666\fR
in the general case, but
\fB0644\fR
if the server was allocated with the
\fBSD_VARLINK_SERVER_ROOT_ONLY\fR
or
\fBSD_VARLINK_SERVER_MYSELF_ONLY\fR
flags (the reason being that it is the
"w"
bit that controls
\fBconnect\fR(2)
access, while leaving the
"r"
bit on permits other users to read the socket\*(Aqs extended attributes, which makes the socket recognizable as a Varlink entrypoint, see
\fBsd-varlink\fR(3))\&.
.PP
The constant
\fBSD_VARLINK_SERVER_MODE_MKDIR_0755\fR
may be OR\-ed into the
\fImode\fR
parameter (this is not supported if the mode is specified as
\fB(mode_t) \-1\fR)\&. If specified, and
\fIaddress\fR
is an absolute path, the leading directories of the socket path are automatically created (with access mode
\fB0755\fR) if they are missing\&.
.PP
\fBsd_varlink_server_listen_fd()\fR
adds an already allocated and listening socket to the server object, referenced by the file descriptor
\fIfd\fR\&. This is typically used in conjunction with socket activation, to make use of a listening socket passed in from the service manager, see
\fBsd_listen_fds\fR(3)\&. The file descriptor is automatically switched to non\-blocking mode and the close\-on\-exec flag is set on it\&.
.PP
\fBsd_varlink_server_listen_name()\fR
picks up sockets passed in via the socket activation protocol whose name (as set via
\fI$LISTEN_FDNAMES\fR, i\&.e\&. via the
\fIFileDescriptorName=\fR
setting of the
\fBsystemd.socket\fR(5)
unit) matches the specified
\fIname\fR\&. For each matching file descriptor that refers to a listening socket
\fBsd_varlink_server_listen_fd()\fR
is invoked; file descriptors that refer to an already accepted connection are added as connections via
\fBsd_varlink_server_add_connection()\fR
instead\&.
.PP
\fBsd_varlink_server_listen_auto()\fR
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
\fBsd_varlink_server_listen_name()\fR
with that name)\&. In addition, if the
\fI$SYSTEMD_VARLINK_LISTEN\fR
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
\fBsd_varlink_server_add_connection_stdio()\fR), otherwise the value is passed to
\fBsd_varlink_server_listen_address()\fR\&. 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)\&.
.SH "RETURN VALUE"
.PP
On success,
\fBsd_varlink_server_listen_address()\fR
and
\fBsd_varlink_server_listen_fd()\fR
return a non\-negative integer\&.
\fBsd_varlink_server_listen_name()\fR
and
\fBsd_varlink_server_listen_auto()\fR
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\&.
.SS "Errors"
.PP
Returned errors may indicate the following problems:
.PP
\fB\-EINVAL\fR
.RS 4
An argument is invalid\&. This is also returned by
\fBsd_varlink_server_listen_address()\fR
if the
\fImode\fR
parameter contains bits other than the permission bits and
\fBSD_VARLINK_SERVER_MODE_MKDIR_0755\fR\&.
.RE
.PP
\fB\-EBADF\fR
.RS 4
The file descriptor passed to
\fBsd_varlink_server_listen_fd()\fR
is negative\&.
.RE
.SH "NOTES"
.PP
Functions described here are available as a shared library, which can be compiled against and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.PP
The code described here uses
\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
\fBsetenv\fR(3)
from a parallel thread\&. It is recommended to only do calls to
\fBsetenv()\fR
from an early phase of the program when no other threads have been started\&.
.SH "HISTORY"
.PP
\fBsd_varlink_server_listen_address()\fR,
\fBsd_varlink_server_listen_fd()\fR, and
\fBsd_varlink_server_listen_auto()\fR
were added in version 257\&.
.PP
\fBsd_varlink_server_listen_name()\fR
was added in version 258\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsd-varlink\fR(3), \fBsd_varlink_server_new\fR(3), \fBsd_listen_fds\fR(3), \fBsystemd.socket\fR(5), \fBvarlinkctl\fR(1)