diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml
index 5faadd603a..7f9235954f 100644
--- a/man/sd_bus_message_append.xml
+++ b/man/sd_bus_message_append.xml
@@ -146,8 +146,10 @@
- For types "s" and "g" (unicode string or signature), the pointer may be
- NULL, which is equivalent to an empty string. See
+ For types s and g (unicode string or signature), the pointer
+ may be NULL, which is equivalent to an empty string. For h (UNIX
+ file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession
+ of the caller. See
sd_bus_message_append_basic3
for the precise interpretation of those and other types.
diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml
index 1b9f36cd84..2b5f1000be 100644
--- a/man/sd_bus_message_read.xml
+++ b/man/sd_bus_message_read.xml
@@ -73,7 +73,10 @@
should be read. See the table below for a complete list of allowed arguments and their types. Note that,
if the basic type is a pointer (e.g., const char * in the case of a string), the argument is
a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must
- be copied if they are to be used after the end of the messages lifetime.
+ be copied if they are to be used after the end of the messages lifetime. If the type is
+ h (UNIX file descriptor), the descriptor is not duplicated by this call and the
+ returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
+ in order to keep an open reference to it after the message object is freed.
Each argument may also be NULL, in which case the value is read and ignored.
@@ -228,6 +231,15 @@ const char *s, *t, *u;
sd_bus_message_read(m, "a{is}", 3, &i, &s, &j, &t, &k, &u);
+
+ Read a single file descriptor, and duplicate it in order to keep it open after the message is
+ freed.
+
+ sd_bus_message *m;
+int fd, fd_copy;
+
+sd_bus_message_read(m, "h", &fd);
+fd_copy = fcntl(fd, FD_DUPFD_CLOEXEC, 3);
diff --git a/man/sd_bus_message_read_basic.xml b/man/sd_bus_message_read_basic.xml
index e1e993434a..dc9f960618 100644
--- a/man/sd_bus_message_read_basic.xml
+++ b/man/sd_bus_message_read_basic.xml
@@ -52,17 +52,19 @@
- If p is not NULL, it should contain
- a pointer to an appropriate object. For example, if type
- is 'y', the object passed in p
- should have type uint8_t *. If type is
- 's', the object passed in p should
- have type const char **. Note that, if the basic type is a pointer
- (e.g., const char * in the case of a string), the pointer is only
- borrowed and the contents must be copied if they are to be used after the end
- of the messages lifetime. Similarly, during the lifetime of such a pointer, the
- message must not be modified. See the table below for a complete list of allowed
- types.
+ If p is not NULL, it should contain a pointer to an
+ appropriate object. For example, if type is 'y', the object
+ passed in p should have type uint8_t *. If
+ type is 's', the object passed in p
+ should have type const char **. Note that, if the basic type is a pointer (e.g.,
+ const char * in the case of a string), the pointer is only borrowed and the contents must
+ be copied if they are to be used after the end of the messages lifetime. Similarly, during the lifetime
+ of such a pointer, the message must not be modified. If type is
+ 'h' (UNIX file descriptor), the descriptor is not duplicated by this call and the
+ returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
+ in order to keep an open reference to it after the message object is freed (for example by calling
+ fcntl(fd, FD_DUPFD_CLOEXEC, 3)). See the table below for a complete list of
+ allowed types.