kdbus.name kdbus.name 7 kdbus.name kdbus.name Each kdbus.bus 7 instantiates a name registry to resolve well-known names into unique connection IDs for message delivery. The registry will be queried when a message is sent with kdbus_msg.dst_id set to KDBUS_DST_ID_NAME, or when a registry dump is requested with KDBUS_CMD_NAME_LIST. All of the below is subject to policy rules for SEE and OWN permissions. See kdbus.policy 7 for more information. A name has to comply with the following rules in order to be considered valid. The name has two or more elements separated by a '.' (period) character. All elements must contain at least one character. Each element must only contain the ASCII characters [A-Z][a-z][0-9]_ and must not begin with a digit. The name must contain at least one '.' (period) character (and thus at least two elements). The name must not begin with a '.' (period) character. The name must not exceed 255 characters in length. To acquire a name, a client uses the KDBUS_CMD_NAME_ACQUIRE ioctl with struct kdbus_cmd as argument. struct kdbus_cmd { __u64 size; __u64 flags; __u64 return_flags; struct kdbus_item items[0]; }; The fields in this struct are described below. size The overall size of the struct, including its items. flags Flags to control details in the name acquisition. KDBUS_NAME_REPLACE_EXISTING Acquiring a name that is already present usually fails, unless this flag is set in the call, and KDBUS_NAME_ALLOW_REPLACEMENT (see below) was set when the current owner of the name acquired it, or if the current owner is an activator connection (see kdbus.connection 7 ). KDBUS_NAME_ALLOW_REPLACEMENT Allow other connections to take over this name. When this happens, the former owner of the connection will be notified of the name loss. KDBUS_NAME_QUEUE A name that is already acquired by a connection can not be acquired again (unless the KDBUS_NAME_ALLOW_REPLACEMENT flag was set during acquisition; see above). However, a connection can put itself in a queue of connections waiting for the name to be released. Once that happens, the first connection in that queue becomes the new owner and is notified accordingly. KDBUS_FLAG_NEGOTIATE Request a set of valid flags for this ioctl. When this bit is set, no action is taken; the ioctl will fail with -1, and errno is set to EPROTO. Once the ioctl returned, the flags field will have all bits set that the kernel recognizes as valid for this command. The KDBUS_FLAG_NEGOTIATE bit will be cleared by the operation. return_flags Flags returned by the kernel. Currently, the following may be returned by the kernel. KDBUS_NAME_IN_QUEUE The name was not acquired yet, but the connection was placed in the queue of peers waiting for the name. This can only happen if KDBUS_NAME_QUEUE was set in the flags member (see above). The connection will receive a name owner change notification once the current owner has given up the name and its ownership was transferred. items Items to submit the name. Currently, one item of type KDBUS_ITEM_NAME is expected and allowed, and the contained string must be a valid bus name. KDBUS_ITEM_NEGOTIATE may be used to probe for valid item types. See kdbus.item 7 for a detailed description of how this item is used. Unrecognized items are rejected, and the ioctl will fail with errno set to >EINVAL. A connection may release a name explicitly with the KDBUS_CMD_NAME_RELEASE ioctl. If the connection was an implementer of an activatable name, its pending messages are moved back to the activator. If there are any connections queued up as waiters for the name, the first one in the queue (the oldest entry) will become the new owner. The same happens implicitly for all names once a connection terminates. See kdbus.connection 7 for more information on connections. The KDBUS_CMD_NAME_RELEASE ioctl uses the same data structure as the acquisition call (KDBUS_CMD_NAME_ACQUIRE), but with slightly different field usage. struct kdbus_cmd { __u64 size; __u64 flags; __u64 return_flags; struct kdbus_item items[0]; }; The fields in this struct are described below. size The overall size of the struct, including its items. flags Flags to the command. Currently unused. KDBUS_FLAG_NEGOTIATE is accepted to probe for valid flags. If set, the ioctl will return 0, and the flags field is set to 0. return_flags Flags returned by the kernel. Currently unused and always set to 0 by the kernel. items Items to submit the name. Currently, one item of type KDBUS_ITEM_NAME is expected and allowed, and the contained string must be a valid bus name. KDBUS_ITEM_NEGOTIATE may be used to probe for valid item types. See kdbus.item 7 for a detailed description of how this item is used. Unrecognized items are rejected, and the ioctl will fail with errno set to EINVAL. A connection may request a complete or filtered dump of currently active bus names with the KDBUS_CMD_LIST ioctl, which takes a struct kdbus_cmd_list as argument. struct kdbus_cmd_list { __u64 flags; __u64 return_flags; __u64 offset; }; The fields in this struct are described below. flags Any combination of flags to specify which names should be dumped. KDBUS_LIST_UNIQUE List the unique (numeric) IDs of the connection, whether it owns a name or not. KDBUS_LIST_NAMES List well-known names stored in the database which are actively owned by a real connection (not an activator). KDBUS_LIST_ACTIVATORS List names that are owned by an activator. KDBUS_LIST_QUEUED List connections that are not yet owning a name but are waiting for it to become available. KDBUS_FLAG_NEGOTIATE Request a set of valid flags for this ioctl. When this bit is set, no action is taken; the ioctl will fail with -1, and errno is set to EPROTO. Once the ioctl returned, the flags field will have all bits set that the kernel recognizes as valid for this command. The KDBUS_FLAG_NEGOTIATE bit will be cleared by the operation. return_flags Flags returned by the kernel. Currently unused and always set to 0 by the kernel. offset When the ioctl returns successfully, the offset to the name registry dump inside the connection's pool will be stored in this field. The returned list of names is stored in a struct kdbus_list that in turn contains an array of type struct kdbus_info, The array-size in bytes is given as list_size. The fields inside struct kdbus_info is described next. struct kdbus_info { __u64 size; __u64 id; __u64 flags; struct kdbus_item items[0]; }; The fields in this struct are described below. size The overall size of the struct, including its items. id The owning connection's unique ID. flags The flags of the owning connection. items Items containing the actual name. Currently, one item of type KDBUS_ITEM_OWNED_NAME will be attached, including the name's flags. In that item, the flags field of the name may carry the following bits: KDBUS_NAME_ALLOW_REPLACEMENT Other connections are allowed to take over this name from the connection that owns it. KDBUS_NAME_IN_QUEUE When retrieving a list of currently acquired names in the registry, this flag indicates whether the connection actually owns the name or is currently waiting for it to become available. KDBUS_NAME_ACTIVATOR An activator connection owns a name as a placeholder for an implementer, which is started on demand by programs as soon as the first message arrives. There's some more information on this topic in kdbus.connection 7 . In contrast to KDBUS_NAME_REPLACE_EXISTING, when a name is taken over from an activator connection, all the messages that have been queued in the activator connection will be moved over to the new owner. The activator connection will still be tracked for the name and will take control again if the implementer connection terminates. This flag can not be used when acquiring a name, but is implicitly set through KDBUS_CMD_HELLO with KDBUS_HELLO_ACTIVATOR set in kdbus_cmd_hello.conn_flags. KDBUS_FLAG_NEGOTIATE Requests a set of valid flags for this ioctl. When this bit is set, no action is taken; the ioctl will return 0, and the flags field will have all bits set that are valid for this command. The KDBUS_FLAG_NEGOTIATE bit will be cleared by the operation. The returned buffer must be freed with the KDBUS_CMD_FREE ioctl when the user is finished with it. See kdbus.pool 7 for more information. On success, all mentioned ioctl commands return 0; on error, -1 is returned, and errno is set to indicate the error. If the issued ioctl is illegal for the file descriptor used, errno will be set to ENOTTY. EINVAL Illegal command flags, illegal name provided, or an activator tried to acquire a second name. EPERM Policy prohibited name ownership. EALREADY Connection already owns that name. EEXIST The name already exists and can not be taken over. E2BIG The maximum number of well-known names per connection is exhausted. EINVAL Invalid command flags, or invalid name provided. ESRCH Name is not found in the registry. EADDRINUSE Name is owned by a different connection and can't be released. EINVAL Invalid command flags ENOBUFS No available memory in the connection's pool. kdbus 7 kdbus.bus 7 kdbus.connection 7 kdbus.item 7 kdbus.policy 7 kdbus.pool 7