# sd_bus_message_append_array

## NAME



           sd_bus_message_append_array, sd_bus_message_append_array_memfd,
           sd_bus_message_append_array_iovec,
           sd_bus_message_append_array_space - Append an array of fields to a
           D-Bus message
    


## SYNOPSIS



           **#include <systemd/sd-bus.h>**
    
           **int sd_bus_message_append_array(sd_bus_message ***_m_**, char** _type_**,**
                                           **const void ***_ptr_**, size_t** _size_**);**
    
           **int sd_bus_message_append_array_memfd(sd_bus_message ***_m_**,**
                                                 **char** _type_**, int** _memfd_**,**
                                                 **uint64_t** _offset_**,**
                                                 **uint64_t** _size_**);**
    
           **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(sd_bus_message ***_m_**,**
                                                 **char** _type_**, size_t** _size_**,**
                                                 **void ****_ptr_**);**
    


## DESCRIPTION



           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 D-Bus Types******[1] section of the D-Bus
           specification, and listed insd_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 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_create(2) 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 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 return 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



           Functions described here are available as a shared library, which
           can be compiled against and linked to with the
           **libsystemd pkg-config**(1) file.
    
           The code described here uses getenv(3), which is declared to be
           not multi-thread-safe. This means that the code calling the
           functions described here must not call setenv(3) from a parallel
           thread. It is recommended to only do calls to **setenv()** from an
           early phase of the program when no other threads have been
           started.
    


## NOTES



            1. Basic D-Bus Types
               https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types
    
            2. The D-Bus specification
               https://dbus.freedesktop.org/doc/dbus-specification.html
    


* * *