ipc/kdbus/Documentation/kdbus.endpoint.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <refentry id="kdbus.endpoint">
   6
   7   <refentryinfo>
   8     <title>kdbus.endpoint</title>
   9     <productname>kdbus.endpoint</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>kdbus.endpoint</refentrytitle>
  14     <manvolnum>7</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>kdbus.endpoint</refname>
  19     <refpurpose>kdbus endpoint</refpurpose>
  20   </refnamediv>
  21
  22   <refsect1>
  23     <title>Description</title>
  24
  25     <para>
  26       Endpoints are entry points to a bus (see
  27       <citerefentry>
  28         <refentrytitle>kdbus.bus</refentrytitle>
  29         <manvolnum>7</manvolnum>
  30       </citerefentry>).
  31       By default, each bus has a default
  32       endpoint called 'bus'. The bus owner has the ability to create custom
  33       endpoints with specific names, permissions, and policy databases
  34       (see below). An endpoint is presented as file underneath the directory
  35       of the parent bus.
  36     </para>
  37     <para>
  38       To create a custom endpoint, open the default endpoint
  39       (<literal>bus</literal>) and use the
  40       <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> ioctl with
  41       <type>struct kdbus_cmd</type>. Custom endpoints always have a policy
  42       database that, by default, forbids any operation. You have to explicitly
  43       install policy entries to allow any operation on this endpoint.
  44     </para>
  45     <para>
  46       Once <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> succeeded, the new
  47       endpoint will appear in the filesystem
  48       (<citerefentry>
  49         <refentrytitle>kdbus.bus</refentrytitle>
  50         <manvolnum>7</manvolnum>
  51       </citerefentry>), and the used file descriptor will manage the
  52       newly created endpoint resource. It cannot be used to manage further
  53       resources and must be kept open as long as the endpoint is needed. The
  54       endpoint will be terminated as soon as the file descriptor is closed.
  55     </para>
  56     <para>
  57       Endpoint names may be chosen freely except for one restriction: the name
  58       must be prefixed with the numeric effective UID of the creator and a dash.
  59       This is required to avoid namespace clashes between different users. When
  60       creating an endpoint, the name that is passed in must be properly
  61       formatted or the kernel will refuse creation of the endpoint. Example:
  62       <literal>1047-my-endpoint</literal> is an acceptable name for an
  63       endpoint registered by a user with UID 1047. However,
  64       <literal>1024-my-endpoint</literal> is not, and neither is
  65       <literal>my-endpoint</literal>. The UID must be provided in the
  66       user-namespace of the bus.
  67     </para>
  68     <para>
  69       To create connections to a bus, use <constant>KDBUS_CMD_HELLO</constant>
  70       on a file descriptor returned by <function>open()</function> on an
  71       endpoint node. See
  72       <citerefentry>
  73         <refentrytitle>kdbus.connection</refentrytitle>
  74         <manvolnum>7</manvolnum>
  75       </citerefentry>
  76       for further details.
  77     </para>
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Creating custom endpoints</title>
  82     <para>
  83       To create a new endpoint, the
  84       <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> command is used. Along with
  85       the endpoint's name, which will be used to expose the endpoint in the
  86       <citerefentry>
  87         <refentrytitle>kdbus.fs</refentrytitle>
  88         <manvolnum>7</manvolnum>
  89       </citerefentry>,
  90       the command also optionally takes items to set up the endpoint's
  91       <citerefentry>
  92         <refentrytitle>kdbus.policy</refentrytitle>
  93         <manvolnum>7</manvolnum>
  94       </citerefentry>.
  95       <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> takes a
  96       <type>struct kdbus_cmd</type> argument.
  97     </para>
  98     <programlisting>
  99 struct kdbus_cmd {
 100   __u64 size;
 101   __u64 flags;
 102   __u64 return_flags;
 103   struct kdbus_item items[0];
 104 };
 105     </programlisting>
 106
 107     <para>The fields in this struct are described below.</para>
 108
 109     <variablelist>
 110       <varlistentry>
 111         <term><varname>size</varname></term>
 112         <listitem><para>
 113           The overall size of the struct, including its items.
 114         </para></listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><varname>flags</varname></term>
 119         <listitem><para>The flags for creation.</para>
 120           <variablelist>
 121             <varlistentry>
 122               <term><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
 123               <listitem>
 124                 <para>Make the endpoint file group-accessible.</para>
 125               </listitem>
 126             </varlistentry>
 127
 128             <varlistentry>
 129               <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
 130               <listitem>
 131                 <para>Make the endpoint file world-accessible.</para>
 132               </listitem>
 133             </varlistentry>
 134
 135             <varlistentry>
 136               <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
 137               <listitem>
 138                 <para>
 139                   Requests a set of valid flags for this ioctl. When this bit is
 140                   set, no action is taken; the ioctl will return
 141                   <errorcode>0</errorcode>, and the <varname>flags</varname>
 142                   field will have all bits set that are valid for this command.
 143                   The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
 144                   cleared by the operation.
 145                 </para>
 146               </listitem>
 147             </varlistentry>
 148           </variablelist>
 149         </listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><varname>return_flags</varname></term>
 154         <listitem><para>
 155           Flags returned by the kernel. Currently unused and always set to
 156           <constant>0</constant> by the kernel.
 157         </para></listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term><varname>items</varname></term>
 162         <listitem>
 163           <para>
 164             The following items are expected for
 165             <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>.
 166           </para>
 167           <variablelist>
 168             <varlistentry>
 169               <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
 170               <listitem>
 171                 <para>Contains a string to identify the endpoint name.</para>
 172               </listitem>
 173             </varlistentry>
 174
 175             <varlistentry>
 176               <term><constant>KDBUS_ITEM_NAME</constant></term>
 177               <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
 178               <listitem>
 179                 <para>
 180                   These items are used to set the policy attached to the
 181                   endpoint. For more details on bus and endpoint policies, see
 182                   <citerefentry>
 183                     <refentrytitle>kdbus.policy</refentrytitle>
 184                     <manvolnum>7</manvolnum>
 185                   </citerefentry>.
 186                 </para>
 187               </listitem>
 188             </varlistentry>
 189           </variablelist>
 190           <para>
 191             Unrecognized items are rejected, and the ioctl will fail with
 192             <varname>errno</varname> set to <varname>EINVAL</varname>.
 193           </para>
 194         </listitem>
 195       </varlistentry>
 196     </variablelist>
 197   </refsect1>
 198
 199   <refsect1>
 200     <title>Updating endpoints</title>
 201     <para>
 202       To update an existing endpoint, the
 203       <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> command is used on the file
 204       descriptor that was used to create the endpoint, using
 205       <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>. The only relevant detail of
 206       the endpoint that can be updated is the policy. When the command is
 207       employed, the policy of the endpoint is <emphasis>replaced</emphasis>
 208       atomically with the new set of rules.
 209       The command takes a <type>struct kdbus_cmd</type> argument.
 210     </para>
 211     <programlisting>
 212 struct kdbus_cmd {
 213   __u64 size;
 214   __u64 flags;
 215   __u64 return_flags;
 216   struct kdbus_item items[0];
 217 };
 218     </programlisting>
 219
 220     <para>The fields in this struct are described below.</para>
 221
 222     <variablelist>
 223       <varlistentry>
 224         <term><varname>size</varname></term>
 225         <listitem><para>
 226           The overall size of the struct, including its items.
 227         </para></listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term><varname>flags</varname></term>
 232         <listitem><para>
 233           Unused for this command.
 234           <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
 235           valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
 236           and the <varname>flags</varname> field is set to
 237           <constant>0</constant>.
 238         </para></listitem>
 239       </varlistentry>
 240
 241       <varlistentry>
 242         <term><varname>return_flags</varname></term>
 243         <listitem><para>
 244           Flags returned by the kernel. Currently unused and always set to
 245           <constant>0</constant> by the kernel.
 246         </para></listitem>
 247       </varlistentry>
 248
 249       <varlistentry>
 250         <term><varname>items</varname></term>
 251         <listitem>
 252           <para>
 253             The following items are expected for
 254             <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant>.
 255           </para>
 256           <variablelist>
 257             <varlistentry>
 258               <term><constant>KDBUS_ITEM_NAME</constant></term>
 259               <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
 260               <listitem>
 261                 <para>
 262                   These items are used to set the policy attached to the
 263                   endpoint. For more details on bus and endpoint policies, see
 264                   <citerefentry>
 265                     <refentrytitle>kdbus.policy</refentrytitle>
 266                     <manvolnum>7</manvolnum>
 267                   </citerefentry>.
 268                   Existing policy is atomically replaced with the new rules
 269                   provided.
 270                 </para>
 271               </listitem>
 272             </varlistentry>
 273
 274             <varlistentry>
 275               <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
 276               <listitem><para>
 277                 With this item, programs can <emphasis>probe</emphasis> the
 278                 kernel for known item types. See
 279                 <citerefentry>
 280                   <refentrytitle>kdbus.item</refentrytitle>
 281                   <manvolnum>7</manvolnum>
 282                 </citerefentry>
 283                 for more details.
 284               </para></listitem>
 285             </varlistentry>
 286           </variablelist>
 287           <para>
 288             Unrecognized items are rejected, and the ioctl will fail with
 289             <varname>errno</varname> set to <constant>EINVAL</constant>.
 290           </para>
 291         </listitem>
 292       </varlistentry>
 293     </variablelist>
 294   </refsect1>
 295
 296   <refsect1>
 297     <title>Return value</title>
 298     <para>
 299       On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
 300       on error, <errorcode>-1</errorcode> is returned, and
 301       <varname>errno</varname> is set to indicate the error.
 302       If the issued ioctl is illegal for the file descriptor used,
 303       <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
 304     </para>
 305
 306     <refsect2>
 307       <title>
 308         <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> may fail with the
 309         following errors
 310       </title>
 311
 312       <variablelist>
 313         <varlistentry>
 314           <term><constant>EINVAL</constant></term>
 315           <listitem><para>
 316             The flags supplied in the <type>struct kdbus_cmd</type>
 317             are invalid.
 318           </para></listitem>
 319         </varlistentry>
 320
 321         <varlistentry>
 322           <term><constant>EINVAL</constant></term>
 323           <listitem><para>
 324             Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and
 325             <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided.
 326           </para></listitem>
 327         </varlistentry>
 328
 329         <varlistentry>
 330           <term><constant>EEXIST</constant></term>
 331           <listitem><para>
 332             An endpoint of that name already exists.
 333           </para></listitem>
 334         </varlistentry>
 335
 336         <varlistentry>
 337           <term><constant>EPERM</constant></term>
 338           <listitem><para>
 339             The calling user is not privileged. See
 340             <citerefentry>
 341               <refentrytitle>kdbus</refentrytitle>
 342               <manvolnum>7</manvolnum>
 343             </citerefentry>
 344             for information about privileged users.
 345           </para></listitem>
 346         </varlistentry>
 347       </variablelist>
 348     </refsect2>
 349
 350     <refsect2>
 351       <title>
 352         <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> may fail with the
 353         following errors
 354       </title>
 355
 356       <variablelist>
 357         <varlistentry>
 358           <term><constant>EINVAL</constant></term>
 359           <listitem><para>
 360             The flags supplied in <type>struct kdbus_cmd</type>
 361             are invalid.
 362           </para></listitem>
 363         </varlistentry>
 364
 365         <varlistentry>
 366           <term><constant>EINVAL</constant></term>
 367           <listitem><para>
 368             Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and
 369             <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided.
 370           </para></listitem>
 371         </varlistentry>
 372       </variablelist>
 373     </refsect2>
 374   </refsect1>
 375
 376   <refsect1>
 377     <title>See Also</title>
 378     <simplelist type="inline">
 379       <member>
 380         <citerefentry>
 381           <refentrytitle>kdbus</refentrytitle>
 382           <manvolnum>7</manvolnum>
 383         </citerefentry>
 384       </member>
 385       <member>
 386         <citerefentry>
 387           <refentrytitle>kdbus.bus</refentrytitle>
 388           <manvolnum>7</manvolnum>
 389         </citerefentry>
 390       </member>
 391       <member>
 392         <citerefentry>
 393           <refentrytitle>kdbus.endpoint</refentrytitle>
 394           <manvolnum>7</manvolnum>
 395         </citerefentry>
 396       </member>
 397       <member>
 398         <citerefentry>
 399           <refentrytitle>kdbus.fs</refentrytitle>
 400           <manvolnum>7</manvolnum>
 401         </citerefentry>
 402       </member>
 403       <member>
 404         <citerefentry>
 405           <refentrytitle>kdbus.item</refentrytitle>
 406           <manvolnum>7</manvolnum>
 407         </citerefentry>
 408       </member>
 409       <member>
 410         <citerefentry>
 411           <refentrytitle>kdbus.message</refentrytitle>
 412           <manvolnum>7</manvolnum>
 413         </citerefentry>
 414       </member>
 415       <member>
 416         <citerefentry>
 417           <refentrytitle>kdbus.name</refentrytitle>
 418           <manvolnum>7</manvolnum>
 419         </citerefentry>
 420       </member>
 421       <member>
 422         <citerefentry>
 423           <refentrytitle>kdbus.pool</refentrytitle>
 424            <manvolnum>7</manvolnum>
 425         </citerefentry>
 426       </member>
 427     </simplelist>
 428   </refsect1>
 429 </refentry>