HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |NOTES |HISTORY |SEE ALSO |NOTES |COLOPHON | |
SD_BUS_MESSAGE_NEW(3) sd_bus_message_newSD_BUS_MESSAGE_NEW(3)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
#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_ttype);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);sd_bus_message_new()creates a new bus message object attached to the busbus and returns it in the output parameterm. 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 likesd_bus_message_new_method_call(3),sd_bus_message_new_method_error(3),sd_bus_message_new_method_return(3), andsd_bus_message_new_signal(3) that create a message of a certain type and initialize various fields are easier to use. Thetype parameter specifies the type of the message. It must be one ofSD_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, seesd_bus_set_allow_interactive_authorization(3). This may be changed usingsd_bus_message_set_allow_interactive_authorization(3).sd_bus_message_ref()increases the internal reference counter ofm by one.sd_bus_message_unref()decreases the internal reference counter ofm by one. Once the reference count has dropped to zero, message object is destroyed and cannot be used anymore, so further calls tosd_bus_message_ref()orsd_bus_message_unref()are illegal.sd_bus_message_unrefp()is similar tosd_bus_message_unref()but takes a pointer to a pointer to ansd_bus_messageobject. This call is useful in conjunction with GCC's and LLVM'sClean-upVariable Attribute[1]. Seesd_bus_new(3) for an example how to use the cleanup attribute.sd_bus_message_ref()andsd_bus_message_unref()execute no operation if the passed in bus message object address isNULL.sd_bus_message_unrefp()will first dereference its argument, which must not beNULL, and will execute no operation ifthat isNULL.sd_bus_message_get_bus()returns the bus object that messagem is attached to.
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 returnsNULL.sd_bus_message_get_bus()always returns the bus object.Errors Returned errors may indicate the following problems:-EINVAL Specifiedtype is invalid.-ENOTCONN The bus parameterbus isNULLor the bus is not connected.-ENOMEM Memory allocation failed.
Functions described here are available as a shared library, which can be compiled against and linked to with thelibsystemd pkg-config(1) file. The code described here usesgetenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not callsetenv(3) from a parallel thread. It is recommended to only do calls tosetenv()from an early phase of the program when no other threads have been started.
sd_bus_message_new(),sd_bus_message_ref(),sd_bus_message_unref(),sd_bus_message_unrefp(), andsd_bus_message_get_bus()were added in version 240.
systemd(1),sd-bus(3),sd_bus_new(3),sd_bus_message_new_method_call(3),sd_bus_message_new_method_error(3),sd_bus_message_new_method_return(3),sd_bus_message_new_signal(3)
1. Clean-up Variable Attributehttps://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
This page is part of thesystemd (systemd system and service manager) project. Information about the project can be found at ⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a bug report for this manual page, see ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩. This page was obtained from the project's upstream Git repository ⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgsystemd 258~rc2SD_BUS_MESSAGE_NEW(3)Pages that refer to this page:sd-bus(3), sd_bus_add_match(3), sd_bus_call(3), sd_bus_message_get_signature(3), sd_bus_message_get_type(3), sd_bus_process(3), sd_bus_slot_ref(3), systemd.directives(7), systemd.index(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |