picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
Systemd/src/systemd/sd-device.h

129 lines
6.2 KiB
C
Raw Normal View History

license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 05:23:58 +01:00
/* SPDX-License-Identifier: LGPL-2.1-or-later */
libsystemd: add sd-device library This provides equivalent functionality to libudev-device, but in the systemd style. The public API only caters to creating sd_device objects from for devices that already exist in /sys, there is no support for listening for monitoring events or creating devices received over the udev netlink protocol. The private API contains the necessary functionality to make sd-device a drop-in replacement for libudev-device, but which we would not otherwise want to export.
2015-04-01 13:50:31 +02:00
#ifndef foosddevicehfoo
#define foosddevicehfoo
/***
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
***/
sd-*.h: clean up exported (or to-be-exported) header files Exported header files should not include internal headers. Fix that. Exported header files should not use the bool type. So far we opted to stick to C89 for exported headers, and hence use "int" for bools in them. Continue to do so. Exported header files should have #include lines for everything they use including inttypes.h and sys/types.h, so that they may be included in any order. Exported header files should have C++ guards, hence add them. Exported header files should not use gcc extensions like #pragma once, get rid of it.
2015-10-24 23:42:56 +02:00
#include <inttypes.h>
include sys/sysmacros.h in more places Since glibc is moving away from implicitly including sys/sysmacros.h all the time via sys/types.h, include the header directly in more places. This seems to cover most makedev/major/minor usage.
2016-03-14 22:44:49 +01:00
#include <sys/sysmacros.h>
tree-wide: sort includes in *.h This is a continuation of the previous include sort patch, which only sorted for .c files.
2015-11-18 22:46:33 +01:00
#include <sys/types.h>
libsystemd: add sd-device library This provides equivalent functionality to libudev-device, but in the systemd style. The public API only caters to creating sd_device objects from for devices that already exist in /sys, there is no support for listening for monitoring events or creating devices received over the udev netlink protocol. The private API contains the necessary functionality to make sd-device a drop-in replacement for libudev-device, but which we would not otherwise want to export.
2015-04-01 13:50:31 +02:00
sd-device: introduce sd_device_monitor
2018-10-08 15:45:52 +02:00
#include "sd-event.h"
libsystemd: add sd-device library This provides equivalent functionality to libudev-device, but in the systemd style. The public API only caters to creating sd_device objects from for devices that already exist in /sys, there is no support for listening for monitoring events or creating devices received over the udev netlink protocol. The private API contains the necessary functionality to make sd-device a drop-in replacement for libudev-device, but which we would not otherwise want to export.
2015-04-01 13:50:31 +02:00
#include "_sd-common.h"
_SD_BEGIN_DECLARATIONS;
typedef struct sd_device sd_device;
sd-device: add device-enumerator library
2015-04-14 16:22:39 +02:00
typedef struct sd_device_enumerator sd_device_enumerator;
sd-device: introduce sd_device_monitor
2018-10-08 15:45:52 +02:00
typedef struct sd_device_monitor sd_device_monitor;
/* callback */
typedef int (*sd_device_monitor_handler_t)(sd_device_monitor *m, sd_device *device, void *userdata);
sd-device: add device-enumerator library
2015-04-14 16:22:39 +02:00
/* device */
libsystemd: add sd-device library This provides equivalent functionality to libudev-device, but in the systemd style. The public API only caters to creating sd_device objects from for devices that already exist in /sys, there is no support for listening for monitoring events or creating devices received over the udev netlink protocol. The private API contains the necessary functionality to make sd-device a drop-in replacement for libudev-device, but which we would not otherwise want to export.
2015-04-01 13:50:31 +02:00
sd_device *sd_device_ref(sd_device *device);
sd_device *sd_device_unref(sd_device *device);
int sd_device_new_from_syspath(sd_device **ret, const char *syspath);
int sd_device_new_from_devnum(sd_device **ret, char type, dev_t devnum);
int sd_device_new_from_subsystem_sysname(sd_device **ret, const char *subsystem, const char *sysname);
int sd_device_new_from_device_id(sd_device **ret, const char *id);
int sd_device_get_parent(sd_device *child, sd_device **ret);
int sd_device_get_parent_with_subsystem_devtype(sd_device *child, const char *subsystem, const char *devtype, sd_device **ret);
int sd_device_get_syspath(sd_device *device, const char **ret);
int sd_device_get_subsystem(sd_device *device, const char **ret);
int sd_device_get_devtype(sd_device *device, const char **ret);
int sd_device_get_devnum(sd_device *device, dev_t *devnum);
int sd_device_get_ifindex(sd_device *device, int *ifindex);
int sd_device_get_driver(sd_device *device, const char **ret);
int sd_device_get_devpath(sd_device *device, const char **ret);
int sd_device_get_devname(sd_device *device, const char **ret);
int sd_device_get_sysname(sd_device *device, const char **ret);
int sd_device_get_sysnum(sd_device *device, const char **ret);
sd-device: make sd_device_get_is_initialized() returns is_initialized by return value
2018-10-29 09:32:21 +01:00
int sd_device_get_is_initialized(sd_device *device);
libsystemd: add sd-device library This provides equivalent functionality to libudev-device, but in the systemd style. The public API only caters to creating sd_device objects from for devices that already exist in /sys, there is no support for listening for monitoring events or creating devices received over the udev netlink protocol. The private API contains the necessary functionality to make sd-device a drop-in replacement for libudev-device, but which we would not otherwise want to export.
2015-04-01 13:50:31 +02:00
int sd_device_get_usec_since_initialized(sd_device *device, uint64_t *usec);
const char *sd_device_get_tag_first(sd_device *device);
const char *sd_device_get_tag_next(sd_device *device);
udev: make tags "sticky" This tries to address the "bind"/"unbind" uevent kernel API breakage, by changing the semantics of device tags. Previously, tags would be applied on uevents (and the database entries they result in) only depending on the immediate context. This means that if one uevent causes the tag to be set and the next to be unset, this would immediately effect what apps would see and the database entries would contain each time. This is problematic however, as tags are a filtering concept, and if tags vanish then clients won't hence notice when a device stops being relevant to them since not only the tags disappear but immediately also the uevents for it are filtered including the one necessary for the app to notice that the device lost its tag and hence relevance. With this change tags become "sticky". If a tag is applied is once applied to a device it will stay in place forever, until the device is removed. Tags can never be removed again. This means that an app watching a specific set of devices by filtering for a tag is guaranteed to not only see the events where the tag is set but also all follow-up events where the tags might be removed again. This change of behaviour is unfortunate, but is required due to the kernel introducing new "bind" and "unbind" uevents that generally have the effect that tags and properties disappear and apps hence don't notice when a device looses relevance to it. "bind"/"unbind" events were introduced in kernel 4.12, and are now used in more and more subsystems. The introduction broke userspace widely, and this commit is an attempt to provide a way for apps to deal with it. While tags are now "sticky" a new automatic device property CURRENT_TAGS is introduced (matching the existing TAGS property) that always reflects the precise set of tags applied on the most recent events. Thus, when subscribing to devices through tags, all devices that ever had the tag put on them will be be seen, and by CURRENT_TAGS it may be checked whether the device right at the moment matches the tag requirements. See: #7587 #7018 #8221
2018-12-13 17:55:14 +01:00
const char *sd_device_get_current_tag_first(sd_device *device);
const char *sd_device_get_current_tag_next(sd_device *device);
libsystemd: add sd-device library This provides equivalent functionality to libudev-device, but in the systemd style. The public API only caters to creating sd_device objects from for devices that already exist in /sys, there is no support for listening for monitoring events or creating devices received over the udev netlink protocol. The private API contains the necessary functionality to make sd-device a drop-in replacement for libudev-device, but which we would not otherwise want to export.
2015-04-01 13:50:31 +02:00
const char *sd_device_get_devlink_first(sd_device *device);
const char *sd_device_get_devlink_next(sd_device *device);
const char *sd_device_get_property_first(sd_device *device, const char **value);
const char *sd_device_get_property_next(sd_device *device, const char **value);
const char *sd_device_get_sysattr_first(sd_device *device);
const char *sd_device_get_sysattr_next(sd_device *device);
int sd_device_has_tag(sd_device *device, const char *tag);
udev: make tags "sticky" This tries to address the "bind"/"unbind" uevent kernel API breakage, by changing the semantics of device tags. Previously, tags would be applied on uevents (and the database entries they result in) only depending on the immediate context. This means that if one uevent causes the tag to be set and the next to be unset, this would immediately effect what apps would see and the database entries would contain each time. This is problematic however, as tags are a filtering concept, and if tags vanish then clients won't hence notice when a device stops being relevant to them since not only the tags disappear but immediately also the uevents for it are filtered including the one necessary for the app to notice that the device lost its tag and hence relevance. With this change tags become "sticky". If a tag is applied is once applied to a device it will stay in place forever, until the device is removed. Tags can never be removed again. This means that an app watching a specific set of devices by filtering for a tag is guaranteed to not only see the events where the tag is set but also all follow-up events where the tags might be removed again. This change of behaviour is unfortunate, but is required due to the kernel introducing new "bind" and "unbind" uevents that generally have the effect that tags and properties disappear and apps hence don't notice when a device looses relevance to it. "bind"/"unbind" events were introduced in kernel 4.12, and are now used in more and more subsystems. The introduction broke userspace widely, and this commit is an attempt to provide a way for apps to deal with it. While tags are now "sticky" a new automatic device property CURRENT_TAGS is introduced (matching the existing TAGS property) that always reflects the precise set of tags applied on the most recent events. Thus, when subscribing to devices through tags, all devices that ever had the tag put on them will be be seen, and by CURRENT_TAGS it may be checked whether the device right at the moment matches the tag requirements. See: #7587 #7018 #8221
2018-12-13 17:55:14 +01:00
int sd_device_has_current_tag(sd_device *device, const char *tag);
libsystemd: add sd-device library This provides equivalent functionality to libudev-device, but in the systemd style. The public API only caters to creating sd_device objects from for devices that already exist in /sys, there is no support for listening for monitoring events or creating devices received over the udev netlink protocol. The private API contains the necessary functionality to make sd-device a drop-in replacement for libudev-device, but which we would not otherwise want to export.
2015-04-01 13:50:31 +02:00
int sd_device_get_property_value(sd_device *device, const char *key, const char **value);
int sd_device_get_sysattr_value(sd_device *device, const char *sysattr, const char **_value);
sd-device,libudev: make an argument for *_set_sysattr_value() const
2018-09-11 05:42:18 +02:00
int sd_device_set_sysattr_value(sd_device *device, const char *sysattr, const char *value);
sd-device: introduce sd_device_set_sysattr_valuef()
2020-09-11 10:41:10 +02:00
int sd_device_set_sysattr_valuef(sd_device *device, const char *sysattr, const char *format, ...) _sd_printf_(3, 4);
libsystemd: add sd-device library This provides equivalent functionality to libudev-device, but in the systemd style. The public API only caters to creating sd_device objects from for devices that already exist in /sys, there is no support for listening for monitoring events or creating devices received over the udev netlink protocol. The private API contains the necessary functionality to make sd-device a drop-in replacement for libudev-device, but which we would not otherwise want to export.
2015-04-01 13:50:31 +02:00
sd-device: add device-enumerator library
2015-04-14 16:22:39 +02:00
/* device enumerator */
int sd_device_enumerator_new(sd_device_enumerator **ret);
sd_device_enumerator *sd_device_enumerator_ref(sd_device_enumerator *enumerator);
sd_device_enumerator *sd_device_enumerator_unref(sd_device_enumerator *enumerator);
sd_device *sd_device_enumerator_get_device_first(sd_device_enumerator *enumerator);
sd_device *sd_device_enumerator_get_device_next(sd_device_enumerator *enumerator);
sd_device *sd_device_enumerator_get_subsystem_first(sd_device_enumerator *enumerator);
sd_device *sd_device_enumerator_get_subsystem_next(sd_device_enumerator *enumerator);
int sd_device_enumerator_add_match_subsystem(sd_device_enumerator *enumerator, const char *subsystem, int match);
int sd_device_enumerator_add_match_sysattr(sd_device_enumerator *enumerator, const char *sysattr, const char *value, int match);
int sd_device_enumerator_add_match_property(sd_device_enumerator *enumerator, const char *property, const char *value);
int sd_device_enumerator_add_match_sysname(sd_device_enumerator *enumerator, const char *sysname);
int sd_device_enumerator_add_match_tag(sd_device_enumerator *enumerator, const char *tag);
int sd_device_enumerator_add_match_parent(sd_device_enumerator *enumerator, sd_device *parent);
sd-device: enumerator - match only on initialized devices by default It is still possible to include uninitialized ones, but now that is opt-in. In most cases people only want initialized devices. Exception is if you want to work without udev running. Suggested by David Herrmann.
2015-04-17 14:11:00 +02:00
int sd_device_enumerator_allow_uninitialized(sd_device_enumerator *enumerator);
sd-device: add device-enumerator library
2015-04-14 16:22:39 +02:00
sd-device: introduce sd_device_monitor
2018-10-08 15:45:52 +02:00
/* device monitor */
int sd_device_monitor_new(sd_device_monitor **ret);
sd_device_monitor *sd_device_monitor_ref(sd_device_monitor *m);
sd_device_monitor *sd_device_monitor_unref(sd_device_monitor *m);
int sd_device_monitor_set_receive_buffer_size(sd_device_monitor *m, size_t size);
sd-device: drop priority and description from sd_device_monitor_attach_event() and sd_device_monitor_start() Now we have sd_device_monitor_get_event_soruce(). So, it is not necessary to include these parameters in the functions for sd_device_monitor.
2018-11-10 14:50:11 +01:00
int sd_device_monitor_attach_event(sd_device_monitor *m, sd_event *event);
sd-device: introduce sd_device_monitor
2018-10-08 15:45:52 +02:00
int sd_device_monitor_detach_event(sd_device_monitor *m);
sd_event *sd_device_monitor_get_event(sd_device_monitor *m);
sd-device: add sd_device_monitor_get_event_source()
2018-11-10 14:13:07 +01:00
sd_event_source *sd_device_monitor_get_event_source(sd_device_monitor *m);
sd-device: drop priority and description from sd_device_monitor_attach_event() and sd_device_monitor_start() Now we have sd_device_monitor_get_event_soruce(). So, it is not necessary to include these parameters in the functions for sd_device_monitor.
2018-11-10 14:50:11 +01:00
int sd_device_monitor_start(sd_device_monitor *m, sd_device_monitor_handler_t callback, void *userdata);
sd-device: introduce sd_device_monitor
2018-10-08 15:45:52 +02:00
int sd_device_monitor_stop(sd_device_monitor *m);
int sd_device_monitor_filter_add_match_subsystem_devtype(sd_device_monitor *m, const char *subsystem, const char *devtype);
int sd_device_monitor_filter_add_match_tag(sd_device_monitor *m, const char *tag);
int sd_device_monitor_filter_update(sd_device_monitor *m);
int sd_device_monitor_filter_remove(sd_device_monitor *m);
tree-wide: expose "p"-suffix unref calls in public APIs to make gcc cleanup easy GLIB has recently started to officially support the gcc cleanup attribute in its public API, hence let's do the same for our APIs. With this patch we'll define an xyz_unrefp() call for each public xyz_unref() call, to make it easy to use inside a __attribute__((cleanup())) expression. Then, all code is ported over to make use of this. The new calls are also documented in the man pages, with examples how to use them (well, I only added docs where the _unref() call itself already had docs, and the examples, only cover sd_bus_unrefp() and sd_event_unrefp()). This also renames sd_lldp_free() to sd_lldp_unref(), since that's how we tend to call our destructors these days. Note that this defines no public macro that wraps gcc's attribute and makes it easier to use. While I think it's our duty in the library to make our stuff easy to use, I figure it's not our duty to make gcc's own features easy to use on its own. Most likely, client code which wants to make use of this should define its own: #define _cleanup_(function) __attribute__((cleanup(function))) Or similar, to make the gcc feature easier to use. Making this logic public has the benefit that we can remove three header files whose only purpose was to define these functions internally. See #2008.
2015-11-27 19:13:45 +01:00
_SD_DEFINE_POINTER_CLEANUP_FUNC(sd_device, sd_device_unref);
_SD_DEFINE_POINTER_CLEANUP_FUNC(sd_device_enumerator, sd_device_enumerator_unref);
sd-device: introduce sd_device_monitor
2018-10-08 15:45:52 +02:00
_SD_DEFINE_POINTER_CLEANUP_FUNC(sd_device_monitor, sd_device_monitor_unref);
tree-wide: expose "p"-suffix unref calls in public APIs to make gcc cleanup easy GLIB has recently started to officially support the gcc cleanup attribute in its public API, hence let's do the same for our APIs. With this patch we'll define an xyz_unrefp() call for each public xyz_unref() call, to make it easy to use inside a __attribute__((cleanup())) expression. Then, all code is ported over to make use of this. The new calls are also documented in the man pages, with examples how to use them (well, I only added docs where the _unref() call itself already had docs, and the examples, only cover sd_bus_unrefp() and sd_event_unrefp()). This also renames sd_lldp_free() to sd_lldp_unref(), since that's how we tend to call our destructors these days. Note that this defines no public macro that wraps gcc's attribute and makes it easier to use. While I think it's our duty in the library to make our stuff easy to use, I figure it's not our duty to make gcc's own features easy to use on its own. Most likely, client code which wants to make use of this should define its own: #define _cleanup_(function) __attribute__((cleanup(function))) Or similar, to make the gcc feature easier to use. Making this logic public has the benefit that we can remove three header files whose only purpose was to define these functions internally. See #2008.
2015-11-27 19:13:45 +01:00
libsystemd: add sd-device library This provides equivalent functionality to libudev-device, but in the systemd style. The public API only caters to creating sd_device objects from for devices that already exist in /sys, there is no support for listening for monitoring events or creating devices received over the udev netlink protocol. The private API contains the necessary functionality to make sd-device a drop-in replacement for libudev-device, but which we would not otherwise want to export.
2015-04-01 13:50:31 +02:00
_SD_END_DECLARATIONS;
#endif
Reference in a new issue Copy permalink