From e8216945a97bc2a2b04bc286e67ab5bba313b83e Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 7 Jul 2015 20:35:45 +0200 Subject: man: update and extend the various sd_bus_message_append_*() man pages Some calls changed their signature since the man pages were written. Also extend on a number of details. --- man/sd_bus_message_append_array.xml | 123 +++++++++++++++++++++--------------- 1 file changed, 73 insertions(+), 50 deletions(-) (limited to 'man/sd_bus_message_append_array.xml') diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml index c2adc6f43d..034466bf9c 100644 --- a/man/sd_bus_message_append_array.xml +++ b/man/sd_bus_message_append_array.xml @@ -49,7 +49,8 @@ sd_bus_message_append_array_iovec sd_bus_message_append_array_space - Attach an array of items to a message + Appaned an array of fields to a D-Bus + message @@ -69,6 +70,8 @@ sd_bus_message *m char type int memfd + uint64_t offset + uint64_t size @@ -83,7 +86,7 @@ int sd_bus_message_append_array_space char type size_t size - char void **ptr + void **ptr @@ -91,18 +94,19 @@ Description - The sd_bus_message_append_array functionc - appends items to message m as the single - array. A container will be opened, items appended, and the - container closed. Parameter type determines - how pointer p is interpreted. + The sd_bus_message_append_array() + function appends an array to a D-Bus message + m. A container will be opened, the array + contents appended, and the container closed. The parameter + type determines how the pointer + p is interpreted. type must be one of the "trivial" types y, n, q, i, u, x, t, d (but not - b), as defined by the - Basic Types - section of the D-Bus specification, and listed in + b), as defined by the Basic + Types section of the D-Bus specification, and listed in sd_bus_message_append_basic3. Pointer p must point to an array of size size bytes containing items of the @@ -110,50 +114,68 @@ multiple of the size of the type type. As a special case, p may be NULL, if size is 0. - - - The memory pointed at by p is copied - into the memory area containing the message and may be changed - after this call. - - The - sd_bus_message_append_array_memfd function appends - items to message m, similarly to - sd_bus_message_append_array. Contents of the - memory file descriptor memfd are used as - the contents of the array. Their size must be a multiple of the - size of the type type. - - The descriptor specified with memfd - will be sealed and cannot be modified after this call. - - The - sd_bus_message_append_array_iovec function appends - items to message m, similarly to - sd_bus_message_append_array. Contents of the - iovec iov are used as the contents of the - array. The total size of iov payload (the - sum of iov_len fields) must be a multiple - of the size of the type type. - - The iov argument must point to - n struct iovec - structures. Each structure may have the - iov_base field set, in which case the - memory pointed to will be copied into the message, or unset, in - which case a block of zeros of length + The memory pointed to by p is copied into + the memory area containing the message and stays in possession of + the caller. The caller may hence freely change the data after this + call without affecting the message the array was appended + to. + + The sd_bus_message_append_array_memfd() + function appends an array of a trivial type to message + m, similar to + sd_bus_message_append_array(). The contents + of the memory file descriptor memfd + starting at the specified offset and and of the specified size is + used as the contents of the array. The offset and size must be a + multiple of the size of the type + type. However, as a special exception, if + the offset is specified as zero and the size specified as + UINT64_MAX the full memory file descriptor contents is used. The + memory file descriptor is sealed by this call if it hasn't been + sealed yet, and cannot be modified a after this call. See + memfd_create2 + for details about memory file descriptors. Appending arrays with + memory file descriptors enables efficient zero-copy data transfer, + as the memory file descriptor may be passed as-is to the + destination, without copying the memory in it to the destination + process. Not all protocol transports support passing memory file + descriptors between participants, in which case this call will + automatically fall back to copying. Also, as memory file + descriptor passing is inefficient for smaller amounts of data + copying might still be enforced even where memory file descriptor + passing is supported. + + The sd_bus_message_append_array_iovec() + function appends an array of a trivial type to the message + m, similar to + sd_bus_message_append_array(). Contents of + the IO vector array iov are used as the + contents of the array. The total size of + iov payload (the sum of + iov_len fields) must be a multiple of + the size of the type type. The + iov argument must point to + n IO vector structures. Each structure may + have the iov_base field set, in which + case the memory pointed to will be copied into the message, or + unset (set to zero), in which case a block of zeros of length iov_len bytes will be inserted. The memory pointed at by iov may be changed after this call. - The - sd_bus_message_append_array_space function appends - space for an array of items to message m. - It behaves the same as - sd_bus_message_append_array, but instead - of copying items to the message, it returns a pointer to the - destination area to the caller in pointer p. - + The sd_bus_message_append_array_space() + function appends space for an array of a trivial type to message + m. It behaves the same as + sd_bus_message_append_array(), but instead of + copying items to the message, it returns a pointer to the + destination area to the caller in pointer + p. The caller should subsequently write the + array contents to this memory. Modifications of the memory + pointed to should only occur until the next operation on the bus + message is invoked, most imporantly the memory should not be + altered anymore when another field has been added to the message + or the message has been sealed. @@ -183,6 +205,7 @@ sd-bus3, sd_bus_message_append3, sd_bus_message_append_basic3, + memfd_create2, The D-Bus specification -- cgit v1.2.3-54-g00ecf