| blob | 3498c54ced415c875bd61610f2f4c359aaa0a618 |
1 '\" te
2 .\" Copyright 2007 Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH LIST_DEVICES 1 "Mar 6, 2017"
7 .SH NAME
8 list_devices \- list allocatable devices
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBlist_devices\fR [\fB-s\fR] [\fB-U\fR \fIuid\fR] [\fB-z\fR \fIzonename\fR] [\fB-a\fR [\fB-w\fR]]
13 \fB-l\fR | \fB-n\fR | \fB-u\fR [\fIdevice\fR] | [\fB-l\fR | \fB-n\fR | \fB-u\fR] \fB-c\fR \fIdev-class\fR
14 .fi
16 .LP
17 .nf
18 \fBlist_devices\fR [\fB-s\fR] \fB-d\fR \fIdev-type\fR
19 .fi
21 .SH DESCRIPTION
22 .LP
23 The \fBlist_devices\fR utility lists the allocatable devices in the system
24 according to specified qualifications.
25 .sp
26 .LP
27 The \fIdevice\fR and all device special files associated with the device are
28 listed. The device argument is optional and, if it is not present, all relevant
29 devices are listed. If \fIdev-class\fR is present, devices belonging to the
30 specified \fIdev-class\fR are listed. There is no default \fIdev-class\fR.
31 .SH OPTIONS
32 .LP
33 The following options are supported:
34 .sp
35 .ne 2
36 .na
37 \fB\fB-l\fR [\fB-c\fR \fIdev-class\fR | \fIdevice\fR]\fR
38 .ad
39 .RS 30n
40 Lists the pathnames of the device special files associated with the
41 \fIdevice\fR that are allocatable to the current process.
42 .sp
43 If \fIdev-class\fR is specified, lists only the files associated with all
44 devices of the specified device class.
45 .sp
46 If \fIdevice\fR is specified, lists only the files associated with the
47 specified device.
48 .RE
50 .sp
51 .ne 2
52 .na
53 \fB\fB-n\fR [\fB-c\fR \fIdev-class\fR | \fIdevice\fR]\fR
54 .ad
55 .RS 30n
56 Lists the pathnames of the device special files associated with the device that
57 are allocatable to the current process but are not currently allocated.
58 .sp
59 If \fIdev-class\fR is specified, lists only the files associated with all
60 devices of the specified device class.
61 .sp
62 If \fIdevice\fR is specified, lists only the files associated with the
63 specified device.
64 .RE
66 .sp
67 .ne 2
68 .na
69 \fB\fB-s\fR\fR
70 .ad
71 .RS 30n
72 Silent. Suppresses any diagnostic output.
73 .RE
75 .sp
76 .ne 2
77 .na
78 \fB\fB-u\fR [\fB-c\fR \fIdev-class\fR | \fIdevice\fR]\fR
79 .ad
80 .RS 30n
81 Lists the pathnames of device special files associated with the device that are
82 allocated to the owner of the current process.
83 .sp
84 If \fIdev-class\fR is specified, lists only the files associated with all
85 devices of the specified device class.
86 .sp
87 If \fIdevice\fR is specified, lists only the files associated with the
88 specified device.
89 .RE
91 .sp
92 .ne 2
93 .na
94 \fB\fB-U\fR \fIuid\fR\fR
95 .ad
96 .RS 30n
97 Uses the user \fBID\fR \fIuid\fR instead of the real user \fBID\fR of the
98 current process when performing the \fBlist_devices\fR operation. Only a user
99 with the \fBsolaris.device.revoke\fR authorization can use this option.
100 .RE
102 .sp
103 .LP
104 The following options are supported when the system is configured with Trusted
105 Extensions:
106 .sp
107 .ne 2
108 .na
109 \fB\fB-a\fR\fR
110 .ad
111 .RS 15n
112 Lists attributes like authorizations, cleaning programs and labels associated
113 with a device.
114 .sp
115 The list is a single line of semicolon (\fB;\fR) separated
116 \fIkey\fR\fB=\fR\fIvalue\fR pairs for each device in the format:
117 .sp
118 .in +2
119 .nf
120 device=\fIdevice-name\fR;type=\fIdevice-type\fR;\e
121 auths=\fIauths\fR;clean=\fIdevice-exec\fR;\e
122 \fIdevice-attributes\fR;\e
123 files=\fIdevice-list\fR
124 .fi
125 .in -2
126 .sp
128 where \fIdevice-attributes\fR is the contents of the \fBreserved1\fR field of
129 \fBdevice_allocate\fR(4). The field is colon (\fB:\fR) separated.)
130 .sp
131 See \fBdevice_allocate\fR(4) for a description of these attributes and their
132 format.
133 .sp
134 The \fB-a\fR output has the following keys:
135 .sp
136 .ne 2
137 .na
138 \fB\fBauths\fR\fR
139 .ad
140 .RS 10n
141 Specifies the list of authorizations. The value is \fBauths\fR is described in
142 \fBdevice_allocate\fR(4).
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBclean\fR\fR
149 .ad
150 .RS 10n
151 Specifies the device cleaning script. The value is \fBdevice-exec\fR as
152 described in \fBdevice_allocate\fR(4).
153 .RE
155 .sp
156 .ne 2
157 .na
158 \fB\fBdevice\fR\fR
159 .ad
160 .RS 10n
161 Specifies the device name. The value is \fBdevice-name\fR as described in
162 \fBdevice_allocate\fR(4).
163 .RE
165 .sp
166 .ne 2
167 .na
168 \fB\fBfiles\fR\fR
169 .ad
170 .RS 10n
171 Specifies the device file paths. The value is \fBdevice-list\fR as described in
172 \fBdevice_maps\fR(4).
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fBtype\fR\fR
179 .ad
180 .RS 10n
181 Specifies the device type. The value is \fBdevice-type\fR as described in
182 \fBdevice_allocate\fR(4).
183 .RE
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fB-d\fR\fR
191 .ad
192 .RS 15n
193 Displays the system-supplied default attributes for the device types managed by
194 device allocation. If \fIdev-type\fR is specified, it lists the default
195 attributes for only that device type.
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fB-w\fR\fR
202 .ad
203 .RS 15n
204 This option can be used with \fB-a\fR to list the current owner of the device
205 as the key value pair \fIowner\fR\fB=\fR\fIvalue\fR. \fIvalue\fR is the
206 \fBuid\fR of the current owner of the device. If the device is unallocated,
207 value is \fB/FREE\fR. If the device is in error state, value is \fB/ERROR\fR.
208 This option also suppresses any diagnostic output.
209 .RE
211 .sp
212 .ne 2
213 .na
214 \fB\fB-z\fR \fIzonename\fR\fR
215 .ad
216 .RS 15n
217 When specified with the \fB-l\fR option, lists only those non-allocated devices
218 whose label range includes the label of the zonename, and of the allocated
219 devices, only those that are allocated at the same label as that of
220 \fIzonename\fR.
221 .sp
222 When specified with the \fB-n\fR option, lists only those non-allocated devices
223 whose label range includes the label of the \fIzonename\fR.
224 .sp
225 When specified with the \fB-u\fR option, lists only those devices that are
226 allocated at the same label as that of \fIzonename\fR.
227 .RE
229 .SH EXAMPLES
230 .LP
231 \fBExample 1 \fRListing All Devices
232 .sp
233 .LP
234 The following example lists all devices available to the caller for allocation:
236 .sp
237 .in +2
238 .nf
239 % list_devices -l
240 device: audio type: audio \e
241 files: /dev/audio /dev/audioctl /dev/sound/0 /dev/sound/0ctl
242 .fi
243 .in -2
244 .sp
246 .LP
247 \fBExample 2 \fRListing Attributes of All Devices
248 .sp
249 .LP
250 On a system configured with Trusted Extensions, the following example lists
251 attributes of all devices available to the caller for allocation:
253 .sp
254 .in +2
255 .nf
256 % list_devices -al
257 device=audio1;type=audio;\e
258 auths=solaris.device.allocate;\e
259 clean=/etc/security/lib/audio_clean;\e
260 minlabel=admin_low:maxlabel=admin_high;\e
261 files=/dev/audio1 /dev/audio1ctl /dev/sound/1 /dev/sound/1ctl
262 .fi
263 .in -2
264 .sp
266 .LP
267 \fBExample 3 \fRListing Attributes Including the Device Owner
268 .sp
269 .LP
270 On a system configured with Trusted Extensions, the following example lists
271 attributes including the device owner of all devices allocated to the user:
273 .sp
274 .in +2
275 .nf
276 % list_devices -auw
277 device=audio2;type=audio;auths=solaris.device.allocate;\e
278 clean=/etc/security/lib/audio_clean;\e
279 minlabel=admin_low:maxlabel=admin_high:zone=public;\e
280 owner=1234;\e
281 files=/dev/audio2 /dev/audio2ctl /dev/sound/2 /dev/sound/2ctl
282 .fi
283 .in -2
284 .sp
286 .SH EXIT STATUS
287 .LP
288 The following exit values are returned:
289 .sp
290 .ne 2
291 .na
292 \fB\fB0\fR\fR
293 .ad
294 .RS 15n
295 Successful completion.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fB20\fR\fR
302 .ad
303 .RS 15n
304 No entry for the specified device.
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fIother value\fR\fR
311 .ad
312 .RS 15n
313 An error occurred.
314 .RE
316 .SH FILES
317 .LP
318 \fB/etc/security/device_allocate\fR
319 .sp
320 .LP
321 \fB/etc/security/device_maps\fR
322 .sp
323 .LP
324 \fB/etc/security/dev/*\fR
325 .sp
326 .LP
327 \fB/usr/security/lib/*\fR
328 .SH ATTRIBUTES
329 .LP
330 See \fBattributes\fR(5) for descriptions of the following attributes:
331 .sp
333 .sp
334 .TS
335 box;
336 c | c
337 l | l .
338 ATTRIBUTE TYPE ATTRIBUTE VALUE
339 _
340 Interface Stability See below.
341 .TE
343 .sp
344 .LP
345 The invocation is Uncommitted. The options are Uncommitted. The output from the
346 \fB-a\fR and \fB-w\fR options is Uncommitted. All other output is
347 Not-an-Interface.
348 .SH SEE ALSO
349 .LP
350 \fBallocate\fR(1), \fBdeallocate\fR(1), \fBdminfo\fR(1M),
351 \fBmkdevalloc\fR(1M), \fBmkdevmaps\fR(1M), \fBdevice_allocate\fR(4),
352 \fBdevice_maps\fR(4), \fBattributes\fR(5)
353 .SH NOTES
354 .LP
355 On systems configured with Trusted Extensions, the functionality is enabled by
356 default.
357 .sp
358 .LP
359 \fB/etc/security/dev\fR, \fBmkdevalloc\fR(1M), and \fBmkdevmaps\fR(1M) might
360 not be supported in a future release of the Solaris Operating Environment.