X Tutup
Skip to content

Commit b35ed55

Browse files
keszybzkeszybz
committed
man: add sd_path_lookup(3)
1 parent 557afad commit b35ed55

File tree

3 files changed

+192
-0
lines changed

3 files changed

+192
-0
lines changed

‎man/path-documents.c‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#include <stdio.h>
2+
#include <sd-path.h>
3+
4+
int main(void) {
5+
char *t;
6+
7+
sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
8+
printf("~/Documents: %s\n", t);
9+
}

‎man/rules/meson.build‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -623,6 +623,7 @@ manpages = [
623623
'3',
624624
['sd_notifyf', 'sd_pid_notify', 'sd_pid_notify_with_fds', 'sd_pid_notifyf'],
625625
''],
626+
['sd_path_lookup', '3', ['sd_path_lookup_strv'], ''],
626627
['sd_pid_get_owner_uid',
627628
'3',
628629
['sd_peer_get_cgroup',

‎man/sd_path_lookup.xml‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
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+ -->
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+
};</funcsynopsisinfo>
79+
80+
<funcprototype>
81+
<funcdef>int <function>sd_path_lookup</function></funcdef>
82+
<paramdef>uint64_t <parameter>type</parameter></paramdef>
83+
<paramdef>const char *<parameter>suffix</parameter></paramdef>
84+
<paramdef>char **<parameter>paths</parameter></paramdef>
85+
</funcprototype>
86+
87+
<funcprototype>
88+
<funcdef>int <function>sd_path_lookup_strv</function></funcdef>
89+
<paramdef>uint64_t <parameter>type</parameter></paramdef>
90+
<paramdef>const char *<parameter>suffix</parameter></paramdef>
91+
<paramdef>char ***<parameter>paths</parameter></paramdef>
92+
</funcprototype>
93+
</funcsynopsis>
94+
</refsynopsisdiv>
95+
96+
<refsect1>
97+
<title>Description</title>
98+
99+
<para><function>sd_path_lookup()</function> and <function>sd_bus_path_lookup_strv()</function> return a
100+
single path or set of file system paths specified by the argument <parameter>type</parameter>. In case of
101+
<function>sd_path_lookup()</function> a single <constant>NUL</constant>-terminated string is returned.
102+
When <parameter>type</parameter> specifies a set of paths, they are concatenated using
103+
<literal>:</literal> as a separator (as is traditionally done for e.g. <varname>$PATH</varname> or
104+
<varname>$LD_LIBRARY_PATH</varname>). In case of <function>sd_path_lookup_strv()</function> a
105+
<constant>NULL</constant>-terminated array of strings is returned (strv). If suffix
106+
<parameter>suffix</parameter> is given, it is concatenated to each of the paths after a slash
107+
(<literal>/</literal>). All returned paths are absolute.</para>
108+
109+
<para>For paths which refer to user directories, the relevant XDG standard is followed, with support for
110+
environment variables like <varname>$XDG_DOCUMENTS_DIR</varname>, <varname>$XDG_DESKTOP_DIR</varname>,
111+
..., and explicit configuration in <filename>/etc/xdg/user-dirs.conf</filename> or
112+
<filename>${XDG_CONFIG_HOME}/user-dirs.dirs</filename>. See
113+
<ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">
114+
XDG Base Directory Specification</ulink> for details.</para>
115+
116+
<para><citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry> is
117+
a wrapper around <function>sd_path_lookup()</function> and allows the same set of paths to be queried.
118+
</para>
119+
</refsect1>
120+
121+
<refsect1>
122+
<title>Return Value</title>
123+
124+
<para>On success, <function>sd_path_lookup()</function> and <function>sd_path_lookup_strv()</function>
125+
return a non-negative integer. On failure, a negative errno-style error number is returned by either
126+
function.</para>
127+
128+
<para>The returned string or string array (strv) must be
129+
<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>'d by the
130+
caller.</para>
131+
132+
<refsect2 id='errors'>
133+
<title>Errors</title>
134+
135+
<para>Returned errors may indicate the following problems:</para>
136+
137+
<variablelist>
138+
<varlistentry>
139+
<term><constant>-EOPNOTSUPP</constant></term>
140+
141+
<listitem><para>Unknown identifier <parameter>type</parameter>.</para></listitem>
142+
</varlistentry>
143+
144+
<varlistentry>
145+
<term><constant>-EINVAL</constant></term>
146+
147+
<listitem><para>Output argument is <constant>NULL</constant>.</para></listitem>
148+
</varlistentry>
149+
150+
<varlistentry>
151+
<term><constant>-ENOMEM</constant></term>
152+
153+
<listitem><para>Memory allocation failed.</para></listitem>
154+
</varlistentry>
155+
</variablelist>
156+
</refsect2>
157+
</refsect1>
158+
159+
<refsect1>
160+
<title>Examples</title>
161+
162+
<refsect2>
163+
<title>Look up the location of ~/Documents</title>
164+
165+
<programlisting><xi:include href="path-documents.c" parse="text" /></programlisting>
166+
<para>Note that the default answer of <filename index='false'>$HOME/Documents</filename> may be
167+
overridden by <filename index='false'>user-dirs.conf</filename> or
168+
<varname>$XDG_DOCUMENTS_DIR</varname>.</para>
169+
</refsect2>
170+
</refsect1>
171+
172+
<xi:include href="libsystemd-pkgconfig.xml" />
173+
174+
<refsect1>
175+
<title>See Also</title>
176+
177+
<para>
178+
<citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>
179+
</para>
180+
</refsect1>
181+
182+
</refentry>

0 commit comments

Comments
 (0)
X Tutup