X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=src%2Flibsystemd-bus%2Fkdbus.h;h=13fe49a2b96e5d48c99b517b2425c8e85fd4b05e;hp=d7ea6491f58aa1b3235c8fb66832d12752411318;hb=ff6c70f18bacad842b88bf2bfb86d6e9841c1a16;hpb=e63bb33d71a524e84206ef94ade3eba441e186c5

diff --git a/src/libsystemd-bus/kdbus.h b/src/libsystemd-bus/kdbus.h
index d7ea6491f..13fe49a2b 100644
--- a/src/libsystemd-bus/kdbus.h
+++ b/src/libsystemd-bus/kdbus.h
@@ -26,39 +26,77 @@
 #define KDBUS_MATCH_SRC_ID_ANY		(~0ULL)
 #define KDBUS_DST_ID_BROADCAST		(~0ULL)
 
-/* Common first elements in a structure which are used to iterate over
- * a list of elements. */
+/**
+ * struct KDBUS_PART_HEADER - anonymous struct used as header
+ * @size:		Size of element, excluding padding bytes
+ * @type		Type of element
+ *
+ * Common first elements in a structure, used to specify the type
+ * and size of the data.
+ * */
 #define KDBUS_PART_HEADER \
 	struct {							\
 		__u64 size;						\
 		__u64 type;						\
 	}
 
-/* Message sent from kernel to userspace, when the owner or starter of
- * a well-known name changes */
+/**
+ * struct kdbus_notify_name_change - name registry change message
+ * @old_id		Former owner of a name
+ * @new_id		New owner of a name
+ * @flags		flags from KDBUS_NAME_*
+ * @name		Well-known name
+ *
+ * Data attached to:
+ *   KDBUS_ITEM_NAME_ADD
+ *   KDBUS_ITEM_NAME_REMOVE
+ *   KDBUS_ITEM_NAME_CHANGE
+ *
+ * Sent from kernel to userspace when the owner or starter of
+ * a well-known name changes.
+ */
 struct kdbus_notify_name_change {
 	__u64 old_id;
 	__u64 new_id;
-	__u64 flags;			/* 0 or (possibly?) KDBUS_NAME_IN_QUEUE */
+	__u64 flags;
 	char name[0];
 };
 
+/**
+ * struct kdbus_notify_id_change - name registry change message
+ * @id			New or former owner of the name
+ * @flags		flags field from KDBUS_HELLO_*
+ *
+ * Data attached to:
+ *   KDBUS_ITEM_ID_ADD
+ *   KDBUS_ITEM_ID_REMOVE
+ *
+ * Sent from kernel to userspace when the owner or starter of
+ * a well-known name changes.
+ */
 struct kdbus_notify_id_change {
 	__u64 id;
-	__u64 flags;			/* The kernel flags field from KDBUS_HELLO */
+	__u64 flags;
 };
 
+/**
+ * struct kdbus_creds - process credentials
+ * @uid			User ID
+ * @gid			Group ID
+ * @pid			Process ID
+ * @tid			Thread ID
+ * @starttime		Starttime of the process
+ *
+ * The starttime of the process PID. This is useful to detect PID overruns
+ * from the client side. i.e. if you use the PID to look something up in
+ * /proc/$PID/ you can afterwards check the starttime field of it, to ensure
+ * you didn't run into a PID overrun.
+ */
 struct kdbus_creds {
 	__u64 uid;
 	__u64 gid;
 	__u64 pid;
 	__u64 tid;
-
-	/* The starttime of the process PID. This is useful to detect
-	PID overruns from the client side. i.e. if you use the PID to
-	look something up in /proc/$PID/ you can afterwards check the
-	starttime field of it to ensure you didn't run into a PID
-	ovretun. */
 	__u64 starttime;
 };
 
@@ -108,6 +146,16 @@ struct kdbus_memfd {
 	__u32 __pad;
 };
 
+/**
+ * struct kdbus_name - a registered well-known name with its flags
+ * @flags		flags from KDBUS_NAME_*
+ * @name		well-known name
+ */
+struct kdbus_name {
+	__u64 flags;
+	char name[0];
+};
+
 /* Message Item Types */
 enum {
 	_KDBUS_ITEM_NULL,
@@ -124,7 +172,7 @@ enum {
 
 	/* Filled in by kernelspace */
 	_KDBUS_ITEM_ATTACH_BASE	= 0x400,
-	KDBUS_ITEM_NAMES	= 0x400,/* NUL separated string list with well-known names of source */
+	KDBUS_ITEM_NAME		= 0x400,/* NUL separated string list with well-known names of source */
 	KDBUS_ITEM_STARTER_NAME,	/* Only used in HELLO for starter connection */
 	KDBUS_ITEM_TIMESTAMP,		/* .timestamp */
 
@@ -174,6 +222,7 @@ struct kdbus_item {
 		struct kdbus_creds creds;
 		struct kdbus_audit audit;
 		struct kdbus_timestamp timestamp;
+		struct kdbus_name name;
 
 		/* specific fields */
 		struct kdbus_memfd memfd;
@@ -316,7 +365,7 @@ enum {
  * 			KDBUS_CMD_BUS_MAKE ioctl. It's intended to be useful
  *			to do negotiation of features of the payload that is
  *			transferred (kernel → userspace)
- * @id:			The id of this connection (kernel → userspace)
+ * @id:			The ID of this connection (kernel → userspace)
  * @bloom_size:		The bloom filter size chosen by the owner
  * 			(kernel → userspace)
  * @pool_size:		Maximum size of the pool buffer (kernel → userspace)
@@ -354,18 +403,12 @@ enum {
 enum {
 	_KDBUS_MAKE_NULL,
 	KDBUS_MAKE_NAME,
-	KDBUS_MAKE_CRED,/* allow translator services which connect
-			 * to the bus on behalf of somebody else,
-			 * allow specifying the credentials of the
-			 * client to connect on behalf on. Needs
-			 * privileges */
 };
 
 /**
  * struct kdbus_cmd_bus_make - struct to make a bus
  * @size:		The total size of the struct
- * @flags:		FIXME
- * @bus_flags:
+ * @flags:		Properties for the bus to create
  * @bloom_filter:	Size of the bloom filter for this bus
  * @items:		Items describing details such as the name of the bus
  *
@@ -375,7 +418,6 @@ enum {
 struct kdbus_cmd_bus_make {
 	__u64 size;
 	__u64 flags;
-	__u64 bus_flags;
 	__u64 bloom_size;
 	struct kdbus_item items[0];
 };
@@ -479,7 +521,7 @@ struct kdbus_name_list {
 /**
  * struct kdbus_cmd_conn_info - struct used for KDBUS_CMD_CONN_INFO ioctl
  * @size:		The total size of the struct
- * @flags:		Query flags, currently unused
+ * @flags:		KDBUS_ATTACH_* flags
  * @id:			The 64-bit ID of the connection. If set to zero, passing
  * 			@name is required. kdbus will look up the name to determine
  * 			the ID in this case.
@@ -487,7 +529,7 @@ struct kdbus_name_list {
  * 			kdbus_name_info struct result is stored. The user must
  * 			use KDBUS_CMD_FREE to free the allocated memory.
  * @name:		The optional well-known name to look up. Only needed in
- * 			case @if is zero.
+ * 			case @id is zero.
  *
  * On success, the KDBUS_CMD_CONN_INFO ioctl will return 0 and @offset will
  * tell the user the offset in the connection pool buffer at which to find the
@@ -521,10 +563,10 @@ struct kdbus_conn_info {
 enum {
 	_KDBUS_MATCH_NULL,
 	KDBUS_MATCH_BLOOM,		/* Matches a mask blob against KDBUS_MSG_BLOOM */
-	KDBUS_MATCH_SRC_NAME,		/* Matches a name string against KDBUS_MSG_SRC_NAMES */
-	KDBUS_MATCH_NAME_ADD,		/* Matches a name string against KDBUS_MSG_NAME_ADD */
-	KDBUS_MATCH_NAME_REMOVE,	/* Matches a name string against KDBUS_MSG_NAME_REMOVE */
-	KDBUS_MATCH_NAME_CHANGE,	/* Matches a name string against KDBUS_MSG_NAME_CHANGE */
+	KDBUS_MATCH_SRC_NAME,		/* Matches a name string against KDBUS_ITEM_NAME */
+	KDBUS_MATCH_NAME_ADD,		/* Matches a name string against KDBUS_ITEM_NAME_ADD */
+	KDBUS_MATCH_NAME_REMOVE,	/* Matches a name string against KDBUS_ITEM_NAME_REMOVE */
+	KDBUS_MATCH_NAME_CHANGE,	/* Matches a name string against KDBUS_ITEM_NAME_CHANGE */
 	KDBUS_MATCH_ID_ADD,		/* Matches an ID against KDBUS_MSG_ID_ADD */
 	KDBUS_MATCH_ID_REMOVE,		/* Matches an ID against KDBUS_MSG_ID_REMOVE */
 };