diff options
| -rw-r--r-- | README | 40 | ||||
| -rw-r--r-- | docs/PORTABILITY_AND_STABILITY.md | 11 | ||||
| -rw-r--r-- | man/libsystemd.xml | 89 | ||||
| -rw-r--r-- | man/rules/meson.build | 2 | ||||
| -rw-r--r-- | man/sd-bus-errors.xml | 1 | ||||
| -rw-r--r-- | man/sd-bus.xml | 7 | ||||
| -rw-r--r-- | man/sd-daemon.xml | 9 | ||||
| -rw-r--r-- | man/sd-device.xml | 6 | ||||
| -rw-r--r-- | man/sd-event.xml | 5 | ||||
| -rw-r--r-- | man/sd-hwdb.xml | 6 | ||||
| -rw-r--r-- | man/sd-id128.xml | 12 | ||||
| -rw-r--r-- | man/sd-journal.xml | 5 | ||||
| -rw-r--r-- | man/sd-login.xml | 7 |
13 files changed, 173 insertions, 27 deletions
@@ -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-<suffix>.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-<suffix>.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 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 | 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="libsystemd" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>libsystemd</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>libsystemd</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>libsystemd</refname> + <refpurpose>Functions for implementing services and interacting with systemd</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +#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> + </programlisting> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>libsystemd</filename> library provides functions that allow interacting with various + interfaces provided by the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> service + manager, as well as various other functions and constants useful for implementing services in + general.</para> + + <para>See + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-device</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + and + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for information about different parts of the library interface.</para> + </refsect1> + + <refsect1> + <title>Interface stability</title> + + <para>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. + </para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>libudev</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <ulink url="https://systemd.io/PORTABILITY_AND_STABILITY/">Interface Portability and Stability Promise</ulink> + </para> + </refsect1> + +</refentry> diff --git a/man/rules/meson.build b/man/rules/meson.build index 13d2bd9b58..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', [], ''], @@ -807,6 +808,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'], 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 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 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 @@ <refsect1> <title>Description</title> - <para><filename>sd-bus.h</filename> provides an implementation of a D-Bus IPC client. See + <para><filename>sd-bus.h</filename> is part of + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and + provides an implementation of a D-Bus IPC client. See <ulink url="https://www.freedesktop.org/software/dbus/" /> - for more information about D-Bus IPC. - </para> + for more information about D-Bus IPC.</para> <para>See <literallayout><citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 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 @@ <refsect1> <title>Description</title> - <para><filename>sd-daemon.h</filename> provides APIs for new-style - daemons, as implemented by the - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - service manager.</para> + <para><filename>sd-daemon.h</filename> is part of + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and + provides APIs for new-style daemons, as implemented by the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> service + manager.</para> <para>See <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 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 @@ <refsect1> <title>Description</title> - <para><filename>sd-device.h</filename> 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 + <para><filename>sd-device.h</filename> is part of + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> 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 <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This API is a replacement for <citerefentry><refentrytitle>libudev</refentrytitle><manvolnum>3</manvolnum></citerefentry> 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 @@ <refsect1> <title>Description</title> - <para><filename>sd-event.h</filename> provides a generic event - loop implementation, based on Linux <citerefentry + <para><filename>sd-event.h</filename> is part of + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and + provides a generic event loop implementation, based on Linux <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. </para> 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 @@ <refsect1> <title>Description</title> - <para><filename>sd-hwdb.h</filename> allows read-only access the systemd database of hardware properties. - See <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> and + <para><filename>sd-hwdb.h</filename> is part of + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and allows + read-only access the systemd database of hardware properties. See + <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> and <citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum></citerefentry> for more information about the database.</para> 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 @@ <refsect1> <title>Description</title> - <para><filename>sd-id128.h</filename> 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 <ulink url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink> 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. + <para><filename>sd-id128.h</filename> is part of + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> 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 <ulink + url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink> 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. </para> <para>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 @@ <refsect1> <title>Description</title> - <para><filename>sd-journal.h</filename> provides APIs to submit - and query log entries. The APIs exposed act both as client for the + <para><filename>sd-journal.h</filename> is part of + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and + provides APIs to submit and query log entries. The APIs exposed act both as client for the <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> journal service and as parser for the journal files on disk. </para> 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 @@ <refsect1> <title>Description</title> - <para><filename>sd-login.h</filename> provides APIs to introspect - and monitor seat, login session and user status information on the - local system. </para> + <para><filename>sd-login.h</filename> is part of + <citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and + provides APIs to introspect and monitor seat, login session, and user status information on the local + system.</para> <para>Note that these APIs only allow purely passive access and monitoring of seats, sessions and users. To actively make changes |