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 |REFERENCE OWNERSHIP |NOTES |HISTORY |SEE ALSO |NOTES |COLOPHON | |
SD_BUS_TRACK_NEW(3) sd_bus_track_newSD_BUS_TRACK_NEW(3)sd_bus_track_new, sd_bus_track_ref, sd_bus_track_unref, sd_bus_track_unrefp, sd_bus_track_set_recursive, sd_bus_track_get_recursive, sd_bus_track_get_bus, sd_bus_track_get_userdata, sd_bus_track_set_userdata - Track bus peers
#include <systemd/sd-bus.h>int sd_bus_track_new(sd_bus*bus, sd_bus_track**ret,sd_bus_track_handler_thandler,void*userdata);sd_bus_track *sd_bus_track_ref(sd_bus_track *t);sd_bus_track *sd_bus_track_unref(sd_bus_track *t);void sd_bus_track_unrefp(sd_bus_track **t);int sd_bus_track_get_recursive(sd_bus_track *t);int sd_bus_track_set_recursive(sd_bus_track *t, intb);sd_bus* sd_bus_track_get_bus(sd_bus_track *t);void* sd_bus_track_get_userdata(sd_bus_track *t);void* sd_bus_track_set_userdata(sd_bus_track *t, void *userdata);
sd_bus_track_new()creates a new bus peer tracking object. The object is allocated for the specified bus, and returned in the*ret parameter. After use, the object should be freed again by dropping the acquired reference withsd_bus_track_unref()(see below). A bus peer tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to specific bus peers are added viasd_bus_track_add_name(3) orsd_bus_track_add_sender(). They may be dropped again viasd_bus_track_remove_name()andsd_bus_track_remove_sender(). Alternatively, references on peers are removed automatically when they disconnect from the bus. If non-NULLthehandler may specify a function that is invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly viasd_bus_track_remove_name()or implicitly because the peer disconnected from the bus. The final argumentuserdata may be used to attach a generic user data pointer to the object. This pointer is passed to the handler callback when it is invoked.sd_bus_track_ref()creates a new reference to a bus peer tracking object. This object will not be destroyed untilsd_bus_track_unref()has been called as many times plus once more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls tosd_bus_track_ref()orsd_bus_track_unref()on the same object are illegal.sd_bus_track_unref()destroys a reference to a bus peer tracking object.sd_bus_track_unrefp()is similar tosd_bus_track_unref()but takes a pointer to a pointer to ansd_bus_trackobject. This call is useful in conjunction with GCC's and LLVM'sClean-up VariableAttribute[1]. Note that this function is defined as inline function.sd_bus_track_ref(),sd_bus_track_unref()andsd_bus_track_unrefp() execute no operation if the passed in bus peer tracking object isNULL. Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked or not tracked. In this mode invokingsd_bus_track_add_name()multiple times in a row for the same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if necessary, and executes no operation if the peer is already being tracked. A single invocation ofsd_bus_track_remove_name()removes the reference on the peer again, regardless how many timessd_bus_track_add_name() was called before. If operating in recursive mode, the number of timessd_bus_track_add_name()is invoked for the same peer name is counted andsd_bus_track_remove_name()must be called the same number of times before the peer is not tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is irrelevant and the tracking of the specific peer is immediately removed.sd_bus_track_get_recursive()may be used to determine whether the bus peer tracking object is operating in recursive mode.sd_bus_track_set_recursive()may be used to enable or disable recursive mode. By default, a bus peer tracking object operates in non-recursive mode, andsd_bus_track_get_recursive()for a newly allocated object hence returns a value equal to zero. Usesd_bus_track_set_recursive()to enable recursive mode, right after allocation. It takes a boolean argument to enable or disable recursive mode. Note that tracking objects for whichsd_bus_track_add_name()was already invoked at least once (and which hence track already one or more peers) may not be switched from recursive to non-recursive mode anymore.sd_bus_track_get_bus()returns the bus object the bus peer tracking object belongs to. It returns the bus object initially passed tosd_bus_track_new()when the object was allocated.sd_bus_track_get_userdata()returns the generic user data pointer set on the bus peer tracking object at the time of creation usingsd_bus_track_new()or at a later time, usingsd_bus_track_set_userdata().
On success,sd_bus_track_new()andsd_bus_track_set_recursive() return 0 or a positive integer. On failure, they return a negative errno-style error code.sd_bus_track_ref()always returns the argument.sd_bus_track_unref()always returnsNULL.sd_bus_track_get_recursive()returns 0 if non-recursive mode is selected (default), and greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned.sd_bus_track_get_bus()returns the bus object associated to the bus peer tracking object.sd_bus_track_get_userdata()returns the generic user data pointer associated with the bus peer tracking object.sd_bus_track_set_userdata()returns the previous user data pointer set.
Thesd_bus_track_new()function creates a new object and the caller owns the sole reference. When not needed anymore, this reference should be destroyed withsd_bus_track_unref().Errors Returned errors may indicate the following problems:-EBUSY Bus peers have already been added to the bus peer tracking object andsd_bus_track_set_recursive()was called to change tracking mode.-EINVAL Specified parameter is invalid (NULLin case of output parameters).-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_track_new(),sd_bus_track_ref(),sd_bus_track_unref(),sd_bus_track_unrefp(),sd_bus_track_get_recursive(),sd_bus_track_set_recursive(),sd_bus_track_get_bus(),sd_bus_track_get_userdata(), andsd_bus_track_set_userdata()were added in version 232.
systemd(1),sd-bus(3),sd_bus_track_add_name(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_TRACK_NEW(3)Pages that refer to this page:sd-bus(3), sd_bus_slot_set_destroy_callback(3), sd_bus_track_add_name(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. | |