---
name: "SD_BUS_MESSAGE_METHOD_CALL"
section: "3"
platform: "linux"
package: "libsystemd-dev"
version: "257.13-1~deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/sd_bus_message_new"
---

# SD\_BUS\_MESSAGE\_METHOD\_CALL(3)

Create a new bus message object and create or destroy references to it

Part of [sd\_bus\_message\_new(3)](/sd_bus_message_new/3.md).

## NAME

sd\_bus\_message\_new, sd\_bus\_message\_ref, sd\_bus\_message\_unref, sd\_bus\_message\_unrefp, SD\_BUS\_MESSAGE\_METHOD\_CALL, SD\_BUS\_MESSAGE\_METHOD\_RETURN, SD\_BUS\_MESSAGE\_METHOD\_ERROR, SD\_BUS\_MESSAGE\_SIGNAL, sd\_bus\_message\_get\_bus - Create a new bus message object and create or destroy references to it

## SYNOPSIS

```
#include <systemd/sd-bus.h>
```

```
enum {
      SD_BUS_MESSAGE_METHOD_CALL,
      SD_BUS_MESSAGE_METHOD_RETURN,
      SD_BUS_MESSAGE_METHOD_ERROR,
      SD_BUS_MESSAGE_SIGNAL,
};
```

**int sd\_bus\_message\_new(sd\_bus \****bus***, sd\_bus\_message \*\****m***, uint8\_t** *type***);**

**sd\_bus\_message \*sd\_bus\_message\_ref(sd\_bus\_message \****m***);**

**sd\_bus\_message \*sd\_bus\_message\_unref(sd\_bus\_message \****m***);**

**void sd\_bus\_message\_unrefp(sd\_bus\_message \*\****mp***);**

**sd\_bus \*sd\_bus\_message\_get\_bus(sd\_bus\_message \****m***);**

## DESCRIPTION

**sd\_bus\_message\_new()** creates a new bus message object attached to the bus *bus* and returns it in the output parameter *m*. This object is reference-counted, and will be destroyed when all references are gone. Initially, the caller of this function owns the sole reference to the message object. Note that the message object holds a reference to the bus object, so the bus object will not be destroyed as long as the message exists.

Note: this is a low-level call. In most cases functions like [**sd\_bus\_message\_new\_method\_call**(3)](/sd_bus_message_new_method_call/3.md), [**sd\_bus\_message\_new\_method\_error**(3)](/sd_bus_message_new_method_error/3.md), [**sd\_bus\_message\_new\_method\_return**(3)](/sd_bus_message_new_method_return/3.md), and [**sd\_bus\_message\_new\_signal**(3)](/sd_bus_message_new_signal/3.md) that create a message of a certain type and initialize various fields are easier to use.

The *type* parameter specifies the type of the message. It must be one of **SD\_BUS\_MESSAGE\_METHOD\_CALL** — a method call, **SD\_BUS\_MESSAGE\_METHOD\_RETURN** — a method call reply, **SD\_BUS\_MESSAGE\_METHOD\_ERROR** — an error reply to a method call, **SD\_BUS\_MESSAGE\_SIGNAL** — a broadcast message with no reply.

The flag to allow interactive authorization is initialized based on the current value set in the bus object, see [**sd\_bus\_set\_allow\_interactive\_authorization**(3)](/sd_bus_set_allow_interactive_authorization/3.md). This may be changed using [**sd\_bus\_message\_set\_allow\_interactive\_authorization**(3)](/sd_bus_message_set_allow_interactive_authorization/3.md).

**sd\_bus\_message\_ref()** increases the internal reference counter of *m* by one.

**sd\_bus\_message\_unref()** decreases the internal reference counter of *m* by one. Once the reference count has dropped to zero, message object is destroyed and cannot be used anymore, so further calls to **sd\_bus\_message\_ref()** or **sd\_bus\_message\_unref()** are illegal.

**sd\_bus\_message\_unrefp()** is similar to **sd\_bus\_message\_unref()** but takes a pointer to a pointer to an **sd\_bus\_message** object. This call is useful in conjunction with GCC's and LLVM's **Clean-up Variable Attribute**\[1\]. See [**sd\_bus\_new**(3)](/sd_bus_new/3.md) for an example how to use the cleanup attribute.

**sd\_bus\_message\_ref()** and **sd\_bus\_message\_unref()** execute no operation if the passed in bus message object address is **NULL**. **sd\_bus\_message\_unrefp()** will first dereference its argument, which must not be **NULL**, and will execute no operation if *that* is **NULL**.

**sd\_bus\_message\_get\_bus()** returns the bus object that message *m* is attached to.

## RETURN VALUE

On success, **sd\_bus\_message\_new()** returns 0 or a positive integer. On failure, it returns a negative errno-style error code.

**sd\_bus\_message\_ref()** always returns the argument.

**sd\_bus\_message\_unref()** always returns **NULL**.

**sd\_bus\_message\_get\_bus()** always returns the bus object.

### Errors

Returned errors may indicate the following problems:

**-EINVAL**

Specified *type* is invalid.

**-ENOTCONN**

The bus parameter *bus* is **NULL** or the bus is not connected.

**-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)](/pkg-config/1.md) file.

The code described here uses [**getenv**(3)](/getenv/3.md), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call [**setenv**(3)](/setenv/3.md) 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.

## HISTORY

**sd\_bus\_message\_new()**, **sd\_bus\_message\_ref()**, **sd\_bus\_message\_unref()**, **sd\_bus\_message\_unrefp()**, and **sd\_bus\_message\_get\_bus()** were added in version 240.

## SEE ALSO

[**systemd**(1)](/systemd/1.md), [**sd-bus**(3)](/sd-bus/3.md), [**sd\_bus\_new**(3)](/sd_bus_new/3.md), [**sd\_bus\_message\_new\_method\_call**(3)](/sd_bus_message_new_method_call/3.md), [**sd\_bus\_message\_new\_method\_error**(3)](/sd_bus_message_new_method_error/3.md), [**sd\_bus\_message\_new\_method\_return**(3)](/sd_bus_message_new_method_return/3.md), [**sd\_bus\_message\_new\_signal**(3)](/sd_bus_message_new_signal/3.md)

## NOTES

- 1\.

  Clean-up Variable Attribute

  https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html