mirror of
https://github.com/morgan9e/systemd
synced 2026-04-15 08:56:15 +09:00
Merge pull request #27652 from keszybz/readme-more
Add man page for libsystemd, extend readme and stability promise
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
40
README
40
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-<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
|
||||
|
||||
@@ -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 |
|
||||
|
||||
89
man/libsystemd.xml
Normal file
89
man/libsystemd.xml
Normal file
@@ -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>
|
||||
@@ -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'],
|
||||
|
||||
@@ -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>,
|
||||
|
||||
@@ -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>,
|
||||
|
||||
@@ -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>,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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>
|
||||
|
||||
|
||||
@@ -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>
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user