man/sd_bus_open_user.3

   1 '\" t
   2 .TH "SD_BUS_OPEN_USER" "3" "" "systemd 214" "sd_bus_open_user"
   3 .\" -----------------------------------------------------------------
   4 .\" * Define some portability stuff
   5 .\" -----------------------------------------------------------------
   6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7 .\" http://bugs.debian.org/507673
   8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
   9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 .ie \n(.g .ds Aq \(aq
  11 .el       .ds Aq '
  12 .\" -----------------------------------------------------------------
  13 .\" * set default formatting
  14 .\" -----------------------------------------------------------------
  15 .\" disable hyphenation
  16 .nh
  17 .\" disable justification (adjust text to left margin only)
  18 .ad l
  19 .\" -----------------------------------------------------------------
  20 .\" * MAIN CONTENT STARTS HERE *
  21 .\" -----------------------------------------------------------------
  22 .SH "NAME"
  23 sd_bus_open_user, sd_bus_open_system, sd_bus_open_system_remote, sd_bus_open_system_container, sd_bus_default_user, sd_bus_default_system \- Open a connection to the system or user bus
  24 .SH "SYNOPSIS"
  25 .sp
  26 .ft B
  27 .nf
  28 #include <systemd/sd\-bus\&.h>
  29 .fi
  30 .ft
  31 .HP \w'int\ sd_bus_open_user('u
  32 .BI "int sd_bus_open_user(sd_bus\ **" "bus" ");"
  33 .HP \w'int\ sd_bus_open_system('u
  34 .BI "int sd_bus_open_system(sd_bus\ **" "bus" ");"
  35 .HP \w'int\ sd_bus_open_system_remote('u
  36 .BI "int sd_bus_open_system_remote(const\ char\ *" "host" ", sd_bus\ **" "bus" ");"
  37 .HP \w'int\ sd_bus_open_system_container('u
  38 .BI "int sd_bus_open_system_container(const\ char\ *" "machine" ", sd_bus\ **" "bus" ");"
  39 .HP \w'int\ sd_bus_default_user('u
  40 .BI "int sd_bus_default_user(sd_bus\ **" "bus" ");"
  41 .HP \w'int\ sd_bus_default_system('u
  42 .BI "int sd_bus_default_system(sd_bus\ **" "bus" ");"
  43 .SH "DESCRIPTION"
  44 .PP
  45 \fBsd_bus_open_user()\fR
  46 creates a new bus object and opens a connection to the user bus\&.
  47 \fBsd_bus_open_system()\fR
  48 does the same, but connects to the system bus\&.
  49 .PP
  50 If the
  51 \fI$DBUS_SESSION_BUS_ADDRESS\fR
  52 environment variable is set (cf\&.
  53 \fBenviron\fR(7)), it will be used as the address of the user bus\&. This variable can contain multiple addresses separated by
  54 ";"\&. If this variable is not set, a suitable default for the default user D\-Bus instance will be used\&.
  55 .PP
  56 If the
  57 \fI$DBUS_SYSTEM_BUS_ADDRESS\fR
  58 environment variable is set, it will be used as the address of the system bus\&. This variable uses the same syntax as
  59 \fI$DBUS_SESSION_BUS_ADDRESS\fR/\&. If this variable is not set, a suitable default for the default system D\-Bus instance will be used\&.
  60 .PP
  61 \fBsd_bus_open_system_remote()\fR
  62 connects to the system bus on the specified
  63 \fIhost\fR
  64 using SSH\&.
  65 \fIhost\fR
  66 consists of an optional user name followed by the
  67 "@"
  68 symbol, and the hostname\&.
  69 .PP
  70 \fBsd_bus_open_system_remote()\fR
  71 connects to the system bus in the specified
  72 \fImachine\fR, where
  73 \fImachine\fR
  74 is the name of a container\&. See
  75 \fBmachinectl\fR(1)
  76 for more information about "machines"\&.
  77 .PP
  78 \fBsd_bus_default_user()\fR
  79 returns a bus object connected to the user bus\&. Each thread has its own object, but it may be passed around\&. It is created on the first invocation of
  80 \fBsd_bus_default_user()\fR, and subsequent invocations returns a reference to the same object\&.
  81 .PP
  82 \fBsd_bus_default_system()\fR
  83 is similar to
  84 \fBsd_bus_default_user()\fR, but connects to the system bus\&.
  85 .SH "RETURN VALUE"
  86 .PP
  87 On success, these calls return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&.
  88 .SH "REFERENCE OWNERSHIP"
  89 .PP
  90 Functions
  91 \fBsd_bus_open_user()\fR,
  92 \fBsd_bus_open_system()\fR,
  93 \fBsd_bus_open_system_remote()\fR, and
  94 \fBsd_bus_open_system_machine()\fR
  95 return a new object and the caller owns the sole reference\&. When not needed anymore, this reference should be destroyed with
  96 \fBsd_bus_unref\fR(3)\&.
  97 .PP
  98 The functions
  99 \fBsd_bus_default_user()\fR
 100 and
 101 \fBsd_bus_default_system()\fR
 102 do not create a new reference\&.
 103 .SH "ERRORS"
 104 .PP
 105 Returned errors may indicate the following problems:
 106 .PP
 107 \fI\-EINVAL\fR
 108 .RS 4
 109 Specified parameter is invalid (\fBNULL\fR
 110 in case of output parameters)\&.
 111 .RE
 112 .PP
 113 \fI\-ENOMEM\fR
 114 .RS 4
 115 Memory allocation failed\&.
 116 .RE
 117 .PP
 118 In addition, any further connection\-related errors may be by returned\&. See
 119 \fBsd_bus_send\fR(3)\&.
 120 .SH "NOTES"
 121 .PP
 122 \fBsd_bus_open_user()\fR
 123 and other functions described here are available as a shared library, which can be compiled and linked to with the
 124 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
 125 file\&.
 126 .SH "SEE ALSO"
 127 .PP
 128 \fBsystemd\fR(1),
 129 \fBsd-bus\fR(3),
 130 \fBsd_bus_new\fR(3),
 131 \fBsd_bus_ref\fR(3),
 132 \fBsd_bus_unref\fR(3),
 133 \fBssh\fR(1),
 134 \fBsystemd-machined.service\fR(8),
 135 \fBmachinectl\fR(1)