X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_bus_message_append_array.xml;h=70f1f78896d445ded977622c06723a2243713254;hb=91d60274701a12d2bbcd2b8e40f8b8abe00be0e7;hp=ab1fcd26cbab502d41a3442bd13a26f67f94e656;hpb=630a4d9ea7298fb4a494662cbb4871069143ff56;p=elogind.git diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml index ab1fcd26c..70f1f7889 100644 --- a/man/sd_bus_message_append_array.xml +++ b/man/sd_bus_message_append_array.xml @@ -1,27 +1,27 @@ - + - @@ -49,7 +49,8 @@ along with systemd; If not, see . sd_bus_message_append_array_iovec sd_bus_message_append_array_space - Attach an array of items to a message + Append an array of fields to a D-Bus + message @@ -69,6 +70,8 @@ along with systemd; If not, see . sd_bus_message *m char type int memfd + uint64_t offset + uint64_t size @@ -83,7 +86,7 @@ along with systemd; If not, see . int sd_bus_message_append_array_space char type size_t size - char void **ptr + void **ptr @@ -91,18 +94,19 @@ along with systemd; If not, see . 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,57 +114,75 @@ along with systemd; If not, see . 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 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 has not been + sealed yet, and cannot be modified 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 I/O 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 I/O 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 to the memory + pointed to should only occur until the next operation on the bus + message is invoked. Most importantly, the memory should not be + altered anymore when another field has been added to the message + or the message has been sealed. Return Value On success, these calls return 0 or a positive integer. On - failure, they returns a negative errno-style error code. + failure, they return a negative errno-style error code. @@ -171,7 +193,7 @@ along with systemd; If not, see . sd_bus_append_array() and other functions described here are available as a shared library, which can be compiled and linked to with the - libsystemd pkg-config1 + libelogind pkg-config1 file. @@ -183,6 +205,7 @@ along with systemd; If not, see . sd-bus3, sd_bus_message_append3, sd_bus_message_append_basic3, + memfd_create2, The D-Bus specification