From 4160043a0fac8b812905b7502ce34adf3af538f1 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Tue, 6 Sep 2016 02:27:18 -0400 Subject: move man pages to appropriate directories --- man/sd_bus_default.xml | 312 ------------------------------------------------- 1 file changed, 312 deletions(-) delete mode 100644 man/sd_bus_default.xml (limited to 'man/sd_bus_default.xml') diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml deleted file mode 100644 index 6d5a90de72..0000000000 --- a/man/sd_bus_default.xml +++ /dev/null @@ -1,312 +0,0 @@ - - - - - - - - - sd_bus_default - systemd - - - - A monkey with a typewriter - Zbigniew - Jędrzejewski-Szmek - zbyszek@in.waw.pl - - - - - - sd_bus_default - 3 - - - - sd_bus_default - sd_bus_default_user - sd_bus_default_system - - sd_bus_open - sd_bus_open_user - sd_bus_open_system - sd_bus_open_system_remote - sd_bus_open_system_machine - - Acquire a connection to a system or user bus - - - - - #include <systemd/sd-bus.h> - - - int sd_bus_default - sd_bus **bus - - - - int sd_bus_default_user - sd_bus **bus - - - - int sd_bus_default_system - sd_bus **bus - - - - int sd_bus_open - sd_bus **bus - - - - int sd_bus_open_user - sd_bus **bus - - - - int sd_bus_open_system - sd_bus **bus - - - - int sd_bus_open_system_remote - sd_bus **bus - const char *host - - - - int sd_bus_open_system_machine - sd_bus **bus - const char *machine - - - - - - - Description - - sd_bus_default() acquires a bus - connection object to the user bus when invoked in user context, or - to the system bus otherwise. The connection object is associated - with the calling thread. Each time the function is invoked from - the same thread, the same object is returned, but its reference - count is increased by one, as long as at least one reference is - kept. When the last reference to the connection is dropped (using - the - sd_bus_unref3 - call), the connection is terminated. Note that the connection is - not automatically terminated when the associated thread ends. It - is important to drop the last reference to the bus connection - explicitly before the thread ends, as otherwise, the connection will - leak. Also, queued but unread or unwritten messages keep the - bus referenced, see below. - - sd_bus_default_user() returns a user - bus connection object associated with the calling thread. - sd_bus_default_system() is similar, but - connects to the system bus. Note that - sd_bus_default() is identical to these two - calls, depending on the execution context. - - sd_bus_open() creates a new, - independent bus connection to the user bus when invoked in user - context, or the system bus - otherwise. sd_bus_open_user() is similar, but - connects only to the user bus. - sd_bus_open_system() does the same, but - connects to the system bus. In contrast to - sd_bus_default(), - sd_bus_default_user(), and - sd_bus_default_system(), these calls return - new, independent connection objects that are not associated with - the invoking thread and are not shared between multiple - invocations. It is recommended to share connections per thread to - efficiently make use the available resources. Thus, it is - recommended to use sd_bus_default(), - sd_bus_default_user() and - sd_bus_default_system() to connect to the - user or system buses. - - If the $DBUS_SESSION_BUS_ADDRESS environment - variable is set - (cf. environ7), - it will be used as the address of the user bus. This variable can - contain multiple addresses separated by ;. If - this variable is not set, a suitable default for the default user - D-Bus instance will be used. - - If the $DBUS_SYSTEM_BUS_ADDRESS - environment variable is set, it will be used as the address of the - system bus. This variable uses the same syntax as - $DBUS_SESSION_BUS_ADDRESS. If this variable is - not set, a suitable default for the default system D-Bus instance - will be used. - - sd_bus_open_system_remote() connects to - the system bus on the specified host using - ssh1. host - consists of an optional user name followed by the - @ symbol, and the hostname. - - - 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. - - These calls allocate a bus connection object and initiate - the connection to a well-known bus of some form. An alternative to - using these high-level calls is to create an unconnected bus - object with - sd_bus_new3 - and to connect it with - sd_bus_start3. - - - - - - Reference ownership - The functions sd_bus_open(), - sd_bus_open_user(), - sd_bus_open_system(), - sd_bus_open_system_remote(), and - sd_bus_open_system_machine() return a new - connection object and the caller owns the sole reference. When not - needed anymore, this reference should be destroyed with - sd_bus_unref3. - - - The functions sd_bus_default(), - sd_bus_default_user() and - sd_bus_default_system() do not necessarily - create a new object, but increase the connection reference of an - existing connection object by one. Use - sd_bus_unref3 - to drop the reference. - - Queued but unwritten/unread messages also keep a reference - to their bus connection object. For this reason, even if an - application dropped all references to a bus connection, it might - not get destroyed right away. Until all incoming queued - messages are read, and until all outgoing unwritten messages are - written, the bus object will stay - alive. sd_bus_flush() may be used to write - all outgoing queued messages so they drop their references. To - flush the unread incoming messages, use - sd_bus_close(), which will also close the bus - connection. When using the default bus logic, it is a good idea to - first invoke sd_bus_flush() followed by - sd_bus_close() when a thread or process - terminates, and thus its bus connection object should be - freed. - - The life cycle of the default bus connection should be the - responsibility of the code that creates/owns the thread the - default bus connection object is associated with. Library code - should neither call sd_bus_flush() nor - sd_bus_close() on default bus objects unless - it does so in its own private, self-allocated thread. Library code - should not use the default bus object in other threads unless it - is clear that the program using it will life cycle the bus - connection object and flush and close it before exiting from the - thread. In libraries where it is not clear that the calling - program will life cycle the bus connection object, it is hence - recommended to use sd_bus_open_system() - instead of sd_bus_default_system() and - related calls. - - - - Return Value - - On success, these calls return 0 or a positive - integer. On failure, these calls return a negative - errno-style error code. - - - - Errors - - Returned errors may indicate the following problems: - - - - - -EINVAL - - The specified parameters are invalid. - - - - -ENOMEM - - Memory allocation failed. - - - - -ESOCKTNOSUPPORT - - The protocol version required to connect to the selected bus is not supported. - - - - In addition, any further connection-related errors may be - by returned. See sd_bus_send3. - - - - Notes - - sd_bus_open_user() and the other - functions described here are available as a shared library, which - can be compiled and linked to with the - libsystemd pkg-config1 - file. - - - - See Also - - - systemd1, - sd-bus3, - sd_bus_new3, - sd_bus_ref3, - sd_bus_unref3, - ssh1, - systemd-machined.service8, - machinectl1 - - - - -- cgit v1.2.3-54-g00ecf