From 778816f4c82c1349fdb69c9e37d88e3f6a1303cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 15 May 2023 22:37:20 +0200 Subject: [PATCH 1/4] meson: add sd_pid_notify_barrier link Fixup for 0de343187127f6a5a93602608812e60fc4092c9a. --- man/rules/meson.build | 1 + 1 file changed, 1 insertion(+) diff --git a/man/rules/meson.build b/man/rules/meson.build index 13d2bd9b58..b5aa2bff8a 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -807,6 +807,7 @@ manpages = [ ['sd_notify_barrier', 'sd_notifyf', 'sd_pid_notify', + 'sd_pid_notify_barrier', 'sd_pid_notify_with_fds', 'sd_pid_notifyf', 'sd_pid_notifyf_with_fds'], From 4bc96dc16258d38d752a32612f196de6516fb27f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 15 May 2023 15:17:13 +0200 Subject: [PATCH 2/4] man: add libsystemd(3) Before libsystemd-daemon, libsystemd-journal, libsystemd-id128, etc., were merged into libsystemd, it was enough to have individual man pages for them. But they have been delivered as one thing for many years, so it's better to have a landing page for libsystemd. It mostly directs to individual pages anyway. --- man/libsystemd.xml | 89 +++++++++++++++++++++++++++++++++++++++++++ man/rules/meson.build | 1 + man/sd-bus-errors.xml | 1 + man/sd-bus.xml | 7 ++-- man/sd-daemon.xml | 9 +++-- man/sd-device.xml | 6 ++- man/sd-event.xml | 5 ++- man/sd-hwdb.xml | 6 ++- man/sd-id128.xml | 12 +++--- man/sd-journal.xml | 5 ++- man/sd-login.xml | 7 ++-- 11 files changed, 125 insertions(+), 23 deletions(-) create mode 100644 man/libsystemd.xml diff --git a/man/libsystemd.xml b/man/libsystemd.xml new file mode 100644 index 0000000000..e9de64ca70 --- /dev/null +++ b/man/libsystemd.xml @@ -0,0 +1,89 @@ + + + + + + + + libsystemd + systemd + + + + libsystemd + 3 + + + + libsystemd + Functions for implementing services and interacting with systemd + + + + +#include <systemd/sd-bus.h> +#include <systemd/sd-bus-vtable.h> +#include <systemd/sd-bus-protocol.h> +#include <systemd/sd-daemon.h> +#include <systemd/sd-device.h> +#include <systemd/sd-event.h> +#include <systemd/sd-gpt.h> +#include <systemd/sd-hwdb.h> +#include <systemd/sd-id128.h> +#include <systemd/sd-journal.h> +#include <systemd/sd-login.h> +#include <systemd/sd-messages.h> +#include <systemd/sd-path.h> + + + + pkg-config --cflags --libs libsystemd + + + + + Description + + The libsystemd library provides functions that allow interacting with various + interfaces provided by the + systemd1 service + manager, as well as various other functions and constants useful for implementing services in + general. + + See + sd-bus3, + sd-bus-errors3, + sd-daemon3, + sd-device3, + sd-event3, + sd-hwdb3, + sd-id1283, + sd-journal3, + and + sd-login3 + for information about different parts of the library interface. + + + + Interface stability + + Strict backwards-compatibility is maintained for the API (application programming interface) and + ABI (application binary interface). Symbol versioning is used, with symbols only added and never removed. + + + + + + + See Also + + systemd1, + libudev1, + pkg-config1, + Interface Portability and Stability Promise + + + + diff --git a/man/rules/meson.build b/man/rules/meson.build index b5aa2bff8a..6bd54739af 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -31,6 +31,7 @@ manpages = [ ['journald.conf', '5', ['journald.conf.d', 'journald@.conf'], ''], ['kernel-command-line', '7', [], ''], ['kernel-install', '8', [], 'ENABLE_KERNEL_INSTALL'], + ['libsystemd', '3', [], ''], ['libudev', '3', [], ''], ['loader.conf', '5', [], 'ENABLE_BOOTLOADER'], ['locale.conf', '5', [], ''], diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml index dc9d9fc63b..cade523763 100644 --- a/man/sd-bus-errors.xml +++ b/man/sd-bus-errors.xml @@ -274,6 +274,7 @@ systemd1, + libsystemd3, sd-bus3, sd_bus_error3, sd_bus_message_set_allow_interactive_authorization3, diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 36925ba8c4..4c9c00986a 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -34,10 +34,11 @@ Description - sd-bus.h provides an implementation of a D-Bus IPC client. See + sd-bus.h is part of + libsystemd3 and + provides an implementation of a D-Bus IPC client. See - for more information about D-Bus IPC. - + for more information about D-Bus IPC. See sd_bus_add_match3, diff --git a/man/sd-daemon.xml b/man/sd-daemon.xml index 5dee3e893c..6cd06a81e3 100644 --- a/man/sd-daemon.xml +++ b/man/sd-daemon.xml @@ -44,10 +44,11 @@ Description - sd-daemon.h provides APIs for new-style - daemons, as implemented by the - systemd1 - service manager. + sd-daemon.h is part of + libsystemd3 and + provides APIs for new-style daemons, as implemented by the + systemd1 service + manager. See sd_listen_fds3, diff --git a/man/sd-device.xml b/man/sd-device.xml index 7af839b4bd..4950781f84 100644 --- a/man/sd-device.xml +++ b/man/sd-device.xml @@ -34,8 +34,10 @@ Description - sd-device.h provides an API to introspect and enumerate devices on the local - system. It provides a programmatic interface to the database of devices and their properties mananaged by + sd-device.h is part of + libsystemd3 and + provides an API to introspect and enumerate devices on the local system. It provides a programmatic + interface to the database of devices and their properties mananaged by systemd-udevd.service8. This API is a replacement for libudev3 and diff --git a/man/sd-event.xml b/man/sd-event.xml index cb3108aee6..2f17b89145 100644 --- a/man/sd-event.xml +++ b/man/sd-event.xml @@ -34,8 +34,9 @@ Description - sd-event.h provides a generic event - loop implementation, based on Linux sd-event.h is part of + libsystemd3 and + provides a generic event loop implementation, based on Linux epoll7. diff --git a/man/sd-hwdb.xml b/man/sd-hwdb.xml index 254c218ac6..189fcd6b6c 100644 --- a/man/sd-hwdb.xml +++ b/man/sd-hwdb.xml @@ -34,8 +34,10 @@ Description - sd-hwdb.h allows read-only access the systemd database of hardware properties. - See hwdb7 and + sd-hwdb.h is part of + libsystemd3 and allows + read-only access the systemd database of hardware properties. See + hwdb7 and systemd-hwdb8 for more information about the database. diff --git a/man/sd-id128.xml b/man/sd-id128.xml index c869943ad7..245bfbb4d3 100644 --- a/man/sd-id128.xml +++ b/man/sd-id128.xml @@ -121,11 +121,13 @@ Description - sd-id128.h provides APIs to generate, convert, and compare 128-bit ID values. - The 128-bit ID values processed and generated by these APIs are a generalization of OSF UUIDs as defined - by RFC 4122 but use a simpler string format. - These functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are - mostly compatible with those types of IDs. + sd-id128.h is part of + libsystemd3 and + provides APIs to generate, convert, and compare 128-bit ID values. The 128-bit ID values processed and + generated by these APIs are a generalization of OSF UUIDs as defined by RFC 4122 but use a simpler string format. These + functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly + compatible with those types of IDs. A 128-bit ID is implemented as the following diff --git a/man/sd-journal.xml b/man/sd-journal.xml index 4609868c11..34debb4d36 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -36,8 +36,9 @@ Description - sd-journal.h provides APIs to submit - and query log entries. The APIs exposed act both as client for the + sd-journal.h is part of + libsystemd3 and + provides APIs to submit and query log entries. The APIs exposed act both as client for the systemd-journald.service8 journal service and as parser for the journal files on disk. diff --git a/man/sd-login.xml b/man/sd-login.xml index 0127b691f5..61b555a7ab 100644 --- a/man/sd-login.xml +++ b/man/sd-login.xml @@ -35,9 +35,10 @@ Description - sd-login.h provides APIs to introspect - and monitor seat, login session and user status information on the - local system. + sd-login.h is part of + libsystemd3 and + provides APIs to introspect and monitor seat, login session, and user status information on the local + system. Note that these APIs only allow purely passive access and monitoring of seats, sessions and users. To actively make changes From 522c108de10f85b3a3d8770c44bfdaf933ef57d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 15 May 2023 22:35:10 +0200 Subject: [PATCH 3/4] README: describe how our libraries are linked In https://github.com/systemd/systemd/pull/27637#issuecomment-1547517316 we discussed disclaiming warranty when distros do version mixing. But to make this disclaimer meaningful, we need to document what options are available. --- README | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/README b/README index d2d1def101..8d64ed769c 100644 --- a/README +++ b/README @@ -282,18 +282,54 @@ POLICY FOR SUPPORT OF DISTRIBUTIONS AND ARCHITECTURES: latest Ubuntu LTS and non-LTS releases, openSUSE Tumbleweed/Leap, CentOS Stream 8 and 9, up-to-date Arch, etc.) We will generally attempt to support also other non-EOL versions of various distros. - Features which would break compilation on slightly-older distributions + Features which would break compilation on slightly older distributions will only be introduced if there are significant reasons for this (i.e. supporting them interferes with development or requires too many resources to support). In some cases backports of specific libraries or tools might be required. - The policy is similar wrt. architecture support. systemd is regularly + The policy is similar for architecture support. systemd is regularly tested on popular architectures (currently amd64, i386, arm64, ppc64el, and s390x), but should compile and work also on other architectures, for which support has been added. systemd will emit warnings when architecture-specific constants are not defined. +STATIC COMPILATION AND "STANDALONE" BINARIES: + + systemd provides a public shared libraries libsystemd.so and + libudev.so. The latter is deprecated, and the sd-device APIs in + libsystemd should be used instead for new code. In addition, systemd is + built with a private shared library, libsystemd-shared-.so, + that also includes the libsystemd code, and by default most systemd + binaries are linked to it. Using shared libraries saves disk space and + memory at runtime, because only one copy of the code is needed. + + It is possible to build static versions of systemd public shared + libraries (via the configuration options '-Dstatic-libsystemd' and + '-Dstatic-libudev'). This allows the libsystemd and libudev code to be + linked statically into programs. In addition, it is possible to disable + the use of libsystemd-shared-.so for various components (via + the configuration options '-Dlink-*-shared'). In this mode, the + libsystemd and libsystemd-shared code is linked statically into + selected binaries. This option is intended for systems where some of + the components are intended to be delivered independently of the main + systemd package. Finally, some binaries can be compiled in a second + version (via the configuration option '-Dstandalone-binaries'). The + version suffixed with ".standalone" has the libsystemd and + libsystemd-shared code linked statically. Those binaries are intended + as replacements to be used in limited installations where the full + systemd is not installed. Yet another option is to rebuild systemd with + a different '-Dshared-lib-tag' setting, allowing different systemd + binaries to be linked to instances of the private shared library that + can be installed in parallel. + + Using the default shared linking is recommended. Mixing versions of + systemd components that would normally be built and used together (in + particular various daemons and the manager) is not recommended: we do + not test such combinations upstream and cannot provide support. + Distributors making use of those options are responsible if things do + not work as expected. + USERS AND GROUPS: Default udev rules use the following standard system group names, which need to be resolvable by getgrnam() at any time, even in the very early From 7ecce0e5716f0e9f08f7a2b4f77267541c0ce55b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 15 May 2023 22:48:50 +0200 Subject: [PATCH 4/4] docs: list all public headers in stability promise We provide the same stability for all the headers that are public. Also, mark id128 as portable to other systems. There is really nothing in the code that would make it hard. It would probably work out-of-the-box. --- docs/PORTABILITY_AND_STABILITY.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index dfbca2352a..82aefc742d 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -88,10 +88,17 @@ And now, here's the list of (hopefully) all APIs that we have introduced with sy | [Boot Loader interface](BOOT_LOADER_INTERFACE.md) | EFI variables | yes | yes | gummiboot | yes | - | no | | [Service bus API](https://www.freedesktop.org/software/systemd/man/org.freedesktop.systemd1.html) | D-Bus | yes | yes | system-config-services | no | - | no | | [logind](https://www.freedesktop.org/software/systemd/man/org.freedesktop.login1.html) | D-Bus | yes | yes | GNOME | no | - | no | -| [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, polkit, ... | no | - | no | +| [sd-bus.h API](https://www.freedesktop.org/software/systemd/man/sd-bus.html) | C Library | yes | yes | - | maybe | - | maybe | | [sd-daemon.h API](https://www.freedesktop.org/software/systemd/man/sd-daemon.html) | C Library or Drop-in | yes | yes | numerous | yes | - | yes | -| [sd-id128.h API](https://www.freedesktop.org/software/systemd/man/sd-id128.html) | C Library | yes | yes | - | yes | - | no | +| [sd-device.h API](https://www.freedesktop.org/software/systemd/man/sd-device.html) | C Library | yes | no | numerous | yes | - | yes | +| [sd-event.h API](https://www.freedesktop.org/software/systemd/man/sd-event.html) | C Library | yes | yes | - | maybe | - | maybe | +| [sd-gpt.h API](https://www.freedesktop.org/software/systemd/man/sd-gpt.html) | Header Library | yes | no | - | yes | - | yes | +| [sd-hwdb.h API](https://www.freedesktop.org/software/systemd/man/sd-hwdb.html) | C Library | yes | yes | - | maybe | - | yes | +| [sd-id128.h API](https://www.freedesktop.org/software/systemd/man/sd-id128.html) | C Library | yes | yes | - | yes | - | yes | | [sd-journal.h API](https://www.freedesktop.org/software/systemd/man/sd-journal.html) | C Library | yes | yes | - | maybe | - | no | +| [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, polkit, ... | no | - | no | +| [sd-messages.h API](https://www.freedesktop.org/software/systemd/man/sd-messages.html) | Header Library | yes | yes | - | yes | python-systemd | yes | +| [sd-path.h API](https://www.freedesktop.org/software/systemd/man/sd-path.html) | C Library | yes | no | - | maybe | - | maybe | | [$XDG_RUNTIME_DIR](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) | Environment | yes | yes | glib, GNOME | yes | - | no | | [$LISTEN_FDS $LISTEN_PID FD Passing](https://www.freedesktop.org/software/systemd/man/sd_listen_fds.html) | Environment | yes | yes | numerous (via sd-daemon.h) | yes | - | no | | [$NOTIFY_SOCKET Daemon Notifications](https://www.freedesktop.org/software/systemd/man/sd_notify.html) | Environment | yes | yes | a few, including udev | yes | - | no |