| blob | 66d8a7d70df32c83012ae38dda29af0c945d3642 |
1 .\"
2 .\" The contents of this file are subject to the terms of the
3 .\" Common Development and Distribution License (the "License").
4 .\" You may not use this file except in compliance with the License.
5 .\"
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7 .\" or http://www.opensolaris.org/os/licensing.
8 .\" See the License for the specific language governing permissions
9 .\" and limitations under the License.
10 .\"
11 .\" When distributing Covered Code, include this CDDL HEADER in each
12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13 .\" If applicable, add the following below this CDDL HEADER, with the
14 .\" fields enclosed by brackets "[]" replaced with your own identifying
15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
16 .\"
17 .\"
18 .\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved
19 .\" Copyright 2017 Nexenta Systems, Inc.
20 .\"
21 .Dd January 25, 2017
22 .Dt DEVID_GET 3DEVID
23 .Os
24 .Sh NAME
25 .Nm devid_get ,
26 .Nm devid_free ,
27 .Nm devid_get_minor_name ,
28 .Nm devid_deviceid_to_nmlist ,
29 .Nm devid_free_nmlist ,
30 .Nm devid_compare ,
31 .Nm devid_sizeof ,
32 .Nm devid_valid ,
33 .Nm devid_str_encode ,
34 .Nm devid_str_decode ,
35 .Nm devid_str_from_path ,
36 .Nm devid_str_free
37 .Nd device ID interfaces for user applications
38 .Sh SYNOPSIS
39 .Lb libdevid
40 .In devid.h
41 .Ft int
42 .Fo devid_get
43 .Fa "int fd"
44 .Fa "ddi_devid_t *retdevid"
45 .Fc
46 .Ft void
47 .Fo devid_free
48 .Fa "ddi_devid_t devid"
49 .Fc
50 .Ft int
51 .Fo devid_get_minor_name
52 .Fa "int fd"
53 .Fa "char **retminor_name"
54 .Fc
55 .Ft int
56 .Fo devid_deviceid_to_nmlist
57 .Fa "char *search_path"
58 .Fa "ddi_devid_t devid"
59 .Fa "char *minor_name"
60 .Fa "devid_nmlist_t **retlist"
61 .Fc
62 .Ft void
63 .Fo devid_free_nmlist
64 .Fa "devid_nmlist_t *list"
65 .Fc
66 .Ft int
67 .Fo devid_compare
68 .Fa "ddi_devid_t devid1"
69 .Fa "ddi_devid_t devid2"
70 .Fc
71 .Ft size_t
72 .Fo devid_sizeof
73 .Fa "ddi_devid_t devid"
74 .Fc
75 .Ft int
76 .Fo devid_valid
77 .Fa "ddi_devid_t devid"
78 .Fc
79 .Ft char *
80 .Fo devid_str_encode
81 .Fa "ddi_devid_t devid"
82 .Fa "char *minor_name"
83 .Fc
84 .Ft int
85 .Fo devid_str_decode
86 .Fa "char *devidstr"
87 .Fa "ddi_devid_t *retdevid"
88 .Fa "char **retminor_name"
89 .Fc
90 .Ft char *
91 .Fo devid_str_from_path
92 .Fa "const char *path"
93 .Fc
94 .Ft void
95 .Fo devid_str_free
96 .Fa "char *str"
97 .Fc
98 .Sh DESCRIPTION
99 These functions provide unique identifiers
100 .Pq device ID
101 for devices.
102 Applications and device drivers use these functions to identify and locate
103 devices, independent of the device's physical connection or its logical device
104 name or number.
105 .Pp
106 The
107 .Fn devid_get
108 function returns in
109 .Fa retdevid
110 the device ID for the device associated with the open file descriptor
111 .Fa fd ,
112 which refers to any device.
113 It returns an error if the device does not have an associated device ID.
114 The caller must free the memory allocated for
115 .Fa retdevid
116 using the
117 .Fn devid_free
118 function.
119 .Pp
120 The
121 .Fn devid_free
122 function frees the space that was allocated for the returned
123 .Fa devid
124 by
125 .Fn devid_get
126 and
127 .Fn devid_str_decode .
128 .Pp
129 The
130 .Fn devid_get_minor_name
131 function returns the minor name, in
132 .Fa retminor_name ,
133 for the device associated with the open file descriptor
134 .Fa fd .
135 This name is specific to the particular minor number, but is
136 .Qq instance number
137 specific.
138 The caller of this function must free the memory allocated for the returned
139 .Fa retminor_name
140 string using
141 .Fn devid_str_free .
142 .Pp
143 The
144 .Fn devid_deviceid_to_nmlist
145 function returns an array of
146 .Fa devid_nmlist
147 structures, where each entry matches the
148 .Fa devid
149 and
150 .Fa minor_name
151 passed in.
152 If the
153 .Fa minor_name
154 specified is one of the special values
155 .Po
156 .Dv DEVID_MINOR_NAME_ALL ,
157 .Dv DEVID_MINOR_NAME_ALL_CHR ,
158 or
159 .Dv DEVID_MINOR_NAME_ALL_BLK
160 .Pc ,
161 then all minor names associated with
162 .Fa devid
163 which also meet the special
164 .Fa minor_name
165 filtering requirements are returned.
166 The
167 .Fa devid_nmlist
168 structure contains the device name and device number.
169 The last entry of the array contains a null pointer for the
170 .Fa devname
171 and
172 .Dv NODEV
173 for the device number.
174 This function traverses the file tree, starting at
175 .Fa search_path .
176 For each device with a matching device ID and minor name tuple, a device name
177 and device number are added to the
178 .Fa retlist .
179 If no matches are found, an error is returned.
180 The caller of this function must free the memory allocated for the returned
181 array with the
182 .Fn devid_free_nmlist
183 function.
184 This function may take a long time to complete if called with the device ID of
185 an unattached device.
186 .Pp
187 The
188 .Fn devid_free_nmlist
189 function frees the memory allocated by the
190 .Fn devid_deviceid_to_nmlist
191 function and returned in the
192 .Fa retlist .
193 .Pp
194 The
195 .Fn devid_compare
196 function compares two device IDs and determines both equality and sort order.
197 The function returns an integer greater than 0 if the device ID pointed to by
198 .Fa devid1
199 is greater than the device ID pointed to by
200 .Fa devid2 .
201 It returns 0 if the device ID pointed to by
202 .Fa devid1
203 is equal to the device ID pointed to by
204 .Fa devid2 .
205 It returns an integer less than 0 if the device ID pointed to by
206 .Fa devid1
207 is less than the device ID pointed to by
208 .Fa devid2 .
209 This function is the only valid mechanism to determine the equality of two
210 devids.
211 This function may indicate equality for arguments which by simple inspection
212 appear different.
213 .Pp
214 The
215 .Fn devid_sizeof
216 function returns the size of
217 .Fa devid
218 in bytes.
219 .Pp
220 The
221 .Fn devid_valid
222 function validates the format of a
223 .Fa devid .
224 It returns 1 if the format is valid, and 0 if invalid.
225 This check may not be as complete as the corresponding kernel function
226 .Fn ddi_devid_valid
227 .Po see
228 .Xr ddi_devid_compare 9F
229 .Pc .
230 .Pp
231 The
232 .Fn devid_str_encode
233 function encodes a
234 .Fa devid
235 and
236 .Fa minor_name
237 into a null-terminated ASCII string, returning a pointer to that string.
238 To avoid shell conflicts, the
239 .Fa devid
240 portion of the string is limited to uppercase and lowercase letters, digits, and
241 the plus
242 .Pq Qq Sy \&+ ,
243 minus
244 .Pq Qq Sy \&- ,
245 period
246 .Pq Qq Sy \&. ,
247 equals
248 .Pq Qq Sy \&= ,
249 underscore
250 .Pq Qq Sy \&_ ,
251 tilde
252 .Pq Qq Sy \&~ ,
253 and comma
254 .Pq Qq Sy \&,
255 characters.
256 If there is an ASCII quote character in the binary form of a
257 .Fa devid ,
258 the string representation will be in hex_id form, not ascii_id form.
259 The comma
260 .Pq Qq Sy \&,
261 character is added for
262 .Qq id1,
263 at the head of the string
264 .Fa devid .
265 If both a
266 .Fa devid
267 and a
268 .Fa minor_name
269 are non-null, a slash
270 .Pq Qq Sy \&/
271 is used to separate the
272 .Fa devid
273 from the
274 .Fa minor_name
275 in the encoded string.
276 If
277 .Fa minor_name
278 is null, only the
279 .Fa devid
280 is encoded.
281 If the
282 .Fa devid
283 is null then the special string
284 .Qq id0
285 is returned.
286 Note that you cannot compare the returned string against another string with
287 .Xr strcmp 3C
288 to determine devid equality.
289 The string returned must be freed by calling
290 .Fn devid_str_free .
291 .Pp
292 The
293 .Fn devid_str_from_path
294 is similar to
295 .Fn devid_str_encode ,
296 but takes a
297 .Fa path
298 argument instead.
299 If
300 .Fa path
301 includes the minor name, it will be encoded as well.
302 The string returned must be freed by calling
303 .Fn devid_str_free .
304 .Pp
305 The
306 .Fn devid_str_decode
307 function takes a string previously produced by the
308 .Fn devid_str_encode
309 or
310 .Fn ddi_devid_str_encode
311 .Po see
312 .Xr ddi_devid_compare 9F
313 .Pc
314 function and decodes the contained device ID and minor name, allocating and
315 returning pointers to the extracted parts via the
316 .Fa retdevid
317 and
318 .Fa retminor_name
319 arguments.
320 If the special
321 .Fa devidstr
322 .Qq id0
323 was specified, the returned device ID and minor name will both be null.
324 A non-null returned devid must be freed by the caller by the
325 .Fn devid_free
326 function.
327 A non-null returned minor name must be freed by calling
328 .Fn devid_str_free .
329 .Pp
330 The
331 .Fn devid_str_free
332 function frees the character string returned by
333 .Fn devid_str_encode
334 and the
335 .Fa retminor_name
336 argument returned by
337 .Fn devid_str_decode
338 and
339 .Fn devid_get_minor_name .
340 .Sh RETURN VALUES
341 Upon successful completion, the
342 .Fn devid_get ,
343 .Fn devid_get_minor_name ,
344 .Fn devid_str_decode ,
345 and
346 .Fn devid_deviceid_to_nmlist
347 functions return 0.
348 Otherwise, they return -1.
349 .Pp
350 The
351 .Fn devid_compare
352 function returns the following values:
353 .Bl -tag -width Ds
354 .It Sy -1
355 The device ID pointed to by
356 .Fa devid1
357 is less than the device ID pointed to by
358 .Fa devid2 .
359 .It Sy 0
360 The device ID pointed to by
361 .Fa devid1
362 is equal to the device ID pointed to by
363 .Fa devid2 .
364 .It Sy 1
365 The device ID pointed to by
366 .Fa devid1
367 is greater than the device ID pointed to by
368 .Fa devid2 .
369 .El
370 .Pp
371 The
372 .Fn devid_sizeof
373 function returns the size of
374 .Fa devid
375 in bytes.
376 If
377 .Fa devid
378 is null, the number of bytes that must be allocated and initialized to determine
379 the size of a complete device ID is returned.
380 .Pp
381 The
382 .Fn devid_valid
383 function returns 1 if the
384 .Fa devid
385 is valid and 0 if the
386 .Fa devid
387 is invalid.
388 .Pp
389 The
390 .Fn devid_str_encode
391 and
392 .Fn devid_str_from_path
393 functions return NULL to indicate failure.
394 Failure may be caused by attempting to encode an invalid string.
395 If the return value is non-null, the caller must free the returned string by
396 using the
397 .Fn devid_str_free
398 function.
399 .Sh EXAMPLES
400 .Bl -tag -width Ds
401 .It Xo
402 .Sy Example 1
403 Using
404 .Fn devid_get ,
405 .Fn devid_get_minor_name ,
406 and
407 .Fn devid_str_encode
408 .Xc
409 The following example shows the proper use of
410 .Fn devid_get ,
411 .Fn devid_get_minor_name ,
412 and
413 .Fn devid_str_encode
414 to free the space allocated for
415 .Fa devid ,
416 .Fa minor_name
417 and encoded
418 .Fa devid .
419 .Bd -literal
420 int fd;
421 ddi_devid_t devid;
422 char *minor_name, *devidstr;
424 if ((fd = open("/dev/dsk/c0t3d0s0", O_RDONLY|O_NDELAY)) < 0) {
425 ...
426 }
427 if (devid_get(fd, &devid) != 0) {
428 ...
429 }
430 if (devid_get_minor_name(fd, &minor_name) != 0) {
431 ...
432 }
433 if ((devidstr = devid_str_encode(devid, minor_name)) == 0) {
434 ...
435 }
436 printf("devid %s\en", devidstr);
437 devid_str_free(devidstr);
438 devid_free(devid);
439 devid_str_free(minor_name);
440 .Ed
441 .It Xo
442 .Sy Example 2
443 Using
444 .Fn devid_deviceid_to_nmlist
445 and
446 .Fn devid_free_nmlist
447 .Xc
448 The following example shows the proper use of
449 .Fn devid_deviceid_to_nmlist
450 and
451 .Fn devid_free_nmlist :
452 .Bd -literal
453 devid_nmlist_t *list = NULL;
454 int err;
456 if (devid_deviceid_to_nmlist("/dev/rdsk", devid,
457 minor_name, &list))
458 return (-1);
459 /* loop through list and process device names and numbers */
460 devid_free_nmlist(list);
461 .Ed
462 .El
463 .Sh MT-LEVEL
464 .Sy MT-Safe
465 .Sh INTERFACE STABILITY
466 .Sy Stable
467 .Sh SEE ALSO
468 .Xr free 3C ,
469 .Xr libdevid 3LIB ,
470 .Xr attributes 5 ,
471 .Xr ddi_devid_compare 9F