diff --git a/man/rules/meson.build b/man/rules/meson.build index 0be4b9c86c..4e04b413e9 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -330,6 +330,7 @@ manpages = [ 'sd_bus_release_name_async', 'sd_bus_request_name_async'], ''], + ['sd_bus_set_address', '3', ['sd_bus_get_address'], ''], ['sd_bus_set_close_on_exit', '3', ['sd_bus_get_close_on_exit'], ''], ['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''], ['sd_bus_set_description', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 14fca6ee6b..66b022e6ea 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -54,6 +54,7 @@ sd-bus-errors3, sd_bus_error3, sd_bus_error_add_map3, +sd_bus_get_address3, sd_bus_get_fd3, sd_bus_get_n_queued_read3, sd_bus_message_append3, @@ -85,6 +86,7 @@ sd_bus_process3, sd_bus_reply_method_error3, sd_bus_request_name3, +sd_bus_set_address3, sd_bus_set_connected_signal3, sd_bus_set_description3, sd_bus_set_sender3, diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index ca06f8e6f4..a46b1cb488 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -186,14 +186,14 @@ Note that entering a container is a privileged operation, and will likely only work for the root user on the remote machine. - sd_bus_open_system_machine() connects - to the system bus in the specified machine, - where machine is the name of a local - container. See - machinectl1 - for more information about the "machine" concept. Note that - connections into local containers are only available to privileged - processes at this time. + sd_bus_open_system_machine() connects to the system bus in the specified + machine, where machine is the name of a local + container. See + sd_bus_set_address3 + for a description of the address syntax, and + machinectl1 for more + information about the "machine" concept. Note that connections into local containers are only available + to privileged processes at this time. These calls allocate a bus connection object and initiate the connection to a well-known bus of some form. An alternative to diff --git a/man/sd_bus_set_address.xml b/man/sd_bus_set_address.xml new file mode 100644 index 0000000000..b022741ff4 --- /dev/null +++ b/man/sd_bus_set_address.xml @@ -0,0 +1,176 @@ + + + + + + + + sd_bus_set_address + systemd + + + + sd_bus_set_address + 3 + + + + sd_bus_set_address + sd_bus_get_address + + Set or query the address of the bus connection + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_set_address + sd_bus *bus + const char* address + + + + int sd_bus_get_address + sd_bus *bus + const char** address + + + + + + + Description + + sd_bus_set_address() configures a list of addresses of bus brokers to try to + connect to from a subsequent + sd_bus_start3 call. + The argument is a ;-separated list of addresses to try. Each item must be one of the + following: + + + + + A unix socket address specified as + unix:guid=guid,path=path or + unix:guid=guid,abstract=path. + Exactly one of the path= and abstract= keys must be present, + while guid= is optional. + + + + A TCP socket address specified as + tcp:[guid=guid,][host=host][,port=port][,family=family]. + One or both of the host= and port= keys must be present, while + the rest is optional. family may be either or + . + + + + An executable to spawn specified as + unixexec:guid=guid,path=path,argv1=argument,argv2=argument,.... + The path= key must be present, while guid= is optional. + + + + A machine (container) to connect to specified as + x-machine-unix:guid=guid,machine=machine,pid=pid. + Exactly one of the machine= and pid= keys must be present, + while guid= is optional. machine is the name of a local + container. See + machinectl1 for + more information about the "machine" concept. machine=.host may be used to specify + the host machine. A connection to the standard system bus socket inside of the specified machine will + be created. + + + + In all cases, parameter guid is an identifier of the remote peer, in the + syntax accepted by + sd_id128_from_string3. + If specified, the identifier returned by the peer after the connection is established will be checked and + the connection will be rejected in case of a mismatch. + + Note that the addresses passed to sd_bus_set_address() may not be verified + immediately. If they are invalid, an error may be returned e.g. from a subsequent call to + sd_bus_start3. + + + sd_bus_get_address() returns any previously set addresses. In addition to + being explicitly set by sd_bus_set_address(), the address will also be set + automatically by + sd_bus_open3 and + similar calls, based on environment variables or built-in defaults. + + + + Return Value + + On success, these functions return a non-negative integer. On failure, they return a negative + errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The input parameters bus or address are NULL. + + + + + -ENOPKG + + The bus object bus could not be resolved. + + + + + -EPERM + + The input parameter bus is in a wrong state + (sd_bus_set_address() may only be called once on a newly-created bus object). + + + + + -ECHILD + + The bus object bus was created in a different + process. + + + + + -ENODATA + + The bus object bus has no address configured. + + + + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_start3, + systemd-machined.service8, + machinectl1 + + + +