X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_bus_negotiate_fds.xml;h=61c972008bebaa872790cab9bf1707e34c47e079;hp=38e1fad68a68be18ec6602209a26cbb459116762;hb=9742b1e43855b1599bd52ff95af995d9a9d35eac;hpb=ce236b57bee9a081d62db04bcc5be34e3ba6d217 diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml index 38e1fad68..61c972008 100644 --- a/man/sd_bus_negotiate_fds.xml +++ b/man/sd_bus_negotiate_fds.xml @@ -1,30 +1,30 @@ - + - + - sd_bus_new + sd_bus_negotiate_fds systemd @@ -44,7 +44,7 @@ along with systemd; If not, see . sd_bus_negotiate_fds - sd_bus_negotiate_timestamps + sd_bus_negotiate_timestamp sd_bus_negotiate_creds Control feature negotiation on bus connections @@ -70,6 +70,7 @@ along with systemd; If not, see . int sd_bus_negotiate_creds sd_bus *bus int b + uint64_t mask @@ -79,60 +80,66 @@ along with systemd; If not, see . sd_bus_negotiate_fds() controls whether file descriptor passing shall be negotiated for the specified bus - connection. Takes a bus object and a boolean, which when true - enables file descriptor passing, and when false disables it. Note - that not all transports and servers support file descriptor - passing. To find out whether file descriptor passing is available - after negotiation use + connection. It takes a bus object and a boolean, which, when true, + enables file descriptor passing, and, when false, disables + it. Note that not all transports and servers support file + descriptor passing. In particular, networked transports generally + do not support file descriptor passing. To find out whether file + descriptor passing is available after negotiation, use sd_bus_can_send3 and pass SD_BUS_TYPE_UNIX_FD. Note that file descriptor passing is always enabled for both sending and receiving or for neither, but never only in one direction. By - default file descriptor passing is negotiated for all + default, file descriptor passing is negotiated for all connections. - Note that when bus activation is used it is highly + Note that when bus activation is used, it is highly recommended to set the setting in the .busname unit file to the same setting as negotiated by the program ultimately activated. By - default file descriptor passing is enabled for both. + default, file descriptor passing is enabled for both. - sd_bus_negotiate_timestamps() controls - whether implicit sender timestamps shall be attached automatically - to all incoming messages. Takes a bus object and a boolean, which - when true enables timestamping, and when false disables it. If - this is disabled, + sd_bus_negotiate_timestamp() controls whether implicit sender + timestamps shall be attached automatically to all incoming messages. Takes a bus object and a + boolean, which, when true, enables timestamping, and, when false, disables it. Use sd_bus_message_get_monotonic_usec3, sd_bus_message_get_realtime_usec3, - sd_bus_message_get_seqno3 - fail with -ENODATA on incoming messages. Note - that not all transports support timestamping of messages. On local - transports the timestamping is applied by the kernel and cannot be - manipulated by userspace. - - sd_bus_negotiate_creds() controls - whether implicit sender credentials shall be attached - automatically to all incoming messages. Takes a bus object and a - bit mask value, which controls which credential parameters are - attached. If this is not used, - sd_bus_message_get_creds3 - fails with -ENODATA on incoming - messages. Note that not all transports support attaching sender - credentials to messages, or do not support all types of sender - credential parameters. On local transports the sender credentials - are attached by the kernel and cannot be manipulated by - userspace. By default no sender credentials are attached. - - These functions may be called only before the connection has - been started with - sd_bus_start3. + sd_bus_message_get_seqnum3 + to query the timestamps of incoming messages. If negotiation is disabled or not supported, these + calls will fail with -ENODATA. Note that currently no transports support + timestamping of messages. By default, message timestamping is not negotiated for + connections. + + sd_bus_negotiate_creds() controls whether and which implicit sender + credentials shall be attached automatically to all incoming messages. Takes a bus object and a + boolean indicating whether to enable or disable the credential parts encoded in the bit mask + value argument. Note that not all transports support attaching sender credentials to messages, + or do not support all types of sender credential parameters, or might suppress them under + certain circumstances for individual messages. Specifically, dbus1 only supports + SD_BUS_CREDS_UNIQUE_NAME. The sender credentials are suitable for + authorization decisions. By default, only SD_BUS_CREDS_WELL_KNOWN_NAMES and + SD_BUS_CREDS_UNIQUE_NAME are enabled. In fact, these two credential fields + are always sent along and cannot be turned off. + + The sd_bus_negotiate_fds() function may + be called only before the connection has been started with + sd_bus_start3. Both + sd_bus_negotiate_timestamp() and + sd_bus_negotiate_creds() may also be called + after a connection has been set up. Note that, when operating on a + connection that is shared between multiple components of the same + program (for example via + sd_bus_default3), + it is highly recommended to only enable additional per message + metadata fields, but never disable them again, in order not to + disable functionality needed by other components. Return Value - On success, these functions returns 0 or a - positive integer. On failure, it returns a negative errno-style + On success, these functions return 0 or a + positive integer. On failure, they return a negative errno-style error code. @@ -143,7 +150,7 @@ along with systemd; If not, see . - -EPERM + -EPERM The bus connection has already been started. @@ -153,10 +160,10 @@ along with systemd; If not, see . Notes - sd_bus_negotiate_fs() and the other + sd_bus_negotiate_fds() and the other functions described here are available as a shared library, which can be compiled and linked to with the - libsystemd pkg-config1 + libelogind pkg-config1 file. @@ -169,7 +176,10 @@ along with systemd; If not, see . sd_bus_start3, sd_bus_message_can_send3, sd_bus_message_get_monotonic_usec3, - sd_bus_message_get_creds3 + sd_bus_message_get_realtime_usec3, + sd_bus_message_get_seqnum3, + sd_bus_message_get_creds3, + systemd.busname5