From 0b3b020a178cf3b957fed627de13c895773995ec Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 19 Dec 2011 03:02:17 +0100 Subject: man: document the sd-login interfaces --- man/sd_get_seats.xml | 125 +++++++++++++++++++++++++++++ man/sd_login_monitor_new.xml | 172 ++++++++++++++++++++++++++++++++++++++++ man/sd_pid_get_session.xml | 136 ++++++++++++++++++++++++++++++++ man/sd_seat_get_active.xml | 150 +++++++++++++++++++++++++++++++++++ man/sd_session_is_active.xml | 134 +++++++++++++++++++++++++++++++ man/sd_uid_get_state.xml | 182 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 899 insertions(+) create mode 100644 man/sd_get_seats.xml create mode 100644 man/sd_login_monitor_new.xml create mode 100644 man/sd_pid_get_session.xml create mode 100644 man/sd_seat_get_active.xml create mode 100644 man/sd_session_is_active.xml create mode 100644 man/sd_uid_get_state.xml (limited to 'man') diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml new file mode 100644 index 0000000000..bbc396a09b --- /dev/null +++ b/man/sd_get_seats.xml @@ -0,0 +1,125 @@ + + + + + + + + + sd_get_seats + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_get_seats + 3 + + + + sd_get_seats + sd_get_sessions + sd_get_uids + Determine available seats, sessions and logged in users + + + + + #include <systemd/sd-login.h> + + + int sd_get_seats + char*** seats + + + + int sd_get_sessions + char*** sessions + + + + int sd_get_uids + char*** sessions + + + + + + + Description + + sd_get_seats() may be used + to determine all currently available local + seats. Returns an array of seat identifiers. The + returned array and all strings it references need to + be freed with the libc + free3 + call after use. + + Similar, sd_get_sessions() may + be used to determine all current login sessions. + + Similar, sd_get_uids() may + be used to determine all Unix users who currently have login sessions. + + + + Return Value + + On success sd_get_seats(), + sd_get_sessions() and + sd_get_uids() return the number + of entries in the arrays. On failure, these calls + return a negative errno-style error code. + + + + Notes + + The sd_get_seats(), + sd_get_sessions() and + sd_get_uids() interfaces + are available as shared library, which can be compiled + and linked to with the + libsystemd-login + pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login7, + sd_session_get_seat3, + + + + diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml new file mode 100644 index 0000000000..2b37f00d30 --- /dev/null +++ b/man/sd_login_monitor_new.xml @@ -0,0 +1,172 @@ + + + + + + + + + sd_login_monitor_new + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_login_monitor_new + 3 + + + + sd_login_monitor_new + sd_login_monitor_unref + sd_login_monitor_flush + sd_login_monitor_get_fd + Monitor login sessions, seats and users + + + + + #include <systemd/sd-login.h> + + + int sd_login_monitor_new + const char* category + sd_login_monitor** ret + + + + sd_login_monitor* sd_login_monitor_unref + sd_login_monitor* m + + + + int sd_login_monitor_flush + sd_login_monitor* m + + + + int sd_login_monitor_get_fd + sd_login_monitor* m + + + + + + + Description + + sd_login_monitor_new() may + be used to monitor login session, users and seats. Via + a monitor object a file descriptor can be integrated + into an application defined event loop which is woken + up each time a user logs in, logs out or a seat is + added or removed, or a session, user, or seat changes + state otherwise. The first parameter takes a string + which can be either seat (to get + only notifications about seats being added, removed or + changed), session (to get only + notifications about sessions being created or removed + or changed) or uid (to get only + notifications when a user changes state in respect to + logins). If notifications shall be generated in all + these conditions, NULL may be passed. Note that in + future additional categories may be defined. The + second parameter returns a monitor object and needs to + be freed with the + sd_login_monitor_unref() call + after use. + + sd_login_monitor_unref() + may be used to destroy a monitor object. Note that + this will invalidate any file descriptor returned by + sd_login_monitor_get_fd(). + + sd_login_monitor_flush() + may be used to reset the wakeup state of the monitor + object. Whenever an event causes the monitor to wake + up the event loop via the file descriptor this + function needs to be called to reset the wake-up + state. If this call is not invoked the file descriptor + will immediately wake up the event loop again. + + sd_login_monitor_get_fd() + may be used to retrieve the file descriptor of the + monitor object that may be integrated in an + application defined event loop, based around + poll2 + or a similar interface. The application should include + the returned file descriptor as wake up source for + POLLIN events. Whenever a wake-up is triggered the + file descriptor needs to be reset via + sd_login_monitor_flush(). An + application needs to reread the login state with a + function like + sd_get_seats3 + or similar to determine what changed. + + + + Return Value + + On success + sd_login_monitor_new() and + sd_login_monitor_flush() return 0 + or a positive integer. On success + sd_login_monitor_get_fd() returns + a Unix file descriptor. On failure, these calls return + a negative errno-style error code. + + sd_login_monitor_unref() + always returns NULL. + + + + Notes + + The sd_login_monitor_new(), + sd_login_monitor_unref(), sd_login_monitor_flush() and + sd_login_monitor_get_fd() interfaces + are available as shared library, which can be compiled + and linked to with the + libsystemd-login + pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login7, + sd_get_seats3, + + + + diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml new file mode 100644 index 0000000000..9176433c3d --- /dev/null +++ b/man/sd_pid_get_session.xml @@ -0,0 +1,136 @@ + + + + + + + + + sd_pid_get_session + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_pid_get_session + 3 + + + + sd_pid_get_session + sd_pid_get_owner_uid + Determine session or owner of a session of a specific PID + + + + + #include <systemd/sd-login.h> + + + int sd_pid_get_session + pid_t pid + char** session + + + + int sd_pid_get_owner_uid + pid_t pid + uid_t* uid + + + + + + Description + + sd_pid_get_session() may be + used to determine the login session identifier of a + process identified by the specified process identifier. The session + identifier is a short string (up to 64 characters), + consisting only of the characters a-zA-Z0-9 as well as + '-' and '_'. It is suitable for usage in file system + paths. Note that not all processes are part of a login + session (e.g. system service processes and user + processes that are shared between multiple sessions of + the same user). For processes not being part of a + login session this function will fail. The returned + string needs to be freed with the libc + free3 + call after use. + + sd_pid_get_owner_uid() may + be used to determine the Unix user identifier of the + owner of the session of a process identified the + specified PID. Note that this function will succeed + for user processes which are shared between multiple + login sessions of the same user, where + sd_pid_get_session() will + fail. For processes not being part of a login session + and not being a shared process of a user this function + will fail. + + + + Return Value + + On success these calls return 0 or a positive + integer. On failure, these calls return a negative + errno-style error code. + + + + Notes + + The sd_pid_get_session() + and sd_pid_get_owner_uid() + interfaces are available as shared library, which can + be compiled and linked to with the + libsystemd-login + pkg-config1 + file. + + Note that the login session identifier as + returned by sd_pid_get_session() + is completely unrelated to the process session + identifier as returned by + getsid2. + + + + See Also + + + systemd1, + sd-login7, + sd_session_is_active3, + getsid2 + + + + diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml new file mode 100644 index 0000000000..e729a653b7 --- /dev/null +++ b/man/sd_seat_get_active.xml @@ -0,0 +1,150 @@ + + + + + + + + + sd_seat_get_active + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_seat_get_active + 3 + + + + sd_seat_get_active + sd_seat_get_sessions + sd_seat_can_multi_session + Determine state of a specific seat + + + + + #include <systemd/sd-login.h> + + + int sd_seat_get_active + const char* seat + char** session + uid_t* uid + + + + int sd_seat_get_sessions + const char* seat + char*** sessions + uid_t** uid + unsigned* n_uids + + + + int sd_seat_can_multi_session + const char* session + + + + + + Description + + sd_seat_get_active() may be + used to determine which session is currently active on + a seat, if there is any. Returns the session + identifier and the user identifier of the Unix user + the session is belonging to. Either the session or the + user identifier parameter can be be passed NULL, in + case only one of the parameters shall be queried. The + returned string needs to be freed with the libc + free3 + call after use. + + sd_seat_get_sessions() may + be used to determine all sessions on the specified + seat. Returns two arrays, one (NULL terminated) with + the session identifiers of the sessions and one with + the user identifiers of the Unix users the sessions + belong to. An additional parameter may be used to + return the number of entries in the latter array. The + two arrays and the latter parameter may be passed as + NULL in case these values need not to be + determined. The arrays and the strings referenced by + them need to be freed with the libc + free3 + call after use. + + sd_seat_can_multi_session() + may be used to determine whether a specific seat is + capable of multi-session, i.e. allows multiple login + sessions in parallel (whith only one being active at a + time). + + + + Return Value + + On success + sd_seat_get_active() return + return 0 or a positive integer. On success + sd_seat_get_sessions() returns + the number of entries in the session identifier + array. If the test succeeds + sd_seat_can_multi_session returns + a positive integer, if it fails 0. On failure, these + calls return a negative errno-style error code. + + + + Notes + + The sd_seat_get_active(), + sd_seat_get_sessions(), and + sd_seat_can_multi_session() interfaces + are available as shared library, which can be compiled + and linked to with the + libsystemd-login + pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login7, + sd_session_get_seat3, + + + + diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml new file mode 100644 index 0000000000..82919f84fb --- /dev/null +++ b/man/sd_session_is_active.xml @@ -0,0 +1,134 @@ + + + + + + + + + sd_session_is_active + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_session_is_active + 3 + + + + sd_session_is_active + sd_session_get_uid + sd_session_get_seat + Determine state of a specific session + + + + + #include <systemd/sd-login.h> + + + int sd_session_is_active + const char* session + + + + int sd_session_get_uid + const char* session + uid_t* uid + + + + int sd_session_get_seat + const char* session + char** seat + + + + + + Description + + sd_session_is_active() may + be used to determine whether the session identified by + the specified session identifier is currently active + (i.e. currently in the foreground and available for + user input) or not. + + sd_session_get_uid() may be + used to determine the user identifier of the Unix user the session + identified by the specified session identifier belongs + to. + + sd_session_get_seat() may + be used to determine the seat identifier of the seat + the session identified by the specified session + identifier belongs to. Note that not all sessions are + attached to a seat, this call will fail for them. The + returned string needs to be freed with the libc + free3 + call after use. + + + + Return Value + + If the test succeeds + sd_session_is_active() returns a + positive integer, if it fails 0. On success + sd_session_get_uid() and + sd_session_get_seat() return 0 or + a positive integer. On failure, these calls return a + negative errno-style error code. + + + + Notes + + The sd_session_is_active(), + sd_session_get_uid(), and + sd_session_get_seat() interfaces + are available as shared library, which can be compiled + and linked to with the + libsystemd-login + pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login7, + sd_pid_get_session3, + + + + diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml new file mode 100644 index 0000000000..a4e9e73087 --- /dev/null +++ b/man/sd_uid_get_state.xml @@ -0,0 +1,182 @@ + + + + + + + + + sd_uid_get_state + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_uid_get_state + 3 + + + + sd_uid_get_state + sd_uid_is_on_seat + sd_uid_get_sessions + sd_uid_get_seats + Determine login state of a specific Unix user ID + + + + + #include <systemd/sd-login.h> + + + int sd_uid_get_state + uid_t pid + char** state + + + + int sd_uid_is_on_seat + uid_t pid + int require_active + const char* seat + + + + int sd_uid_get_sessions + uid_t pid + int require_active + char*** sessions + + + + int sd_uid_get_seats + uid_t pid + int require_active + char*** seats + + + + + + Description + + sd_uid_get_state() may be + used to determine the login state of a specific Unix + user identifier. The following states are currently + known: offline (user not logged in + at all), lingering (user not logged + in, but some user services running), + online (user logged in, but not + active), active (user logged in on + an active seat). In the future additional states might + be defined, client code should be written to be robust + in regards to additional state strings being + returned. The returned string needs to be freed with + the libc + free3 + call after use. + + sd_uid_is_on_seat() may be + used to determine whether a specific user is logged in + or active on a specific seat. Accepts a Unix user + identifier and a seat identifier string as + parameters. The require_active + parameter is a boolean. If non-zero (true) this + function will test if the user is active (i.e. has a + session that is in the foreground and accepting user + input) on the specified seat, otherwise (false) only + if the user is logged in (and possibly inactive) on + the specified seat. + + sd_uid_get_sessions() may + be used to determine the current sessions of the + specified user. Acceptes a Unix user identifier as + parameter. The require_active + boolean parameter controls whether the returned list + shall consist of only those sessions where the user is + currently active (true) or where the user is currently + logged in at all, possibly inactive (false). The call + returns a NULL terminated string array of session + identifiers in sessions which + needs to be freed by the caller with the libc + free3 + call after use, including all the strings referenced. If + the string array parameter is passed as NULL the array + will not be filled in, but the return code still + indicates the number of current sessions. + + Similar, sd_uid_get_seats() + may be used to determine the list of seats on which + the user currently has sessions. Similar semantics + apply, however note that the user may have + multiple sessions on the same seat as well as sessions + with no attached seat and hence the number of entries + in the returned array may differ from the one returned + by sd_uid_get_sessions(). + + + + Return Value + + On success + sd_uid_get_state() returns 0 or a + positive integer. If the test succeeds + sd_uid_is_on_seat() returns a + positive integer, if it fails + 0. sd_uid_get_sessions() and + sd_uid_get_seats() return the + number of entries in the returned arrays. On failure, + these calls return a negative errno-style error + code. + + + + Notes + + The sd_uid_get_state(), + sd_uid_is_on_seat(), + sd_uid_get_sessions(), and + sd_uid_get_seats() interfaces are + available as shared library, which can be compiled and + linked to with the libsystemd-login + pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login7, + sd_pid_get_owner_uid3, + + + + -- cgit v1.2.3-54-g00ecf From a822cbfa2e42d60c3cafe724a8571329ab6c632e Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 19 Dec 2011 13:11:42 +0100 Subject: sd-daemon: fix #include lines since we now ship a shared library --- man/sd-daemon.xml | 2 +- man/sd_booted.xml | 2 +- man/sd_is_fifo.xml | 2 +- man/sd_listen_fds.xml | 2 +- man/sd_notify.xml | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) (limited to 'man') diff --git a/man/sd-daemon.xml b/man/sd-daemon.xml index cd67d9992a..383d77f595 100644 --- a/man/sd-daemon.xml +++ b/man/sd-daemon.xml @@ -50,7 +50,7 @@ - #include "sd-daemon.h" + #include <systemd/sd-daemon.h> diff --git a/man/sd_booted.xml b/man/sd_booted.xml index ebcde36b48..c9f538a3e6 100644 --- a/man/sd_booted.xml +++ b/man/sd_booted.xml @@ -49,7 +49,7 @@ - #include "sd-daemon.h" + #include <systemd/sd-daemon.h> int sd_booted diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml index f6fafabc39..82b89bb290 100644 --- a/man/sd_is_fifo.xml +++ b/man/sd_is_fifo.xml @@ -53,7 +53,7 @@ - #include "sd-daemon.h" + #include <systemd/sd-daemon.h> int sd_is_fifo diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 3276aff63d..68a45cd766 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -49,7 +49,7 @@ - #include "sd-daemon.h" + #include <systemd/sd-daemon.h> #define SD_LISTEN_FDS_START 3 diff --git a/man/sd_notify.xml b/man/sd_notify.xml index dd0ba935d6..1b55680748 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -50,7 +50,7 @@ - #include "sd-daemon.h" + #include <systemd/sd-daemon.h> int sd_notify -- cgit v1.2.3-54-g00ecf From 559de1289000f874e23ad01edfa1b37c102a793a Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 19 Dec 2011 13:19:01 +0100 Subject: man: sd_readahead is not actually available in libsystemd-daemon --- man/sd_readahead.xml | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) (limited to 'man') diff --git a/man/sd_readahead.xml b/man/sd_readahead.xml index 88b135b7ec..25fe5b2fc6 100644 --- a/man/sd_readahead.xml +++ b/man/sd_readahead.xml @@ -49,7 +49,7 @@ - #include "sd-daemon.h" + #include "sd-readahead.h" int sd_readahead @@ -134,23 +134,17 @@ url="http://cgit.freedesktop.org/systemd/tree/src/sd-readahead.h"/> sd_readahead() is - implemented in the reference implementation's + implemented in the reference implementation's drop-in sd-readahead.c and - sd-readahead.h files. These - interfaces are available as shared library, which can - be compiled and linked to with the - libsystemd-daemon - pkg-config1 - file. Alternatively, applications consuming this API - may copy the implementation into their source - tree. For more details about the reference - implementation see - sd-readahead7. - - If the reference implementation is used as - drop-in files and -DDISABLE_SYSTEMD is set during - compilation this function will always return 0 and - otherwise become a NOP. + sd-readahead.h files. It is + recommended that applications consuming this API copy + the implementation into their source tree. For more + details about the reference implementation see + sd-readahead7 + + If -DDISABLE_SYSTEMD is set during compilation + this function will always return 0 and otherwise + become a NOP. -- cgit v1.2.3-54-g00ecf From 01448ff92d9549785242ffab453bf5bcde348c61 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 19 Dec 2011 13:57:07 +0100 Subject: man: add sd-login(7) page --- Makefile.am | 31 ++++++++---- man/sd-login.xml | 117 +++++++++++++++++++++++++++++++++++++++++++++ man/sd_pid_get_session.xml | 19 ++++---- 3 files changed, 149 insertions(+), 18 deletions(-) create mode 100644 man/sd-login.xml (limited to 'man') diff --git a/Makefile.am b/Makefile.am index 907ecb4f7c..e689355cee 100644 --- a/Makefile.am +++ b/Makefile.am @@ -799,6 +799,7 @@ MANPAGES = \ man/daemon.7 \ man/sd-daemon.7 \ man/sd-readahead.7 \ + man/sd-login.7 \ man/runlevel.8 \ man/telinit.8 \ man/halt.8 \ @@ -817,7 +818,13 @@ MANPAGES = \ man/modules-load.d.5 \ man/sysctl.d.5 \ man/systemd-ask-password.1 \ - man/systemd-loginctl.1 + man/systemd-loginctl.1 \ + man/sd_pid_get_session.3 \ + man/sd_uid_get_state.3 \ + man/sd_session_is_active.3 \ + man/sd_seat_get_active.3 \ + man/sd_get_seats.3 \ + man/sd_login_monitor_new.3 if ENABLE_BINFMT MANPAGES += \ @@ -830,14 +837,22 @@ MANPAGES_ALIAS = \ man/sd_is_socket.3 \ man/sd_is_socket_unix.3 \ man/sd_is_socket_inet.3 \ + man/sd_is_mq.3 \ man/sd_notifyf.3 \ - man/sd_pid_get_session.3 \ - man/sd_uid_get_state.3 \ - man/sd_session_is_active.3 \ - man/sd_seat_get_active.3 \ - man/sd_get_seats.3 \ - man/sd_login_monitor_new.3 \ - man/init.1 + man/init.1 \ + man/sd_session_get_uid.3 \ + man/sd_session_get_seat.3 \ + man/sd_pid_get_owner_uid.3 \ + man/sd_uid_is_on_seat.3 \ + man/sd_uid_get_sessions.3 \ + man/sd_uid_get_seats.3 \ + man/sd_seat_get_sessions.3 \ + man/sd_seat_can_multi_session.3 \ + man/sd_get_sessions.3 \ + man/sd_get_uids.3 \ + man/sd_login_monitor_unref.3 \ + man/sd_login_monitor_flush.3 \ + man/sd_login_monitor_get_fd.3 man/reboot.8: man/halt.8 man/poweroff.8: man/halt.8 diff --git a/man/sd-login.xml b/man/sd-login.xml new file mode 100644 index 0000000000..62ec6ffefd --- /dev/null +++ b/man/sd-login.xml @@ -0,0 +1,117 @@ + + + + + + + + + sd-login + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-login + 7 + + + + sd-login + APIs for + tracking logins + + + + + #include <systemd/sd-login.h> + + + + pkg-config --cflags --libs libsystemd-login + + + + + Description + + sd-login.h provides APIs to + introspect and monitor seat, login session and user + status information on the local system. + + See Multi-Seat + on Linux for an introduction into multi-seat + support on Linux, the background for this set of APIs. + + 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. + + See + sd_pid_get_session3, + sd_uid_get_state3, + sd_session_is_active3, + sd_seat_get_active3, + sd_get_seats3, + sd_login_monitor_new3 + for more information about the functions + implemented. + + + + Notes + + These APIs are implemented as shared library, + which can be compiled and linked to with the + libsystemd-login + pkg-config1 + file. + + + + See Also + + systemd1, + sd_pid_get_session3, + sd_uid_get_state3, + sd_session_is_active3, + sd_seat_get_active3, + sd_get_seats3, + sd_login_monitor_new3, + sd-daemon7, + sd-readahead7, + pkg-config1 + + + + diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml index 9176433c3d..24e468015f 100644 --- a/man/sd_pid_get_session.xml +++ b/man/sd_pid_get_session.xml @@ -71,16 +71,15 @@ sd_pid_get_session() may be used to determine the login session identifier of a - process identified by the specified process identifier. The session - identifier is a short string (up to 64 characters), - consisting only of the characters a-zA-Z0-9 as well as - '-' and '_'. It is suitable for usage in file system - paths. Note that not all processes are part of a login - session (e.g. system service processes and user - processes that are shared between multiple sessions of - the same user). For processes not being part of a - login session this function will fail. The returned - string needs to be freed with the libc + process identified by the specified process + identifier. The session identifier is a short string, + suitable for usage in file system paths. Note that not + all processes are part of a login session (e.g. system + service processes and user processes that are shared + between multiple sessions of the same user). For + processes not being part of a login session this + function will fail. The returned string needs to be + freed with the libc free3 call after use. -- cgit v1.2.3-54-g00ecf From 595aae376fae21f885ec9af2cac1aaf3ff3e9bee Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 19 Dec 2011 14:42:59 +0100 Subject: man: various updates --- man/sd-login.xml | 21 ++++++++++++++++++++- man/sd_get_seats.xml | 12 +++++++----- man/sd_login_monitor_new.xml | 2 +- man/sd_seat_get_active.xml | 6 ++++-- man/sd_session_is_active.xml | 2 +- man/sd_uid_get_state.xml | 13 ++++++++----- 6 files changed, 41 insertions(+), 15 deletions(-) (limited to 'man') diff --git a/man/sd-login.xml b/man/sd-login.xml index 62ec6ffefd..9926d2b85c 100644 --- a/man/sd-login.xml +++ b/man/sd-login.xml @@ -75,7 +75,26 @@ 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. + systemd-logind, instead. + + These functions 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. + + If the functions return string arrays, these are + generally NULL terminated and need to be freed by the + caller with the libc + free3 + call after use, including the strings referenced + therein. Similar, individual strings returned need to + be freed, as well. + + As a special exception, instead of an empty + string array NULL may be returned, which should be + treated equivalent to an empty string array. See sd_pid_get_session3, diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml index bbc396a09b..2ac76500ec 100644 --- a/man/sd_get_seats.xml +++ b/man/sd_get_seats.xml @@ -76,11 +76,13 @@ sd_get_seats() may be used to determine all currently available local - seats. Returns an array of seat identifiers. The - returned array and all strings it references need to - be freed with the libc + seats. Returns a NULL terminated array of seat + identifiers. The returned array and all strings it + references need to be freed with the libc free3 - call after use. + call after use. Note that instead of an empty array + NULL may be returned and should be considered + equivalent to an empty array. Similar, sd_get_sessions() may be used to determine all current login sessions. @@ -118,7 +120,7 @@ systemd1, sd-login7, - sd_session_get_seat3, + sd_session_get_seat3 diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index 2b37f00d30..de484329a9 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -165,7 +165,7 @@ systemd1, sd-login7, - sd_get_seats3, + sd_get_seats3 diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml index e729a653b7..14cda60a56 100644 --- a/man/sd_seat_get_active.xml +++ b/man/sd_seat_get_active.xml @@ -101,7 +101,9 @@ determined. The arrays and the strings referenced by them need to be freed with the libc free3 - call after use. + call after use. Note that instead of an empty array + NULL may be returned and should be considered + equivalent to an empty array. sd_seat_can_multi_session() may be used to determine whether a specific seat is @@ -143,7 +145,7 @@ systemd1, sd-login7, - sd_session_get_seat3, + sd_session_get_seat3 diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml index 82919f84fb..88b22fd9f8 100644 --- a/man/sd_session_is_active.xml +++ b/man/sd_session_is_active.xml @@ -127,7 +127,7 @@ systemd1, sd-login7, - sd_pid_get_session3, + sd_pid_get_session3 diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml index a4e9e73087..67776257db 100644 --- a/man/sd_uid_get_state.xml +++ b/man/sd_uid_get_state.xml @@ -126,10 +126,13 @@ identifiers in sessions which needs to be freed by the caller with the libc free3 - call after use, including all the strings referenced. If - the string array parameter is passed as NULL the array - will not be filled in, but the return code still - indicates the number of current sessions. + call after use, including all the strings + referenced. If the string array parameter is passed as + NULL the array will not be filled in, but the return + code still indicates the number of current + sessions. Note that instead of an empty array NULL may + be returned and should be considered equivalent to an + empty array. Similar, sd_uid_get_seats() may be used to determine the list of seats on which @@ -175,7 +178,7 @@ systemd1, sd-login7, - sd_pid_get_owner_uid3, + sd_pid_get_owner_uid3 -- cgit v1.2.3-54-g00ecf From 5079a105e701f17439635e76d8cb3052badbb34c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 19 Dec 2011 17:40:31 +0100 Subject: man: extend sd-login(7) in regards to mixing D-Bus and synchronous library calls a bit --- man/sd-login.xml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'man') diff --git a/man/sd-login.xml b/man/sd-login.xml index 9926d2b85c..3fc0e16f69 100644 --- a/man/sd-login.xml +++ b/man/sd-login.xml @@ -77,13 +77,23 @@ you need to utilize the D-Bus API of systemd-logind, instead. - These functions access data in + 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. + 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. + If the functions return string arrays, these are generally NULL terminated and need to be freed by the caller with the libc -- cgit v1.2.3-54-g00ecf From 76318284fc970b30e9dc4c079960807345331dad Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 19 Dec 2011 20:25:52 +0100 Subject: man: switch to UTF-8 output, to work around charset issues --- Makefile.am | 9 +++++---- man/custom-html.xsl | 29 +++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 4 deletions(-) create mode 100644 man/custom-html.xsl (limited to 'man') diff --git a/Makefile.am b/Makefile.am index 656909c6c7..f9093b6d8e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -506,7 +506,8 @@ EXTRA_DIST = \ src/libsystemd-login.sym \ introspect.awk \ src/73-seat-late.rules.in \ - src/99-systemd.rules.in + src/99-systemd.rules.in \ + man/custom-html.xsl if ENABLE_BINFMT EXTRA_DIST += \ @@ -1758,7 +1759,7 @@ endif if HAVE_XSLTPROC XSLTPROC_FLAGS = \ --nonet \ - --param funcsynopsis.style "'ansi'" + --stringparam funcsynopsis.style ansi XSLTPROC_PROCESS_MAN = \ $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ @@ -1771,11 +1772,11 @@ XSLTPROC_PROCESS_MAN_IN = \ XSLTPROC_PROCESS_HTML = \ $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ - $(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< + $(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) man/custom-html.xsl $< XSLTPROC_PROCESS_HTML_IN = \ $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ - $(XSLTPROC) -o ${@:.in=} $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< && \ + $(XSLTPROC) -o ${@:.in=} $(XSLTPROC_FLAGS) man/custom-html.xsl $< && \ mv ${@:.in=} $@ man/%.1: man/%.xml diff --git a/man/custom-html.xsl b/man/custom-html.xsl new file mode 100644 index 0000000000..2d2f458793 --- /dev/null +++ b/man/custom-html.xsl @@ -0,0 +1,29 @@ + + + + + + + + + + + + -- cgit v1.2.3-54-g00ecf