From e2b40db616b4e723036f72a726e2f2f31d35ffe1 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 28 Aug 2020 21:18:14 +0200 Subject: [PATCH] man: document fd ownership for sd-bus fd marshalling Fixes: #8003 --- man/sd_bus_message_append.xml | 6 ++++-- man/sd_bus_message_read.xml | 14 +++++++++++++- man/sd_bus_message_read_basic.xml | 24 +++++++++++++----------- 3 files changed, 30 insertions(+), 14 deletions(-) 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.