Debian Codegraph @

upstream/debian-unstable/man1/systemd-vpick.1

raw
1 '\" t
2 .TH "SYSTEMD\-VPICK" "1" "" "systemd 261~rc3" "systemd-vpick"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-vpick \- Resolve paths to "\&.v/" versioned directories
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-vpick\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB[PATH...]\fR\ 'u
26 \fBsystemd\-vpick \fR\fB[OPTIONS...]\fR\fB \fR\fB[PATH...]\fR
27 .SH "DESCRIPTION"
28 .PP
29 \fBsystemd\-vpick\fR
30 resolves a file system path referencing a
31 "\&.v/"
32 versioned directory to a path to the newest (by version) file contained therein\&. This tool provides a command line interface for the
33 \fBsystemd.v\fR(7)
34 logic\&.
35 .PP
36 The tool expects a path to a
37 "\&.v/"
38 directory as argument (either directly, or with a triple underscore pattern as final component)\&. It then determines the newest file contained in that directory, and writes its path to standard output\&.
39 .PP
40 Unless the triple underscore pattern is passed as last component of the path, it is typically necessary to at least specify the
41 \fB\-\-suffix=\fR
42 switch to configure the file suffix to look for\&.
43 .PP
44 If the specified path does not reference a
45 "\&.v/"
46 path (i\&.e\&. neither the final component ends in
47 "\&.v", nor the penultimate does or the final one does contain a triple underscore) its specified path is written unmodified to standard output\&.
48 .SH "OPTIONS"
49 .PP
50 The following options are understood:
51 .PP
52 \fB\-\-basename=\fR, \fB\-B\fR
53 .RS 4
54 Overrides the "basename" of the files to look for, i\&.e\&. the part to the left of the variable part of the filenames\&. Normally this is derived automatically from the filename of the
55 "\&.v"
56 component of the specified path, or from the triple underscore pattern in the last component of the specified path\&.
57 .sp
58 Added in version 256\&.
59 .RE
60 .PP
61 \fB\-V\fR
62 .RS 4
63 Explicitly configures the version to select\&. If specified, a filename with the specified version string will be looked for, instead of the newest version available\&.
64 .sp
65 Added in version 256\&.
66 .RE
67 .PP
68 \fB\-A\fR
69 .RS 4
70 Explicitly configures the architecture to select\&. If specified, a filename with the specified architecture identifier will be looked for\&. If not specified, only filenames with a locally supported architecture are considered, or those without any architecture identifier\&.
71 .sp
72 Added in version 256\&.
73 .RE
74 .PP
75 \fB\-\-suffix=\fR, \fB\-S\fR
76 .RS 4
77 Configures the suffix of the filenames to consider\&. For the
78 "\&.v/"
79 logic it is necessary to specify the suffix to look for, and the
80 "\&.v/"
81 component must also carry the suffix immediately before
82 "\&.v"
83 in its name\&.
84 .sp
85 Added in version 256\&.
86 .RE
87 .PP
88 \fB\-\-type=\fR, \fB\-t\fR
89 .RS 4
90 Configures the inode type to look for in the
91 "\&.v/"
92 directory\&. Takes one of
93 "reg",
94 "dir",
95 "sock",
96 "fifo",
97 "blk",
98 "chr",
99 "lnk"
100 as argument, each identifying an inode type\&. See
101 \fBinode\fR(7)
102 for details about inode types\&. If this option is used inodes not matching the specified type are filtered and not taken into consideration\&.
103 .sp
104 Added in version 256\&.
105 .RE
106 .PP
107 \fB\-\-print=\fR, \fB\-p\fR
108 .RS 4
109 Configures what precisely to write to standard output\&. If not specified, prints the full, resolved path of the newest matching file in the
110 "\&.v/"
111 directory\&. This switch can be set to one of the following:
112 .sp
113 .RS 4
114 .ie n \{\
115 \h'-04'\(bu\h'+03'\c
116 .\}
117 .el \{\
118 .sp -1
119 .IP \(bu 2.3
120 .\}
121 If set to
122 "filename", will print only the filename instead of the full path of the resolved file\&.
123 .RE
124 .sp
125 .RS 4
126 .ie n \{\
127 \h'-04'\(bu\h'+03'\c
128 .\}
129 .el \{\
130 .sp -1
131 .IP \(bu 2.3
132 .\}
133 If set to
134 "version", will print only the version of the resolved file\&.
135 .RE
136 .sp
137 .RS 4
138 .ie n \{\
139 \h'-04'\(bu\h'+03'\c
140 .\}
141 .el \{\
142 .sp -1
143 .IP \(bu 2.3
144 .\}
145 If set to
146 "type", will print only the inode type of the resolved file (i\&.e\&. a string such as
147 "reg"
148 for regular files, or
149 "dir"
150 for directories)\&.
151 .RE
152 .sp
153 .RS 4
154 .ie n \{\
155 \h'-04'\(bu\h'+03'\c
156 .\}
157 .el \{\
158 .sp -1
159 .IP \(bu 2.3
160 .\}
161 If set to
162 "arch", will print only the architecture of the resolved file\&.
163 .RE
164 .sp
165 .RS 4
166 .ie n \{\
167 \h'-04'\(bu\h'+03'\c
168 .\}
169 .el \{\
170 .sp -1
171 .IP \(bu 2.3
172 .\}
173 If set to
174 "tries", will print only the tries left/tries done of the resolved file\&.
175 .RE
176 .sp
177 .RS 4
178 .ie n \{\
179 \h'-04'\(bu\h'+03'\c
180 .\}
181 .el \{\
182 .sp -1
183 .IP \(bu 2.3
184 .\}
185 If set to
186 "all", will print all of the above in a simple tabular output\&.
187 .RE
188 .sp
189 Added in version 256\&.
190 .RE
191 .PP
192 \fB\-\-resolve=\fR
193 .RS 4
194 Takes a boolean argument\&. If true the path to the versioned file is fully canonicalized (i\&.e\&. symlinks resolved, and redundant path components removed) before it is shown\&. If false (the default) this is not done, and the path is shown without canonicalization\&.
195 .sp
196 Added in version 256\&.
197 .RE
198 .PP
199 \fB\-h\fR, \fB\-\-help\fR
200 .RS 4
201 Print a short help text and exit\&.
202 .RE
203 .PP
204 \fB\-\-version\fR
205 .RS 4
206 Print a short version string and exit\&.
207 .RE
208 .SH "EXAMPLES"
209 .PP
210 Use a command like the following to automatically pick the newest raw disk image from a
211 "\&.v/"
212 directory:
213 .sp
214 .if n \{\
215 .RS 4
216 .\}
217 .nf
218 $ systemd\-vpick \-\-suffix=\&.raw \-\-type=reg /var/lib/machines/quux\&.raw\&.v/
219 .fi
220 .if n \{\
221 .RE
222 .\}
223 .PP
224 This will enumerate all regular files matching
225 /var/lib/machines/quux\&.raw\&.v/quux*\&.raw, filter and sort them according to the rules described in
226 \fBsystemd.v\fR(7), and then write the path to the newest (by version) file to standard output\&.
227 .PP
228 Use a command like the following to automatically pick the newest OS directory tree from a
229 "\&.v/"
230 directory:
231 .sp
232 .if n \{\
233 .RS 4
234 .\}
235 .nf
236 $ systemd\-vpick \-\-type=dir /var/lib/machines/waldo\&.v/
237 .fi
238 .if n \{\
239 .RE
240 .\}
241 .PP
242 This will enumerate all directory inodes matching
243 /var/lib/machines/waldo\&.v/waldo*, filter and sort them according to the rules described in
244 \fBsystemd.v\fR(7), and then write the path to the newest (by version) directory to standard output\&.
245 .PP
246 For further examples see
247 \fBsystemd.v\fR(7)\&.
248 .SH "EXIT STATUS"
249 .PP
250 On success, 0 is returned, a non\-zero failure code otherwise\&.
251 .SH "SEE ALSO"
252 .PP
253 \fBsystemd\fR(1), \fBsystemd.v\fR(7)