From b35ed5530ba1c576b4fa899b9da04882a940ab07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 23 Mar 2020 20:36:41 +0100 Subject: [PATCH] man: add sd_path_lookup(3) --- man/path-documents.c | 9 ++ man/rules/meson.build | 1 + man/sd_path_lookup.xml | 182 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 192 insertions(+) create mode 100644 man/path-documents.c create mode 100644 man/sd_path_lookup.xml diff --git a/man/path-documents.c b/man/path-documents.c new file mode 100644 index 00000000000..a6c1f9371ae --- /dev/null +++ b/man/path-documents.c @@ -0,0 +1,9 @@ +#include +#include + +int main(void) { + char *t; + + sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t); + printf("~/Documents: %s\n", t); +} diff --git a/man/rules/meson.build b/man/rules/meson.build index b95ef6964af..827fbd7155a 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -623,6 +623,7 @@ manpages = [ '3', ['sd_notifyf', 'sd_pid_notify', 'sd_pid_notify_with_fds', 'sd_pid_notifyf'], ''], + ['sd_path_lookup', '3', ['sd_path_lookup_strv'], ''], ['sd_pid_get_owner_uid', '3', ['sd_peer_get_cgroup', diff --git a/man/sd_path_lookup.xml b/man/sd_path_lookup.xml new file mode 100644 index 00000000000..c14ccf0e8c4 --- /dev/null +++ b/man/sd_path_lookup.xml @@ -0,0 +1,182 @@ + + + + + + + + sd_path_lookup + systemd + + + + sd_path_lookup + 3 + + + + sd_path_lookup + sd_path_lookup_strv + + Query well-known file system paths + + + + + #include <systemd/sd-path.h> + + + + enum { + SD_PATH_TEMPORARY, + SD_PATH_TEMPORARY_LARGE, + + SD_PATH_SYSTEM_BINARIES, + SD_PATH_SYSTEM_INCLUDE, + SD_PATH_SYSTEM_LIBRARY_PRIVATE, + SD_PATH_SYSTEM_LIBRARY_ARCH, + SD_PATH_SYSTEM_SHARED, + SD_PATH_SYSTEM_CONFIGURATION_FACTORY, + SD_PATH_SYSTEM_STATE_FACTORY, + + SD_PATH_SYSTEM_CONFIGURATION, + SD_PATH_SYSTEM_RUNTIME, + SD_PATH_SYSTEM_RUNTIME_LOGS, + SD_PATH_SYSTEM_STATE_PRIVATE, + SD_PATH_SYSTEM_STATE_LOGS, + SD_PATH_SYSTEM_STATE_CACHE, + SD_PATH_SYSTEM_STATE_SPOOL, + + SD_PATH_USER_BINARIES, + SD_PATH_USER_LIBRARY_PRIVATE, + SD_PATH_USER_LIBRARY_ARCH, + SD_PATH_USER_SHARED, + + SD_PATH_USER_CONFIGURATION, + SD_PATH_USER_RUNTIME, + SD_PATH_USER_STATE_CACHE, + + SD_PATH_USER, + SD_PATH_USER_DOCUMENTS, + SD_PATH_USER_MUSIC, + SD_PATH_USER_PICTURES, + SD_PATH_USER_VIDEOS, + SD_PATH_USER_DOWNLOAD, + SD_PATH_USER_PUBLIC, + SD_PATH_USER_TEMPLATES, + SD_PATH_USER_DESKTOP, + + SD_PATH_SEARCH_BINARIES, + SD_PATH_SEARCH_BINARIES_DEFAULT, + SD_PATH_SEARCH_LIBRARY_PRIVATE, + SD_PATH_SEARCH_LIBRARY_ARCH, + SD_PATH_SEARCH_SHARED, + SD_PATH_SEARCH_CONFIGURATION_FACTORY, + SD_PATH_SEARCH_STATE_FACTORY, + SD_PATH_SEARCH_CONFIGURATION, +}; + + + int sd_path_lookup + uint64_t type + const char *suffix + char **paths + + + + int sd_path_lookup_strv + uint64_t type + const char *suffix + char ***paths + + + + + + Description + + sd_path_lookup() and sd_bus_path_lookup_strv() return a + single path or set of file system paths specified by the argument type. In case of + sd_path_lookup() a single NUL-terminated string is returned. + When type specifies a set of paths, they are concatenated using + : as a separator (as is traditionally done for e.g. $PATH or + $LD_LIBRARY_PATH). In case of sd_path_lookup_strv() a + NULL-terminated array of strings is returned (strv). If suffix + suffix is given, it is concatenated to each of the paths after a slash + (/). All returned paths are absolute. + + For paths which refer to user directories, the relevant XDG standard is followed, with support for + environment variables like $XDG_DOCUMENTS_DIR, $XDG_DESKTOP_DIR, + ..., and explicit configuration in /etc/xdg/user-dirs.conf or + ${XDG_CONFIG_HOME}/user-dirs.dirs. See + + XDG Base Directory Specification for details. + + systemd-path1 is + a wrapper around sd_path_lookup() and allows the same set of paths to be queried. + + + + + Return Value + + On success, sd_path_lookup() and sd_path_lookup_strv() + return a non-negative integer. On failure, a negative errno-style error number is returned by either + function. + + The returned string or string array (strv) must be + free3'd by the + caller. + + + Errors + + Returned errors may indicate the following problems: + + + + -EOPNOTSUPP + + Unknown identifier type. + + + + -EINVAL + + Output argument is NULL. + + + + -ENOMEM + + Memory allocation failed. + + + + + + + Examples + + + Look up the location of ~/Documents + + + Note that the default answer of $HOME/Documents may be + overridden by user-dirs.conf or + $XDG_DOCUMENTS_DIR. + + + + + + + See Also + + + systemd-path1 + + + +