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+ -->
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_CACHE
</constant>,
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>,
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>,
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>,
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>,
102 <constant>SD_PATH_SYSTEMD_SEARCH_NETWORK
</constant>,
103 };
</funcsynopsisinfo>
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>
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>
122 <title>Description
</title>
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>
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>
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.
147 <title>Return Value
</title>
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
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
157 <refsect2 id='errors'
>
158 <title>Errors
</title>
160 <para>Returned errors may indicate the following problems:
</para>
164 <term><constant>-EOPNOTSUPP
</constant></term>
166 <listitem><para>Unknown identifier
<parameter>type
</parameter>.
</para></listitem>
170 <term><constant>-EINVAL
</constant></term>
172 <listitem><para>Output argument is
<constant>NULL
</constant>.
</para></listitem>
176 <term><constant>-ENXIO
</constant></term>
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>
184 <term><constant>-ENOMEM
</constant></term>
186 <listitem><para>Memory allocation failed.
</para></listitem>
193 <title>Examples
</title>
196 <title>Look up the location of ~/Documents
</title>
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>
205 <xi:include href=
"libsystemd-pkgconfig.xml" />
208 <title>See Also
</title>
211 <citerefentry><refentrytitle>systemd-path
</refentrytitle><manvolnum>1</manvolnum></citerefentry>