sd_bus_message_append_array

Index · Directives · Python · libudev · gudev systemd 215

## 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,
| sd_memfd *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 section of the D-Bus specification, and listed in sd_bus_message_append_basic(3). Pointer `p` must point to an array of 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 `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 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