diff --git a/man/rules/meson.build b/man/rules/meson.build index b37eb5f19f..974d9eee4b 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -977,6 +977,12 @@ manpages = [ ['sd_varlink_is_connected', '3', ['sd_varlink_is_idle'], ''], ['sd_varlink_push_fd', '3', ['sd_varlink_push_dup_fd'], ''], ['sd_varlink_send', '3', ['sd_varlink_sendb', 'sd_varlink_sendbo'], ''], + ['sd_varlink_server_listen_address', + '3', + ['sd_varlink_server_listen_auto', + 'sd_varlink_server_listen_fd', + 'sd_varlink_server_listen_name'], + ''], ['sd_varlink_server_new', '3', [], ''], ['sd_varlink_set_description', '3', ['sd_varlink_get_description'], ''], ['sd_varlink_set_relative_timeout', '3', [], ''], diff --git a/man/sd_varlink_server_listen_address.xml b/man/sd_varlink_server_listen_address.xml new file mode 100644 index 0000000000..55858c1c99 --- /dev/null +++ b/man/sd_varlink_server_listen_address.xml @@ -0,0 +1,181 @@ + + + + + + + + sd_varlink_server_listen_address + systemd + + + + sd_varlink_server_listen_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 + + + + + + + Description + + These functions add listening sockets to a Varlink server object, as previously allocated with + sd_varlink_server_new3. + 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 + chmod2. + 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 + connect2 + 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-varlink3). + + 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_fds3. 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.socket5 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. + + + + + + + + + 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 + + + systemd1 + sd-varlink3 + sd_varlink_server_new3 + sd_listen_fds3 + systemd.socket5 + varlinkctl1 + + + +