1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="sd_path_lookup" xmlns:xi="http://www.w3.org/2001/XInclude">
7
8  <refentryinfo>
9    <title>sd_path_lookup</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>sd_path_lookup</refentrytitle>
15    <manvolnum>3</manvolnum>
16  </refmeta>
17
18  <refnamediv>
19    <refname>sd_path_lookup</refname>
20    <refname>sd_path_lookup_strv</refname>
21
22    <refpurpose>Query well-known file system paths</refpurpose>
23  </refnamediv>
24
25  <refsynopsisdiv>
26    <funcsynopsis>
27      <funcsynopsisinfo>#include &lt;systemd/sd-path.h&gt;</funcsynopsisinfo>
28
29      <!-- note: individual constants are not added as <refname>s, there's just too many -->
30
31      <funcsynopsisinfo><token>enum</token> {
32        <constant>SD_PATH_TEMPORARY</constant>,
33        <constant>SD_PATH_TEMPORARY_LARGE</constant>,
34
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>,
42
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>,
50
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>,
55
56        <constant>SD_PATH_USER_CONFIGURATION</constant>,
57        <constant>SD_PATH_USER_RUNTIME</constant>,
58        <constant>SD_PATH_USER_STATE_CACHE</constant>,
59
60        <constant>SD_PATH_USER</constant>,
61        <constant>SD_PATH_USER_DOCUMENTS</constant>,
62        <constant>SD_PATH_USER_MUSIC</constant>,
63        <constant>SD_PATH_USER_PICTURES</constant>,
64        <constant>SD_PATH_USER_VIDEOS</constant>,
65        <constant>SD_PATH_USER_DOWNLOAD</constant>,
66        <constant>SD_PATH_USER_PUBLIC</constant>,
67        <constant>SD_PATH_USER_TEMPLATES</constant>,
68        <constant>SD_PATH_USER_DESKTOP</constant>,
69
70        <constant>SD_PATH_SEARCH_BINARIES</constant>,
71        <constant>SD_PATH_SEARCH_BINARIES_DEFAULT</constant>,
72        <constant>SD_PATH_SEARCH_LIBRARY_PRIVATE</constant>,
73        <constant>SD_PATH_SEARCH_LIBRARY_ARCH</constant>,
74        <constant>SD_PATH_SEARCH_SHARED</constant>,
75        <constant>SD_PATH_SEARCH_CONFIGURATION_FACTORY</constant>,
76        <constant>SD_PATH_SEARCH_STATE_FACTORY</constant>,
77        <constant>SD_PATH_SEARCH_CONFIGURATION</constant>,
78
79        <constant>SD_PATH_SYSTEMD_UTIL</constant>,
80        <constant>SD_PATH_SYSTEMD_SYSTEM_UNIT</constant>,
81        <constant>SD_PATH_SYSTEMD_SYSTEM_PRESET</constant>,
82        <constant>SD_PATH_SYSTEMD_USER_UNIT</constant>,
83        <constant>SD_PATH_SYSTEMD_USER_PRESET</constant>,
84        <constant>SD_PATH_SYSTEMD_SYSTEM_CONF</constant>,
85        <constant>SD_PATH_SYSTEMD_USER_CONF</constant>,
86        <constant>SD_PATH_SYSTEMD_SEARCH_SYSTEM_UNIT</constant>,
87        <constant>SD_PATH_SYSTEMD_SEARCH_USER_UNIT</constant>,
88        <constant>SD_PATH_SYSTEMD_SYSTEM_GENERATOR</constant>,
89        <constant>SD_PATH_SYSTEMD_USER_GENERATOR</constant>,
90        <constant>SD_PATH_SYSTEMD_SEARCH_SYSTEM_GENERATOR</constant>,
91        <constant>SD_PATH_SYSTEMD_SEARCH_USER_GENERATOR</constant>,
92        <constant>SD_PATH_SYSTEMD_SLEEP</constant>,
93        <constant>SD_PATH_SYSTEMD_SHUTDOWN</constant>,
94
95        <constant>SD_PATH_TMPFILES</constant>,
96        <constant>SD_PATH_SYSUSERS</constant>,
97        <constant>SD_PATH_SYSCTL</constant>,
98        <constant>SD_PATH_BINFMT</constant>,
99        <constant>SD_PATH_MODULES_LOAD</constant>,
100        <constant>SD_PATH_CATALOG</constant>,
101
102        <constant>SD_PATH_SYSTEMD_SEARCH_NETWORK</constant>,
103};</funcsynopsisinfo>
104
105      <funcprototype>
106        <funcdef>int <function>sd_path_lookup</function></funcdef>
107        <paramdef>uint64_t <parameter>type</parameter></paramdef>
108        <paramdef>const char *<parameter>suffix</parameter></paramdef>
109        <paramdef>char **<parameter>paths</parameter></paramdef>
110      </funcprototype>
111
112      <funcprototype>
113        <funcdef>int <function>sd_path_lookup_strv</function></funcdef>
114        <paramdef>uint64_t <parameter>type</parameter></paramdef>
115        <paramdef>const char *<parameter>suffix</parameter></paramdef>
116        <paramdef>char ***<parameter>paths</parameter></paramdef>
117      </funcprototype>
118    </funcsynopsis>
119  </refsynopsisdiv>
120
121  <refsect1>
122    <title>Description</title>
123
124    <para><function>sd_path_lookup()</function> and <function>sd_bus_path_lookup_strv()</function> return a
125    single path or set of file system paths specified by the argument <parameter>type</parameter>. In case of
126    <function>sd_path_lookup()</function> a single <constant>NUL</constant>-terminated string is returned.
127    When <parameter>type</parameter> specifies a set of paths, they are concatenated using
128    <literal>:</literal> as a separator (as is traditionally done for e.g. <varname>$PATH</varname> or
129    <varname>$LD_LIBRARY_PATH</varname>). In case of <function>sd_path_lookup_strv()</function> a
130    <constant>NULL</constant>-terminated array of strings is returned (strv). If suffix
131    <parameter>suffix</parameter> is given, it is concatenated to each of the paths after a slash
132    (<literal>/</literal>). All returned paths are absolute.</para>
133
134    <para>For paths which refer to user directories, the relevant XDG standard is followed, with support for
135    environment variables like <varname>$XDG_DOCUMENTS_DIR</varname>, <varname>$XDG_DESKTOP_DIR</varname>,
136    ..., and explicit configuration in <filename>/etc/xdg/user-dirs.conf</filename> or
137    <filename>${XDG_CONFIG_HOME}/user-dirs.dirs</filename>. See
138    <ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">
139      XDG Base Directory Specification</ulink> for details.</para>
140
141    <para><citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry> is
142    a wrapper around <function>sd_path_lookup()</function> and allows the same set of paths to be queried.
143    </para>
144  </refsect1>
145
146  <refsect1>
147    <title>Return Value</title>
148
149    <para>On success, <function>sd_path_lookup()</function> and <function>sd_path_lookup_strv()</function>
150    return a non-negative integer. On failure, a negative errno-style error number is returned by either
151    function.</para>
152
153    <para>The returned string or string array (strv) must be
154    <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>'d by the
155    caller.</para>
156
157    <refsect2 id='errors'>
158      <title>Errors</title>
159
160      <para>Returned errors may indicate the following problems:</para>
161
162      <variablelist>
163        <varlistentry>
164          <term><constant>-EOPNOTSUPP</constant></term>
165
166          <listitem><para>Unknown identifier <parameter>type</parameter>.</para></listitem>
167        </varlistentry>
168
169        <varlistentry>
170          <term><constant>-EINVAL</constant></term>
171
172          <listitem><para>Output argument is <constant>NULL</constant>.</para></listitem>
173        </varlistentry>
174
175        <varlistentry>
176          <term><constant>-ENXIO</constant></term>
177
178          <listitem><para>Query failed because of an undefined environment variable (e.g. for
179          <constant>SD_PATH_USER_RUNTIME</constant> when <varname>$XDG_RUNTIME_DIR</varname> is not
180          defined).</para></listitem>
181        </varlistentry>
182
183        <varlistentry>
184          <term><constant>-ENOMEM</constant></term>
185
186          <listitem><para>Memory allocation failed.</para></listitem>
187        </varlistentry>
188      </variablelist>
189    </refsect2>
190  </refsect1>
191
192  <refsect1>
193    <title>Examples</title>
194
195    <refsect2>
196      <title>Look up the location of ~/Documents</title>
197
198      <programlisting><xi:include href="path-documents.c" parse="text" /></programlisting>
199      <para>Note that the default answer of <filename index='false'>$HOME/Documents</filename> may be
200      overridden by <filename index='false'>user-dirs.conf</filename> or
201      <varname>$XDG_DOCUMENTS_DIR</varname>.</para>
202    </refsect2>
203  </refsect1>
204
205  <xi:include href="libsystemd-pkgconfig.xml" />
206
207  <refsect1>
208    <title>See Also</title>
209
210    <para>
211      <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>
212    </para>
213  </refsect1>
214
215</refentry>
216