From 2b18106e03096fec69dbd821a126241981a1febd Mon Sep 17 00:00:00 2001 From: Sven Eden Date: Wed, 14 Jun 2017 17:42:55 +0200 Subject: [PATCH] Prep v231: Update man pages to include upstream changes --- man/custom-html.xsl | 4 +- man/loginctl.xml | 46 ++++++++++++-- man/sd_event_add_io.xml | 94 ++++++++++++++--------------- man/sd_event_now.xml | 35 ++++++----- man/sd_event_source_get_pending.xml | 2 +- man/sd_get_seats.xml | 2 +- man/sd_machine_get_class.xml | 2 +- man/sd_notify.xml | 56 +++++++++++++---- man/sd_seat_get_active.xml | 4 +- man/sd_session_is_active.xml | 4 +- man/sd_watchdog_enabled.xml | 26 +++----- man/standard-conf.xml | 4 +- 12 files changed, 169 insertions(+), 110 deletions(-) diff --git a/man/custom-html.xsl b/man/custom-html.xsl index 545f4b306..f1271dcb1 100644 --- a/man/custom-html.xsl +++ b/man/custom-html.xsl @@ -126,7 +126,7 @@ diff --git a/man/loginctl.xml b/man/loginctl.xml index fd2f15c0a..46f1a990f 100644 --- a/man/loginctl.xml +++ b/man/loginctl.xml @@ -196,9 +196,9 @@ activate ID Activate a session. This brings a session into - the foreground, if another session is currently in the + the foreground if another session is currently in the foreground on the respective seat. Takes a session identifier - as argument. If no argument is specified the session of the + as argument. If no argument is specified, the session of the caller is put into foreground. @@ -209,7 +209,7 @@ Activates/deactivates the screen lock on one or more sessions, if the session supports it. Takes one or more session identifiers as arguments. If no argument is - specified the session of the caller is locked/unlocked. + specified, the session of the caller is locked/unlocked. @@ -284,8 +284,11 @@ spawned for the user at boot and kept around after logouts. This allows users who are not logged in to run long-running services. Takes one or more user names or numeric UIDs as - argument. If no argument is specified enables/disables - lingering for the user of the session of the caller. + argument. If no argument is specified, enables/disables + lingering for the user of the session of the caller. + + See also KillUserProcesses= setting in + logind.conf5. @@ -348,7 +351,7 @@ seat. The devices should be specified via device paths in the /sys file system. To create a new seat, attach at least one graphics card to a previously unused seat - name. Seat names may consist only of a-z, A-Z, 0-9, + name. Seat names may consist only of a–z, A–Z, 0–9, - and _ and must be prefixed with seat. To drop assignment of a device to a specific seat, just reassign it to a different @@ -436,6 +439,37 @@ otherwise. + + Examples + + + Querying user status + + $ loginctl user-status +fatima (1005) + Since: Sat 2016-04-09 14:23:31 EDT; 54min ago + State: active + Sessions: 5 *3 + Unit: user-1005.slice + ├─user@1005.service + ... + ├─session-3.scope + ... + └─session-5.scope + ├─3473 login -- fatima + └─3515 -zsh + +Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session): + session opened for user fatima by LOGIN(uid=0) +Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima + + + There are two sessions, 3 and 5. Session 3 is a graphical session, + marked with a star. The tree of processing including the two corresponding + scope units and the user manager unit are shown. + + + diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml index 5c363f96b..3ba7c3bd3 100644 --- a/man/sd_event_add_io.xml +++ b/man/sd_event_add_io.xml @@ -120,36 +120,35 @@ returned in the source parameter. The fd parameter takes the UNIX file descriptor to watch, which may refer to a socket, a FIFO, a message queue, a - serial connection, a character device or any other file descriptor - compatible with Linux epoll7. The - events parameter takes a bit mask of I/O - events to watch the file descriptor for, a combination of the - following event flags: EPOLLIN, - EPOLLOUT, EPOLLRDHUP, - EPOLLPRI and EPOLLET, - see epoll_ctl2 + serial connection, a character device, or any other file descriptor + compatible with Linux + epoll7. The + events parameter takes a bit mask of events + to watch for, a combination of the following event flags: + EPOLLIN, EPOLLOUT, + EPOLLRDHUP, EPOLLPRI, + and EPOLLET, see + epoll_ctl2 for details. The handler shall reference a - function to call when the I/O event source is triggered. The - handler function will be passed the - userdata pointer, which may be chosen - freely by the caller. The handler will also be passed the file - descriptor the event was seen on as well as the actual event flags - seen. It's generally a subset of the events watched, however may - additionally have EPOLLERR and - EPOLLHUP set. - - By default, the I/O event source will stay enabled + function to call when the event source is triggered. The + userdata pointer will be passed to the + handler function, and may be chosen freely by the caller. The + handler will also be passed the file descriptor the event was seen + on, as well as the actual event flags. It's generally a subset of + the events watched, however may additionally include + EPOLLERR and EPOLLHUP. + + + By default, an event source will stay enabled continuously (SD_EVENT_ON), but this may be changed with sd_event_source_set_enabled3. If the handler function returns a negative error code, it will be disabled after the invocation, even if the SD_EVENT_ON mode was requested before. Note - that an I/O event source set to SD_EVENT_ON will - fire continuously unless data is read or written to the file - descriptor in order to reset the mask of events seen. + that an event source set to SD_EVENT_ON will + fire continuously unless data is read from or written to the file + descriptor to reset the mask of events seen. Setting the I/O event mask to watch for to 0 does not mean @@ -164,16 +163,17 @@ sd_event_source_unref3, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure - an event source does not fire anymore, even when there's still a - reference to it kept, consider setting the event source to - SD_EVENT_OFF with - sd_event_source_set_enabled3. + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. If the second parameter of - sd_event_add_io() is passed as NULL no - reference to the event source object is returned. In this case the - event source is considered "floating", and will be destroyed - implicitly when the event loop itself is destroyed. + sd_event_add_io() is + NULL no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed. It is recommended to use sd_event_add_io() only in conjunction with @@ -181,24 +181,24 @@ ensure that all I/O operations from invoked handlers are properly asynchronous and non-blocking. Using file descriptors without O_NONBLOCK might result in unexpected - starving of other event sources. See fcntl2 + starvation of other event sources. See + fcntl2 for details on enabling O_NONBLOCK mode. sd_event_source_get_io_events() retrieves - the configured I/O event mask to watch of an I/O event source created + the configured mask of watched I/O events of an event source created previously with sd_event_add_io(). It takes the event source object and a pointer to a variable to store the - event mask in. + mask in. - sd_event_source_set_io_events() changes the - configured I/O event mask to watch of an I/O event source created previously - with sd_event_add_io(). It takes the event - source object and the new event mask to set. + sd_event_source_set_io_events() + configures the mask of watched I/O events of an event source created + previously with sd_event_add_io(). It takes the + event source object and the new event mask. - sd_event_source_get_io_events() + sd_event_source_get_io_revents() retrieves the I/O event mask of currently seen but undispatched - events from an I/O event source created previously with + events from an event source created previously with sd_event_add_io(). It takes the event source object and a pointer to a variable to store the event mask in. When called from a handler function on the handler's event @@ -214,15 +214,15 @@ source types, the latter only to I/O event sources. sd_event_source_get_io_fd() retrieves - the UNIX file descriptor of an I/O event source created previously + the UNIX file descriptor of an event source created previously with sd_event_add_io(). It takes the event - source object and returns the positive file descriptor in the return - value, or a negative error number on error (see below). + source object and returns the non-negative file descriptor + or a negative error number on error (see below). sd_event_source_set_io_fd() changes the UNIX file descriptor of an I/O event source created previously with sd_event_add_io(). It takes - the event source object and the new file descriptor to set. + the event source object and the new file descriptor. @@ -230,13 +230,13 @@ On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error - code. + code. Errors - Returned errors may indicate the following problems: + Returned values may indicate the following problems: diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml index 219e261fd..b419e7d82 100644 --- a/man/sd_event_now.xml +++ b/man/sd_event_now.xml @@ -65,45 +65,44 @@ Description - sd_event_now() returns the timestamp - the most recent event loop iteration began. This timestamp is - taken right after returning from the event sleep, and before + sd_event_now() returns the time when + the most recent event loop iteration began. A timestamp + is taken right after returning from the event sleep, and before dispatching any event sources. The event - parameter takes the even loop object to retrieve the timestamp + parameter specifies the event loop object to retrieve the timestamp from. The clock parameter specifies the clock to retrieve the timestamp for, and is one of - CLOCK_REALTIME (or its equivalent + CLOCK_REALTIME (or equivalently CLOCK_REALTIME_ALARM), - CLOCK_MONOTONIC or - CLOCK_BOOTTIME (or its equivalent - CLOCK_BOOTTIME_ALARM), see clock_gettime2 + CLOCK_MONOTONIC, or + CLOCK_BOOTTIME (or equivalently + CLOCK_BOOTTIME_ALARM), see + clock_gettime2 for more information on the various clocks. The retrieved timestamp is stored in the usec parameter, in µs since the clock's epoch. If this function is invoked before - the first event loop iteration the current time is returned, as + the first event loop iteration, the current time is returned, as reported by clock_gettime(). To distinguish this case from a regular invocation the return value will be - positive non-zero in this case, while it is zero when the returned - timestamp refers to the actual event loop iteration. + positive, and zero when the returned timestamp refers to an actual + event loop iteration. Return Value If the first event loop iteration has not run yet - sd_event_now() returns the requested - timestamp in usec and returns a positive, - non-zero return value. Otherwise, on success it will return the - iteration's timestamp in usec and 0 as - return value. On failure, the call returns a negative errno-style + sd_event_now() writes current time to + usec and returns a positive return value. + Otherwise, it will write the requested timestamp to usec + and return 0. On failure, the call returns a negative errno-style error code. Errors - Returned errors may indicate the following problems: + Returned values may indicate the following problems: diff --git a/man/sd_event_source_get_pending.xml b/man/sd_event_source_get_pending.xml index 1339d5046..ea3c21db8 100644 --- a/man/sd_event_source_get_pending.xml +++ b/man/sd_event_source_get_pending.xml @@ -87,7 +87,7 @@ For I/O event sources, as created with sd_event_add_io3, the call - sd_event_get_io_revents3 + sd_event_source_get_io_revents3 may be used to query the type of event pending in more detail. diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml index a6c5e8947..963213797 100644 --- a/man/sd_get_seats.xml +++ b/man/sd_get_seats.xml @@ -127,7 +127,7 @@ -EINVAL An input parameter was invalid (out of range, - or NULL, where that's not accepted). + or NULL, where that is not accepted). diff --git a/man/sd_machine_get_class.xml b/man/sd_machine_get_class.xml index 4a3f513f6..be872eac8 100644 --- a/man/sd_machine_get_class.xml +++ b/man/sd_machine_get_class.xml @@ -116,7 +116,7 @@ -EINVAL An input parameter was invalid (out of range, - or NULL, where that's not accepted). + or NULL, where that is not accepted). diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 2345aea4b..03efe0193 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -1,4 +1,4 @@ - + @@ -100,7 +100,7 @@ sd_notify() may be called by a service to notify the service manager about state changes. It can be used to send arbitrary information, encoded in an - environment-block-like string. Most importantly it can be used for + environment-block-like string. Most importantly, it can be used for start-up completion notification. If the unset_environment parameter is @@ -158,7 +158,7 @@ to the service manager that describes the service state. This is free-form and can be used for various purposes: general state feedback, fsck-like programs could pass completion - percentages and failing programs could pass a human readable + percentages and failing programs could pass a human-readable error message. Example: STATUS=Completed 66% of file system check... @@ -194,7 +194,7 @@ watchdog timestamp. This is the keep-alive ping that services need to issue in regular intervals if WatchdogSec= is enabled for it. See - logind.service5 + systemd.service5 for information how to enable this functionality and sd_watchdog_enabled3 for the details of how the service can check whether the @@ -219,7 +219,7 @@ manager will accept messages for a service only if FileDescriptorStoreMax= is set to non-zero for it (defaults to zero). See - logind.service5 + systemd.service5 for details. Multiple arrays of file descriptors may be sent in separate messages, in which case the arrays are combined. Note that the service manager removes duplicate file @@ -229,6 +229,36 @@ below. + + FDNAME=... + + When used in combination with + FDSTORE=1, specifies a name for the + submitted file descriptors. This name is passed to the service + during activation, and may be queried using + sd_listen_fds_with_names3. File + descriptors submitted without this field set, will implicitly + get the name stored assigned. Note that, if + multiple file descriptors are submitted at once, the specified + name will be assigned to all of them. In order to assign + different names to submitted file descriptors, submit them in + separate invocations of + sd_pid_notify_with_fds(). The name may + consist of any ASCII character, but must not contain control + characters or :. It may not be longer than + 255 characters. If a submitted name does not follow these + restrictions, it is ignored. + + + + WATCHDOG_USEC=... + + Reset watchdog_usec value during runtime. + Notice that this is not available when using sd_event_set_watchdog() + or sd_watchdog_enabled(). + Example : WATCHDOG_USEC=20000000 + + It is recommended to prefix variable names that are not @@ -238,7 +268,7 @@ Note that elogind will accept status data sent from a service only if the NotifyAccess= option is correctly set in the service definition file. See - logind.service5 + systemd.service5 for details. sd_notifyf() is similar to @@ -253,7 +283,7 @@ use as originating PID for the message as first argument. This is useful to send notification messages on behalf of other processes, provided the appropriate privileges are available. If the PID - argument is specified as 0 the process ID of the calling process + argument is specified as 0, the process ID of the calling process is used, in which case the calls are fully equivalent to sd_notify() and sd_notifyf(). @@ -356,20 +386,22 @@ To store an open file descriptor in the service manager, in order to continue operation after a service restart without - losing state use FDSTORE=1: + losing state, use FDSTORE=1: - sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1); + sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1); See Also - elogind8, + systemd1, sd-daemon3, + sd_listen_fds3, + sd_listen_fds_with_names3, + sd_watchdog_enabled3, daemon7, - logind.service5, - sd_watchdog_enabled3 + systemd.service5 diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml index 4ae756a9a..b4d044282 100644 --- a/man/sd_seat_get_active.xml +++ b/man/sd_seat_get_active.xml @@ -158,7 +158,7 @@ -ENODATA - Given field is not specified for the described + The given field is not specified for the described seat. @@ -174,7 +174,7 @@ -EINVAL An input parameter was invalid (out of range, - or NULL, where that's not accepted). + or NULL, where that is not accepted). diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml index 11171473b..97721a56a 100644 --- a/man/sd_session_is_active.xml +++ b/man/sd_session_is_active.xml @@ -306,7 +306,7 @@ -ENODATA - Given field is not specified for the described + The given field is not specified for the described session. @@ -315,7 +315,7 @@ -EINVAL An input parameter was invalid (out of range, - or NULL, where that's not accepted). + or NULL, where that is not accepted). diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml index b9670e8bf..19401e6c0 100644 --- a/man/sd_watchdog_enabled.xml +++ b/man/sd_watchdog_enabled.xml @@ -96,8 +96,13 @@ To enable service supervision with the watchdog logic, use WatchdogSec= in service files. See - logind.service5 + systemd.service5 for details. + + Use + sd_event_set_watchdog3 + to enable automatic watchdog support in + sd-event3-based event loops. @@ -149,26 +154,15 @@ - - History - - The watchdog functionality and the - $WATCHDOG_USEC variable were added in - elogind-41. - - sd_watchdog_enabled() function was - added in elogind-209. Since that version the - $WATCHDOG_PID variable is also set. - - See Also - elogind8, + systemd1, sd-daemon3, daemon7, - logind.service5, - sd_notify3 + systemd.service5, + sd_notify3, + sd_event_set_watchdog3 diff --git a/man/standard-conf.xml b/man/standard-conf.xml index 15268030f..807702493 100644 --- a/man/standard-conf.xml +++ b/man/standard-conf.xml @@ -38,9 +38,9 @@ Configuration Directories and Precedence - Default configuration is defined during compilation, so a + The default configuration is defined during compilation, so a configuration file is only needed when it is necessary to deviate - from those defaults. By default the configuration file in + from those defaults. By default, the configuration file in /etc/elogind/ contains commented out entries showing the defaults as a guide to the administrator. This file can be edited to create local overrides. -- 2.30.2