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 |EXAMPLES |SEE ALSO |NOTES |COLOPHON | |
SD_BUS_...ONTAINER(3) sd_bus_message_open_containerSD_BUS_...ONTAINER(3)sd_bus_message_open_container, sd_bus_message_close_container, sd_bus_message_enter_container, sd_bus_message_exit_container - Create and move between containers in D-Bus messages
#include <systemd/sd-bus.h>int sd_bus_message_open_container(sd_bus_message *m, chartype,const char *contents);int sd_bus_message_close_container(sd_bus_message *m);int sd_bus_message_enter_container(sd_bus_message *m, chartype,const char *contents);int sd_bus_message_exit_container(sd_bus_message *m);
sd_bus_message_open_container()appends a new container to the messagem. After opening a new container, it can be filled with content usingsd_bus_message_append(3) and similar functions. Containers behave like a stack. To nest containers inside each other, callsd_bus_message_open_container()multiple times without callingsd_bus_message_close_container()in between. Each container will be nested inside the previous container.type represents the container type and should be one of "r", "a", "v" or "e" as described insd_bus_message_append(3). Instead of literals, the corresponding constantsSD_BUS_TYPE_STRUCT,SD_BUS_TYPE_ARRAY,SD_BUS_TYPE_VARIANTorSD_BUS_TYPE_DICT_ENTRY can also be used.contents describes the type of the container's elements and should be a D-Bus type string following the rules described insd_bus_message_append(3).sd_bus_message_close_container()closes the last container opened withsd_bus_message_open_container(). On success, the write pointer of the messagem is positioned after the closed container in its parent container or inm itself if there is no parent container.sd_bus_message_enter_container()enters the next container of the messagem for reading. It behaves mostly the same assd_bus_message_open_container(). Entering a container allows reading its contents withsd_bus_message_read(3) and similar functions.type andcontents are the same as insd_bus_message_open_container().sd_bus_message_exit_container()exits the scope of the last container entered withsd_bus_message_enter_container(). It behaves mostly the same assd_bus_message_close_container(). Note thatsd_bus_message_exit_container()may only be called after iterating through all members of the container, i.e. reading or skipping over them. Usesd_bus_message_skip(3) to skip over fields of a container in order to be able to exit the container withsd_bus_message_exit_container()without reading all members.
On success, these functions return a non-negative integer.sd_bus_message_open_container()andsd_bus_message_close_container()return 0.sd_bus_message_enter_container()returns 1 if it successfully opened a new container, and 0 if that was not possible because the end of the currently open container or message was reached.sd_bus_message_exit_container()returns 1 on success. On failure, all of these functions return a negative errno-style error code.Errors Returned errors may indicate the following problems:-EINVALm orcontents areNULLortype is invalid. Added in version 246.-EBADMSG Messagem has invalid structure. Added in version 254.-ENXIO Messagem does not have a container of typetype at the current position, or the contents do not matchcontents. Added in version 254.-EPERM The messagem is already sealed. Added in version 246.-ESTALE The messagem is in an invalid state. Added in version 246.-ENOMEM Memory allocation failed. Added in version 246.-EBUSYsd_bus_message_exit_container()was called but there are unread members left in the container. Added in version 247.
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.
Example 1. Append an array of strings to a message /* SPDX-License-Identifier: MIT-0 */ #include <systemd/sd-bus.h> int append_strings_to_message(sd_bus_message *m, const char *const *arr) { const char *s; int r; r = sd_bus_message_open_container(m, 'a', "s"); if (r < 0) return r; for (s = *arr; *s; s++) { r = sd_bus_message_append(m, "s", s); if (r < 0) return r; } return sd_bus_message_close_container(m); }Example 2. Read an array of strings from a message /* SPDX-License-Identifier: MIT-0 */ #include <stdio.h> #include <systemd/sd-bus.h> int read_strings_from_message(sd_bus_message *m) { int r; r = sd_bus_message_enter_container(m, 'a', "s"); if (r < 0) return r; for (;;) { const char *s; r = sd_bus_message_read(m, "s", &s); if (r < 0) return r; if (r == 0) break; printf("%s\n", s); } return sd_bus_message_exit_container(m); }systemd(1),sd-bus(3),sd_bus_message_append(3),sd_bus_message_read(3),sd_bus_message_skip(3),The D-Busspecification[1]
1. The D-Bus specificationhttps://dbus.freedesktop.org/doc/dbus-specification.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_...ONTAINER(3)Pages that refer to this page:sd-bus(3), sd_bus_message_append(3), sd_bus_message_read(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. | |