sd_bus_message_append_basic

Index · Directives · Python · libudev · gudev systemd 215

## Name

sd_bus_message_append_basic — Attach a single part to a message

## Synopsis

    #include <systemd/sd-bus.h>

`int sd_bus_message_append_basic(` | sd_bus_message *m,
| char type,
| char void *p`)`;

## Description

`sd_bus_message_append_basic` appends a single item to the message `m`. Parameter `type` determines how pointer `p` is interpreted. `type` must be one of the basic types as defined by the Basic Types section of the D-Bus specification, and listed in the table below.

Table 1. Item format specifiers

Specifier | Constant | Description | Size
--- | --- | --- | ---
"`y`" | `SD_BUS_TYPE_BYTE` | unsigned interger | 1 byte
"`b`" | `SD_BUS_TYPE_BOOLEAN` | boolean | 4 bytes
"`n`" | `SD_BUS_TYPE_INT16` | signed integer | 2 bytes
"`q`" | `SD_BUS_TYPE_UINT16` | unsigned integer | 2 bytes
"`i`" | `SD_BUS_TYPE_INT32` | signed integer | 4 bytes
"`u`" | `SD_BUS_TYPE_UINT32` | unsigned integer | 4 bytes
"`x`" | `SD_BUS_TYPE_INT64` | signed integer | 8 bytes
"`t`" | `SD_BUS_TYPE_UINT64` | unsigned integer | 8 bytes
"`d`" | `SD_BUS_TYPE_DOUBLE` | floating-point | 8 bytes
"`s`" | `SD_BUS_TYPE_STRING` | Unicode string | variable
"`o`" | `SD_BUS_TYPE_OBJECT_PATH` | object path | variable
"`g`" | `SD_BUS_TYPE_SIGNATURE` | signature | variable
"`h`" | `SD_BUS_TYPE_UNIX_FD` | UNIX file descriptor | 4 bytes

The value of the parameter is copied into the memory area containing the message and may be changed after this call. If `type` is "`h`" (UNIX file descriptor), it is always "consumed" by this call, and either successfully appended to the message or closed.

For types "`s`", "`o`", and "`g`", the parameter `p` is interpreted as a pointer to a `NUL`-terminated character sequence. As a special case, a `NULL` pointer is interpreted as an empty string. The string should be valid Unicode string encoded as UTF-8. In case of the two latter types, the additional requirements for a D-Bus object path or type signature should be satisfied. Those requirements should be verified by the recepient of the message.

## Return Value

On success, this call returns 0 or a positive integer. On failure, it 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

The `sd_bus_append_basic()` function described here is 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), The D-Bus specification