SD_BUS_MESSAGE_APPEND_ARRAY(3)

NAME
sd_bus_message_append_array, sd_bus_message_append_array_memfd, sd_bus_message_append_array_iovec, sd_bus_message_append_array_space - Attach an array of items to a message

SYNOPSIS

#include <systemd/sd-bus.h>

int sd_bus_message_append_array(sd_bus_message *m, char type, char void *ptr, size_t size);

int sd_bus_message_append_array_memfd(sd_bus_message *m, char type, int memfd);

int sd_bus_message_append_array_iovec(sd_bus_message *m, char type, const struct iovec *iov, unsigned n);

int sd_bus_message_append_array_space(char type, size_t size, char void **ptr);

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. 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[1] section of the D-Bus specification, and listed in sd_bus_message_append_basic(3). Pointer p must point to an array of size size bytes containing items of the respective type. Size size must be a 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 nstruct 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 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.

RETURN VALUE

On success, these calls return 0 or a positive integer. On failure, they returns a negative errno-style error code.

ERRORS

Returned errors may indicate the following problems:

-EINVAL
    Specified parameter is invalid.

-EPERM
    Message has been sealed.

-ESTALE
    Message is in invalid state.

-ENXIO
    Message cannot be appended to.

-ENOMEM
    Memory allocation failed.

NOTES

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-config(1) file.

SEE ALSO

systemd(1), sd-bus(3), sd_bus_message_append(3), sd_bus_message_append_basic(3), The D-Bus specification[2]

NOTES

1.  Basic Types
    http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types

2.  The D-Bus specification
    http://dbus.freedesktop.org/doc/dbus-specification.html