2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"sd_path_lookup" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>sd_path_lookup
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>sd_path_lookup
</refentrytitle>
15 <manvolnum>3</manvolnum>
19 <refname>sd_path_lookup
</refname>
20 <refname>sd_path_lookup_strv
</refname>
22 <refpurpose>Query well-known file system paths
</refpurpose>
27 <funcsynopsisinfo>#include
<systemd/sd-path.h
></funcsynopsisinfo>
29 <!-- note: individual constants are not added as <refname>s, there's just too many -->
31 <funcsynopsisinfo><token>enum
</token> {
32 <constant>SD_PATH_TEMPORARY
</constant>,
33 <constant>SD_PATH_TEMPORARY_LARGE
</constant>,
35 <constant>SD_PATH_SYSTEM_BINARIES
</constant>,
36 <constant>SD_PATH_SYSTEM_INCLUDE
</constant>,
37 <constant>SD_PATH_SYSTEM_LIBRARY_PRIVATE
</constant>,
38 <constant>SD_PATH_SYSTEM_LIBRARY_ARCH
</constant>,
39 <constant>SD_PATH_SYSTEM_SHARED
</constant>,
40 <constant>SD_PATH_SYSTEM_CONFIGURATION_FACTORY
</constant>,
41 <constant>SD_PATH_SYSTEM_STATE_FACTORY
</constant>,
43 <constant>SD_PATH_SYSTEM_CONFIGURATION
</constant>,
44 <constant>SD_PATH_SYSTEM_RUNTIME
</constant>,
45 <constant>SD_PATH_SYSTEM_RUNTIME_LOGS
</constant>,
46 <constant>SD_PATH_SYSTEM_STATE_PRIVATE
</constant>,
47 <constant>SD_PATH_SYSTEM_STATE_LOGS
</constant>,
48 <constant>SD_PATH_SYSTEM_STATE_CACHE
</constant>,
49 <constant>SD_PATH_SYSTEM_STATE_SPOOL
</constant>,
51 <constant>SD_PATH_USER_BINARIES
</constant>,
52 <constant>SD_PATH_USER_LIBRARY_PRIVATE
</constant>,
53 <constant>SD_PATH_USER_LIBRARY_ARCH
</constant>,
54 <constant>SD_PATH_USER_SHARED
</constant>,
56 <constant>SD_PATH_USER_CONFIGURATION
</constant>,
57 <constant>SD_PATH_USER_RUNTIME
</constant>,
58 <constant>SD_PATH_USER_STATE_PRIVATE
</constant>,
59 <constant>SD_PATH_USER_STATE_CACHE
</constant>,
61 <constant>SD_PATH_USER
</constant>,
62 <constant>SD_PATH_USER_DOCUMENTS
</constant>,
63 <constant>SD_PATH_USER_MUSIC
</constant>,
64 <constant>SD_PATH_USER_PICTURES
</constant>,
65 <constant>SD_PATH_USER_VIDEOS
</constant>,
66 <constant>SD_PATH_USER_DOWNLOAD
</constant>,
67 <constant>SD_PATH_USER_PUBLIC
</constant>,
68 <constant>SD_PATH_USER_TEMPLATES
</constant>,
69 <constant>SD_PATH_USER_DESKTOP
</constant>,
71 <constant>SD_PATH_SEARCH_BINARIES
</constant>,
72 <constant>SD_PATH_SEARCH_BINARIES_DEFAULT
</constant>,
73 <constant>SD_PATH_SEARCH_LIBRARY_PRIVATE
</constant>,
74 <constant>SD_PATH_SEARCH_LIBRARY_ARCH
</constant>,
75 <constant>SD_PATH_SEARCH_SHARED
</constant>,
76 <constant>SD_PATH_SEARCH_CONFIGURATION_FACTORY
</constant>,
77 <constant>SD_PATH_SEARCH_STATE_FACTORY
</constant>,
78 <constant>SD_PATH_SEARCH_CONFIGURATION
</constant>,
80 <constant>SD_PATH_SYSTEMD_UTIL
</constant>,
81 <constant>SD_PATH_SYSTEMD_SYSTEM_UNIT
</constant>,
82 <constant>SD_PATH_SYSTEMD_SYSTEM_PRESET
</constant>,
83 <constant>SD_PATH_SYSTEMD_USER_UNIT
</constant>,
84 <constant>SD_PATH_SYSTEMD_USER_PRESET
</constant>,
85 <constant>SD_PATH_SYSTEMD_SYSTEM_CONF
</constant>,
86 <constant>SD_PATH_SYSTEMD_USER_CONF
</constant>,
87 <constant>SD_PATH_SYSTEMD_SEARCH_SYSTEM_UNIT
</constant>,
88 <constant>SD_PATH_SYSTEMD_SEARCH_USER_UNIT
</constant>,
89 <constant>SD_PATH_SYSTEMD_SYSTEM_GENERATOR
</constant>,
90 <constant>SD_PATH_SYSTEMD_USER_GENERATOR
</constant>,
91 <constant>SD_PATH_SYSTEMD_SEARCH_SYSTEM_GENERATOR
</constant>,
92 <constant>SD_PATH_SYSTEMD_SEARCH_USER_GENERATOR
</constant>,
93 <constant>SD_PATH_SYSTEMD_SLEEP
</constant>,
94 <constant>SD_PATH_SYSTEMD_SHUTDOWN
</constant>,
96 <constant>SD_PATH_TMPFILES
</constant>,
97 <constant>SD_PATH_SYSUSERS
</constant>,
98 <constant>SD_PATH_SYSCTL
</constant>,
99 <constant>SD_PATH_BINFMT
</constant>,
100 <constant>SD_PATH_MODULES_LOAD
</constant>,
101 <constant>SD_PATH_CATALOG
</constant>,
103 <constant>SD_PATH_SYSTEMD_SEARCH_NETWORK
</constant>,
105 <constant>SD_PATH_SYSTEMD_SYSTEM_ENVIRONMENT_GENERATOR
</constant>,
106 <constant>SD_PATH_SYSTEMD_USER_ENVIRONMENT_GENERATOR
</constant>,
107 <constant>SD_PATH_SYSTEMD_SEARCH_SYSTEM_ENVIRONMENT_GENERATOR
</constant>,
108 <constant>SD_PATH_SYSTEMD_SEARCH_USER_ENVIRONMENT_GENERATOR
</constant>,
109 };
</funcsynopsisinfo>
112 <funcdef>int
<function>sd_path_lookup
</function></funcdef>
113 <paramdef>uint64_t
<parameter>type
</parameter></paramdef>
114 <paramdef>const char *
<parameter>suffix
</parameter></paramdef>
115 <paramdef>char **
<parameter>paths
</parameter></paramdef>
119 <funcdef>int
<function>sd_path_lookup_strv
</function></funcdef>
120 <paramdef>uint64_t
<parameter>type
</parameter></paramdef>
121 <paramdef>const char *
<parameter>suffix
</parameter></paramdef>
122 <paramdef>char ***
<parameter>paths
</parameter></paramdef>
128 <title>Description
</title>
130 <para><function>sd_path_lookup()
</function> and
<function>sd_bus_path_lookup_strv()
</function> return a
131 single path or set of file system paths specified by the argument
<parameter>type
</parameter>. In case of
132 <function>sd_path_lookup()
</function> a single
<constant>NUL
</constant>-terminated string is returned.
133 When
<parameter>type
</parameter> specifies a set of paths, they are concatenated using
134 <literal>:
</literal> as a separator (as is traditionally done for e.g.
<varname>$PATH
</varname> or
135 <varname>$LD_LIBRARY_PATH
</varname>). In case of
<function>sd_path_lookup_strv()
</function> a
136 <constant>NULL
</constant>-terminated array of strings is returned (strv). If suffix
137 <parameter>suffix
</parameter> is given, it is concatenated to each of the paths after a slash
138 (
<literal>/
</literal>). All returned paths are absolute.
</para>
140 <para>For paths which refer to user directories, the relevant XDG standard is followed, with support for
141 environment variables like
<varname>$XDG_DOCUMENTS_DIR
</varname>,
<varname>$XDG_DESKTOP_DIR
</varname>,
142 ..., and explicit configuration in
<filename>/etc/xdg/user-dirs.conf
</filename> or
143 <filename>${XDG_CONFIG_HOME}/user-dirs.dirs
</filename>. See
144 <ulink url=
"https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">
145 XDG Base Directory Specification
</ulink> for details.
</para>
147 <para><citerefentry><refentrytitle>systemd-path
</refentrytitle><manvolnum>1</manvolnum></citerefentry> is
148 a wrapper around
<function>sd_path_lookup()
</function> and allows the same set of paths to be queried.
153 <title>Return Value
</title>
155 <para>On success,
<function>sd_path_lookup()
</function> and
<function>sd_path_lookup_strv()
</function>
156 return a non-negative integer. On failure, a negative errno-style error number is returned by either
159 <para>The returned string or string array (strv) must be
160 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>'d by the
163 <refsect2 id='errors'
>
164 <title>Errors
</title>
166 <para>Returned errors may indicate the following problems:
</para>
170 <term><constant>-EOPNOTSUPP
</constant></term>
172 <listitem><para>Unknown identifier
<parameter>type
</parameter>.
</para>
174 <xi:include href=
"version-info.xml" xpointer=
"v246"/></listitem>
178 <term><constant>-EINVAL
</constant></term>
180 <listitem><para>Output argument is
<constant>NULL
</constant>.
</para>
182 <xi:include href=
"version-info.xml" xpointer=
"v246"/></listitem>
186 <term><constant>-ENXIO
</constant></term>
188 <listitem><para>Query failed because of an undefined environment variable (e.g. for
189 <constant>SD_PATH_USER_RUNTIME
</constant> when
<varname>$XDG_RUNTIME_DIR
</varname> is not
192 <xi:include href=
"version-info.xml" xpointer=
"v246"/></listitem>
196 <term><constant>-ENOMEM
</constant></term>
198 <listitem><para>Memory allocation failed.
</para>
200 <xi:include href=
"version-info.xml" xpointer=
"v246"/></listitem>
207 <title>Examples
</title>
210 <title>Look up the location of ~/Documents
</title>
212 <programlisting><xi:include href=
"path-documents.c" parse=
"text" /></programlisting>
213 <para>Note that the default answer of
<filename index='false'
>$HOME/Documents
</filename> may be
214 overridden by
<filename index='false'
>user-dirs.conf
</filename> or
215 <varname>$XDG_DOCUMENTS_DIR
</varname>.
</para>
219 <xi:include href=
"libsystemd-pkgconfig.xml" />
222 <title>History
</title>
223 <para><function>sd_path_lookup()
</function> and
224 <function>sd_path_lookup_strv()
</function> were added in version
246.
</para>
228 <title>See Also
</title>
231 <citerefentry><refentrytitle>systemd-path
</refentrytitle><manvolnum>1</manvolnum></citerefentry>