From: Lennart Poettering Date: Fri, 22 May 2026 13:04:38 +0000 (+0200) Subject: man: add sd_varlink_connect_address() man page X-Git-Tag: v261-rc2~54 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e69cc9eb36fd6e76710b4d5f4bb7013980fb5174;p=thirdparty%2Fsystemd.git man: add sd_varlink_connect_address() man page --- diff --git a/man/rules/meson.build b/man/rules/meson.build index 6fd43ad4c33..d3df447352d 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -967,6 +967,13 @@ manpages = [ 'sd_uid_get_sessions', 'sd_uid_is_on_seat'], 'HAVE_PAM'], + ['sd_varlink_connect_address', + '3', + ['sd_varlink_connect_exec', + 'sd_varlink_connect_fd', + 'sd_varlink_connect_fd_pair', + 'sd_varlink_connect_url'], + ''], ['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'], ''], diff --git a/man/sd_varlink_connect_address.xml b/man/sd_varlink_connect_address.xml new file mode 100644 index 00000000000..d77a0ae4b7c --- /dev/null +++ b/man/sd_varlink_connect_address.xml @@ -0,0 +1,335 @@ + + + + + + + + sd_varlink_connect_address + systemd + + + + sd_varlink_connect_address + 3 + + + + sd_varlink_connect_address + sd_varlink_connect_exec + sd_varlink_connect_url + sd_varlink_connect_fd + sd_varlink_connect_fd_pair + + Create a Varlink connection object and connect it to a service + + + + + #include <systemd/sd-varlink.h> + + struct ucred; /* defined in <sys/socket.h> */ + + + int sd_varlink_connect_address + sd_varlink **ret + const char *address + + + + int sd_varlink_connect_exec + sd_varlink **ret + const char *command + char **argv + + + + int sd_varlink_connect_url + sd_varlink **ret + const char *url + + + + int sd_varlink_connect_fd + sd_varlink **ret + int fd + + + + int sd_varlink_connect_fd_pair + sd_varlink **ret + int input_fd + int output_fd + const struct ucred *override_ucred + + + + + + Description + + These five functions allocate a new client-side Varlink connection object and connect it to a + Varlink service. They differ only in how the service to talk to is specified. On success, a reference to + the new connection object is returned in ret; the caller owns this reference and + must eventually release it with + sd_varlink_unref3, + sd_varlink_close_unref3 + or + sd_varlink_flush_close_unref3. + + All five functions return immediately; none of them blocks waiting for the connection to be fully + established. For socket-based connections the actual connect() may still be in + progress when the function returns (see below); the connection object handles the completion + transparently. + + The returned connection object is not attached to any event loop. There are three ways to drive it: + attach it to an + sd-event3 loop with + sd_varlink_attach_event3; + run its I/O manually via + sd_varlink_process3 and + sd_varlink_wait3; or + simply issue blocking method calls. In particular it is perfectly fine to follow any of these connection + functions directly with a synchronous, blocking call such as + sd_varlink_call3, which + internally drives the connection (including completing a still-pending + connect()) and returns once the reply has been received. In that case no explicit + event loop integration or manual processing is required. + + sd_varlink_connect_address() connects to an AF_UNIX + stream socket whose address is given as a string in address. The address must + begin either with / (to reference a socket in the file system) or with + @ (to reference a socket in the abstract namespace, with the remainder of the string + used as the abstract name). It must be at least two characters long. No other forms are accepted (in + particular, relative paths are refused). Abstract namespace names that embed NUL + bytes cannot be expressed through this interface. If a file system socket path is too long to fit into a + sockaddr_un structure, the connection is established transparently via an + O_PATH indirection, so overlong paths work. + + sd_varlink_connect_exec() forks off a child process and speaks the Varlink + protocol with it over a connected AF_UNIX SOCK_STREAM socket + pair. command is the program to execute; it is looked up in $PATH + in the usual way (i.e. via execvp3). + argv is the argument vector (a NULL-terminated string array) + to pass to the child as its argv[]; if it is NULL or empty, an + argument vector consisting of just command is synthesized. The connected socket is + handed to the child as file descriptor 3 using the + sd_listen_fds3 + protocol, i.e. the child is invoked with $LISTEN_FDS set to + 1, $LISTEN_FDNAMES set to varlink, and the + appropriate $LISTEN_PID (and, where available, $LISTEN_PIDFDID) + variables. The command and argv strings are copied into the + connection object, so the caller may free or modify them once the function returns. + + sd_varlink_connect_url() is a higher-level interface that parses a service + address string with a leading scheme and dispatches to the appropriate transport. Despite the name, these + strings are not Internet URLs in the sense of the relevant RFCs. The following schemes + are understood natively: + + + + unix:PATH + Connects to an AF_UNIX socket, equivalent to passing + PATH to sd_varlink_connect_address(). + PATH must either be an absolute, normalized file system path, or begin with + @ for an abstract namespace socket (for which no path normalization checks are + applied). + + + + exec:PATH + Forks off the executable at PATH, equivalent to passing it + to sd_varlink_connect_exec() with no extra arguments. PATH + must be an absolute, normalized path. + + + + ssh:HOST:PATH + ssh-unix:HOST:PATH + Connects to an AF_UNIX socket at the absolute, normalized path + PATH on the remote SSH host HOST. This relies on + OpenSSH 9.4 or newer on the server side. Abstract namespace sockets are not supported for this + transport. ssh: and ssh-unix: are synonyms. + + + + ssh-exec:HOST:COMMAND + Invokes COMMAND (a command line, split on whitespace with + shell-style quoting and unescaping) on the remote SSH host HOST and speaks + the Varlink protocol over its standard input and output. + + + + If the scheme is none of the above but is otherwise a syntactically valid URL scheme, + sd_varlink_connect_url() looks for a bridge helper binary of that + name in the directory configured via $SYSTEMD_VARLINK_BRIDGES_DIR (see below). If found + and executable, it is invoked like an exec: transport, with the complete, unmodified URL + passed as its sole command line argument. This allows additional transports to be plugged in out of tree. + + For the natively supported schemes, URL parameterization using ;, + ? or # is rejected (these are reserved for possible future use). A + vsock: scheme is not currently supported. + + sd_varlink_connect_fd() turns an already existing, already connected file + descriptor fd into a Varlink connection. The descriptor is used for both reading and + writing. It may refer to a connected stream socket, but also to a pipe or other bidirectional file + descriptor. + + sd_varlink_connect_fd_pair() is like + sd_varlink_connect_fd(), but accepts a separate input_fd (used + for reading from the peer) and output_fd (used for writing to the peer). This is + useful when the two directions are backed by different descriptors, for example a pair of pipes, or the + standard output and standard input of a co-process. The two descriptors may also be identical, which is + exactly what sd_varlink_connect_fd() does internally. If + override_ucred is non-NULL, the peer credentials reported for + the connection (as returned e.g. by + sd_varlink_get_peer_uid3) + are taken from the supplied ucred structure instead of being queried from the + socket via SO_PEERCRED. This is primarily useful when the descriptors are not sockets + (and hence carry no kernel-supplied peer credentials), or when the credentials need to be overridden for + other reasons. If override_ucred is NULL, peer credentials are + determined from the socket as usual. + + sd_varlink_connect_fd() and sd_varlink_connect_fd_pair() take + over ownership of the descriptors passed to them: the descriptors are closed automatically when the + connection object is freed, and the caller must not close them itself. On failure ownership remains with + the caller. + + The connection objects created by sd_varlink_connect_exec(), and by the + exec:, ssh:/ssh-unix:, + ssh-exec: and bridge-helper paths of sd_varlink_connect_url(), + are bound to the lifetime of the spawned child process. When such a connection object is freed, the + associated child process is sent SIGTERM and reaped. The child is also configured to + receive SIGTERM if the calling process dies. + + + + Return Value + + On success, these functions return a non-negative integer and store a pointer to the new connection + object in ret. On failure, they return a negative errno-style error code and leave + ret unchanged. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + A required argument is NULL, or the supplied address, command, + or URL is malformed. This includes addresses that do not begin with / or + @, abstract namespace names that do not fit into a + sockaddr_un structure, and — for + sd_varlink_connect_url() — file system paths that are not absolute or not + normalized. + + + + -EBADF + + For sd_varlink_connect_fd() and + sd_varlink_connect_fd_pair(): a supplied file descriptor is + negative. + + + + -EPROTONOSUPPORT + + For sd_varlink_connect_url(): the URL contains no + : separator, uses an unsupported scheme for which no bridge helper binary is + available, or makes use of the reserved ;, ? or + # URL parameterization characters with a natively supported + scheme. + + + + -ENOMEM + + Memory allocation failed. + + + + In addition, these functions may propagate any error returned by the underlying system calls they + use, such as socket2, + connect2, + fork2, + pipe2 + and the various execution helpers. + + + + + + + Environment + + + + $SYSTEMD_SSH + + Used by the ssh:/ssh-unix: and + ssh-exec: transports of sd_varlink_connect_url() to override + the ssh binary to invoke. May be a plain file name (looked up in + $PATH) or an absolute path. + + + + + + $SYSTEMD_VARLINK_BRIDGES_DIR + + Overrides the directory in which + sd_varlink_connect_url() looks up bridge helper binaries for non-native URL + schemes. Defaults to /usr/lib/systemd/varlink-bridges/. + + + + + + + + Files + + + + /usr/lib/systemd/varlink-bridges/ + + Default directory searched for bridge helper binaries when + sd_varlink_connect_url() encounters a URL with a scheme that is not natively + supported. See + sd-varlink3 for + details. + + + + + + History + sd_varlink_connect_address(), + sd_varlink_connect_exec(), sd_varlink_connect_url(), + sd_varlink_connect_fd() and sd_varlink_connect_fd_pair() were + added in version 257. + + + + See Also + + + systemd1 + sd-varlink3 + sd_varlink_attach_event3 + sd_varlink_call3 + sd_varlink_send3 + sd_varlink_is_connected3 + sd_listen_fds3 + varlinkctl1 + + + +