Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 188 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man3/sd-login.3 b/upstream/opensuse-tumbleweed/man3/sd-login.3
new file mode 100644
index 00000000..47c7566a
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man3/sd-login.3
@@ -0,0 +1,188 @@
+'\" t
+.TH "SD\-LOGIN" "3" "" "systemd 254" "sd-login"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+sd-login \- APIs for tracking logins
+.SH "SYNOPSIS"
+.sp
+.ft B
+.nf
+#include <systemd/sd\-login\&.h>
+.fi
+.ft
+.HP \w'\fBpkg\-config\ \-\-cflags\ \-\-libs\ libsystemd\fR\ 'u
+\fBpkg\-config \-\-cflags \-\-libs libsystemd\fR
+.SH "DESCRIPTION"
+.PP
+sd\-login\&.h
+is part of
+\fBlibsystemd\fR(3)
+and provides APIs to introspect and monitor seat, login session, and user status information on the local system\&.
+.PP
+Note that these APIs only allow purely passive access and monitoring of seats, sessions and users\&. To actively make changes to the seat configuration, terminate login sessions, or switch session on a seat you need to utilize the D\-Bus API of systemd\-logind, instead\&.
+.PP
+These functions synchronously access data in
+/proc/,
+/sys/fs/cgroup/
+and
+/run/\&. All of these are virtual file systems, hence the runtime cost of the accesses is relatively cheap\&.
+.PP
+It is possible (and often a very good choice) to mix calls to the synchronous interface of
+sd\-login\&.h
+with the asynchronous D\-Bus interface of systemd\-logind\&. However, if this is done you need to think a bit about possible races since the stream of events from D\-Bus and from
+sd\-login\&.h
+interfaces such as the login monitor are asynchronous and not ordered against each other\&.
+.PP
+If the functions return string arrays, these are generally
+\fBNULL\fR
+terminated and need to be freed by the caller with the libc
+\fBfree\fR(3)
+call after use, including the strings referenced therein\&. Similarly, individual strings returned need to be freed, as well\&.
+.PP
+As a special exception, instead of an empty string array
+\fBNULL\fR
+may be returned, which should be treated equivalent to an empty string array\&.
+.PP
+See
+\fBsd_pid_get_session\fR(3),
+\fBsd_uid_get_state\fR(3),
+\fBsd_session_is_active\fR(3),
+\fBsd_seat_get_active\fR(3),
+\fBsd_get_seats\fR(3),
+\fBsd_login_monitor_new\fR(3)
+for more information about the functions implemented\&.
+.SH "DEFINITION OF TERMS"
+.PP
+seat
+.RS 4
+A seat consists of all hardware devices assigned to a specific workplace\&. It consists of at least one graphics device, and usually also includes keyboard, mouse\&. It can also include video cameras, sound cards and more\&. Seats are identified by seat names, which are strings (<= 255 characters), that start with the four characters
+"seat"
+followed by at least one character from the range [a\-zA\-Z0\-9],
+"_"
+and
+"\-"\&. They are suitable for use as file names\&. Seat names may or may not be stable and may be reused if a seat becomes available again\&.
+.RE
+.PP
+session
+.RS 4
+A session is defined by the time a user is logged in until they log out\&. A session is bound to one or no seats (the latter for \*(Aqvirtual\*(Aq ssh logins)\&. Multiple sessions can be attached to the same seat, but only one of them can be active, the others are in the background\&. A session is identified by a short string\&.
+.sp
+\fBsystemd\fR(1)
+ensures that audit sessions are identical to systemd sessions, and uses the audit session ID as session ID in systemd (if auditing is enabled)\&. In general the session identifier is a short string consisting only of [a\-zA\-Z0\-9],
+"_"
+and
+"\-", suitable for use as a file name\&. Session IDs are unique on the local machine and are never reused as long as the machine is online\&. A user (the way we know it on UNIX) corresponds to the person using a computer\&. A single user can have multiple sessions open at the same time\&. A user is identified by a numeric user id (UID) or a user name (a string)\&. A multi\-session system allows multiple user sessions on the same seat at the same time\&. A multi\-seat system allows multiple independent seats that can be individually and simultaneously used by different users\&.
+.RE
+.PP
+All hardware devices that are eligible to being assigned to a seat, are assigned to one\&. A device can be assigned to only one seat at a time\&. If a device is not assigned to any particular other seat it is implicitly assigned to the special default seat called
+"seat0"\&.
+.PP
+Note that hardware like printers, hard disks or network cards is generally not assigned to a specific seat\&. They are available to all seats equally\&. (Well, with one exception: USB sticks can be assigned to a seat\&.)
+.PP
+"seat0"
+always exists\&.
+.SH "UDEV RULES"
+.PP
+Assignment of hardware devices to seats is managed inside the udev database, via settings on the devices:
+.PP
+Tag "seat"
+.RS 4
+When set, a device is eligible to be assigned to a seat\&. This tag is set for graphics devices, mice, keyboards, video cards, sound cards and more\&. Note that some devices like sound cards consist of multiple subdevices (i\&.e\&. a PCM for input and another one for output)\&. This tag will be set only for the originating device, not for the individual subdevices\&. A UI for configuring assignment of devices to seats should enumerate and subscribe to all devices with this tag set and show them in the UI\&. Note that USB hubs can be assigned to a seat as well, in which case all (current and future) devices plugged into it will also be assigned to the same seat (unless they are explicitly assigned to another seat)\&.
+.RE
+.PP
+Tag "master\-of\-seat"
+.RS 4
+When set, this device is enough for a seat to be considered existent\&. This tag is usually set for the framebuffer device of graphics cards\&. A seat hence consists of an arbitrary number of devices marked with the
+"seat"
+tag, but (at least) one of these devices needs to be tagged with
+"master\-of\-seat"
+before the seat is actually considered to be around\&.
+.RE
+.PP
+Property \fIID_SEAT\fR
+.RS 4
+This property specifies the name of the seat a specific device is assigned to\&. If not set the device is assigned to
+"seat0"\&. Also, to speed up enumeration of hardware belonging to a specific seat, the seat is also set as tag on the device\&. I\&.e\&. if the property
+\fIID_SEAT=seat\-waldo\fR
+is set for a device, the tag
+"seat\-waldo"
+will be set as well\&. Note that if a device is assigned to
+"seat0", it will usually not carry such a tag and you need to enumerate all devices and check the
+\fIID_SEAT\fR
+property manually\&. Again, if a device is assigned to seat0 this is visible on the device in two ways: with a property
+\fIID_SEAT=seat0\fR
+and with no property
+\fIID_SEAT\fR
+set for it at all\&.
+.RE
+.PP
+Property \fIID_AUTOSEAT\fR
+.RS 4
+When set to
+"1", this device automatically generates a new and independent seat, which is named after the path of the device\&. This is set for specialized USB hubs like the Pluggable devices, which when plugged in should create a hotplug seat without further configuration\&.
+.RE
+.PP
+Property \fIID_FOR_SEAT\fR
+.RS 4
+When creating additional (manual) seats starting from a graphics device this is a good choice to name the seat after\&. It is created from the path of the device\&. This is useful in UIs for configuring seats: as soon as you create a new seat from a graphics device, read this property and prefix it with
+"seat\-"
+and use it as name for the seat\&.
+.RE
+.PP
+A seat exists only and exclusively because a properly tagged device with the right
+\fIID_SEAT\fR
+property exists\&. Besides udev rules there is no persistent data about seats stored on disk\&.
+.PP
+Note that
+\fBsystemd-logind\fR(8)
+manages ACLs on a number of device classes, to allow user code to access the device nodes attached to a seat as long as the user has an active session on it\&. This is mostly transparent to applications\&. As mentioned above, for certain user software it might be a good idea to watch whether they can access device nodes instead of thinking about seats\&.
+.SH "NOTES"
+.PP
+Functions described here are available as a shared library, which can be compiled against and linked to with the
+\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
+file\&.
+.PP
+The code described here uses
+\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
+\fBsetenv\fR(3)
+from a parallel thread\&. It is recommended to only do calls to
+\fBsetenv()\fR
+from an early phase of the program when no other threads have been started\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsd_pid_get_session\fR(3),
+\fBsd_uid_get_state\fR(3),
+\fBsd_session_is_active\fR(3),
+\fBsd_seat_get_active\fR(3),
+\fBsd_get_seats\fR(3),
+\fBsd_login_monitor_new\fR(3),
+\fBsd-daemon\fR(3),
+\fBpkg-config\fR(1)
+.PP
+\m[blue]\fBMulti\-Seat on Linux\fR\m[]\&\s-2\u[1]\d\s+2
+may also be of historical interest\&.
+.SH "NOTES"
+.IP " 1." 4
+Multi-Seat on Linux
+.RS 4
+\%https://www.freedesktop.org/wiki/Software/systemd/multiseat
+.RE