xref: /illumos-gate/usr/src/man/man3devid/devid_get.3devid (revision 66582b606a8194f7f3ba5b3a3a6dca5b0d346361)
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
99These functions provide unique identifiers
100.Pq device ID
101for devices.
102Applications and device drivers use these functions to identify and locate
103devices, independent of the device's physical connection or its logical device
104name or number.
105.Pp
106The
107.Fn devid_get
108function returns in
109.Fa retdevid
110the device ID for the device associated with the open file descriptor
111.Fa fd ,
112which refers to any device.
113It returns an error if the device does not have an associated device ID.
114The caller must free the memory allocated for
115.Fa retdevid
116using the
117.Fn devid_free
118function.
119.Pp
120The
121.Fn devid_free
122function frees the space that was allocated for the returned
123.Fa devid
124by
125.Fn devid_get
126and
127.Fn devid_str_decode .
128.Pp
129The
130.Fn devid_get_minor_name
131function returns the minor name, in
132.Fa retminor_name ,
133for the device associated with the open file descriptor
134.Fa fd .
135This name is specific to the particular minor number, but is
136.Qq instance number
137specific.
138The caller of this function must free the memory allocated for the returned
139.Fa retminor_name
140string using
141.Fn devid_str_free .
142.Pp
143The
144.Fn devid_deviceid_to_nmlist
145function returns an array of
146.Fa devid_nmlist
147structures, where each entry matches the
148.Fa devid
149and
150.Fa minor_name
151passed in.
152If the
153.Fa minor_name
154specified is one of the special values
155.Po
156.Dv DEVID_MINOR_NAME_ALL ,
157.Dv DEVID_MINOR_NAME_ALL_CHR ,
158or
159.Dv DEVID_MINOR_NAME_ALL_BLK
160.Pc ,
161then all minor names associated with
162.Fa devid
163which also meet the special
164.Fa minor_name
165filtering requirements are returned.
166The
167.Fa devid_nmlist
168structure contains the device name and device number.
169The last entry of the array contains a null pointer for the
170.Fa devname
171and
172.Dv NODEV
173for the device number.
174This function traverses the file tree, starting at
175.Fa search_path .
176For each device with a matching device ID and minor name tuple, a device name
177and device number are added to the
178.Fa retlist .
179If no matches are found, an error is returned.
180The caller of this function must free the memory allocated for the returned
181array with the
182.Fn devid_free_nmlist
183function.
184This function may take a long time to complete if called with the device ID of
185an unattached device.
186.Pp
187The
188.Fn devid_free_nmlist
189function frees the memory allocated by the
190.Fn devid_deviceid_to_nmlist
191function and returned in the
192.Fa retlist .
193.Pp
194The
195.Fn devid_compare
196function compares two device IDs and determines both equality and sort order.
197The function returns an integer greater than 0 if the device ID pointed to by
198.Fa devid1
199is greater than the device ID pointed to by
200.Fa devid2 .
201It returns 0 if the device ID pointed to by
202.Fa devid1
203is equal to the device ID pointed to by
204.Fa devid2 .
205It returns an integer less than 0 if the device ID pointed to by
206.Fa devid1
207is less than the device ID pointed to by
208.Fa devid2 .
209This function is the only valid mechanism to determine the equality of two
210devids.
211This function may indicate equality for arguments which by simple inspection
212appear different.
213.Pp
214The
215.Fn devid_sizeof
216function returns the size of
217.Fa devid
218in bytes.
219.Pp
220The
221.Fn devid_valid
222function validates the format of a
223.Fa devid .
224It returns 1 if the format is valid, and 0 if invalid.
225This 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
231The
232.Fn devid_str_encode
233function encodes a
234.Fa devid
235and
236.Fa minor_name
237into a null-terminated ASCII string, returning a pointer to that string.
238To avoid shell conflicts, the
239.Fa devid
240portion of the string is limited to uppercase and lowercase letters, digits, and
241the plus
242.Pq Qq Sy \&+ ,
243minus
244.Pq Qq Sy \&- ,
245period
246.Pq Qq Sy \&. ,
247equals
248.Pq Qq Sy \&= ,
249underscore
250.Pq Qq Sy \&_ ,
251tilde
252.Pq Qq Sy \&~ ,
253and comma
254.Pq Qq Sy \&,
255characters.
256If there is an ASCII quote character in the binary form of a
257.Fa devid ,
258the string representation will be in hex_id form, not ascii_id form.
259The comma
260.Pq Qq Sy \&,
261character is added for
262.Qq id1,
263at the head of the string
264.Fa devid .
265If both a
266.Fa devid
267and a
268.Fa minor_name
269are non-null, a slash
270.Pq Qq Sy \&/
271is used to separate the
272.Fa devid
273from the
274.Fa minor_name
275in the encoded string.
276If
277.Fa minor_name
278is null, only the
279.Fa devid
280is encoded.
281If the
282.Fa devid
283is null then the special string
284.Qq id0
285is returned.
286Note that you cannot compare the returned string against another string with
287.Xr strcmp 3C
288to determine devid equality.
289The string returned must be freed by calling
290.Fn devid_str_free .
291.Pp
292The
293.Fn devid_str_from_path
294is similar to
295.Fn devid_str_encode ,
296but takes a
297.Fa path
298argument instead.
299If
300.Fa path
301includes the minor name, it will be encoded as well.
302The string returned must be freed by calling
303.Fn devid_str_free .
304.Pp
305The
306.Fn devid_str_decode
307function takes a string previously produced by the
308.Fn devid_str_encode
309or
310.Fn ddi_devid_str_encode
311.Po see
312.Xr ddi_devid_compare 9F
313.Pc
314function and decodes the contained device ID and minor name, allocating and
315returning pointers to the extracted parts via the
316.Fa retdevid
317and
318.Fa retminor_name
319arguments.
320If the special
321.Fa devidstr
322.Qq id0
323was specified, the returned device ID and minor name will both be null.
324A non-null returned devid must be freed by the caller by the
325.Fn devid_free
326function.
327A non-null returned minor name must be freed by calling
328.Fn devid_str_free .
329.Pp
330The
331.Fn devid_str_free
332function frees the character string returned by
333.Fn devid_str_encode
334and the
335.Fa retminor_name
336argument returned by
337.Fn devid_str_decode
338and
339.Fn devid_get_minor_name .
340.Sh RETURN VALUES
341Upon successful completion, the
342.Fn devid_get ,
343.Fn devid_get_minor_name ,
344.Fn devid_str_decode ,
345and
346.Fn devid_deviceid_to_nmlist
347functions return 0.
348Otherwise, they return -1.
349.Pp
350The
351.Fn devid_compare
352function returns the following values:
353.Bl -tag -width Ds
354.It Sy -1
355The device ID pointed to by
356.Fa devid1
357is less than the device ID pointed to by
358.Fa devid2 .
359.It Sy 0
360The device ID pointed to by
361.Fa devid1
362is equal to the device ID pointed to by
363.Fa devid2 .
364.It Sy 1
365The device ID pointed to by
366.Fa devid1
367is greater than the device ID pointed to by
368.Fa devid2 .
369.El
370.Pp
371The
372.Fn devid_sizeof
373function returns the size of
374.Fa devid
375in bytes.
376If
377.Fa devid
378is null, the number of bytes that must be allocated and initialized to determine
379the size of a complete device ID is returned.
380.Pp
381The
382.Fn devid_valid
383function returns 1 if the
384.Fa devid
385is valid and 0 if the
386.Fa devid
387is invalid.
388.Pp
389The
390.Fn devid_str_encode
391and
392.Fn devid_str_from_path
393functions return NULL to indicate failure.
394Failure may be caused by attempting to encode an invalid string.
395If the return value is non-null, the caller must free the returned string by
396using the
397.Fn devid_str_free
398function.
399.Sh EXAMPLES
400.Bl -tag -width Ds
401.It Xo
402.Sy Example 1
403Using
404.Fn devid_get ,
405.Fn devid_get_minor_name ,
406and
407.Fn devid_str_encode
408.Xc
409The following example shows the proper use of
410.Fn devid_get ,
411.Fn devid_get_minor_name ,
412and
413.Fn devid_str_encode
414to free the space allocated for
415.Fa devid ,
416.Fa minor_name
417and encoded
418.Fa devid .
419.Bd -literal
420int fd;
421ddi_devid_t devid;
422char *minor_name, *devidstr;
423
424if ((fd = open("/dev/dsk/c0t3d0s0", O_RDONLY|O_NDELAY)) < 0) {
425    ...
426}
427if (devid_get(fd, &devid) != 0) {
428    ...
429}
430if (devid_get_minor_name(fd, &minor_name) != 0) {
431    ...
432}
433if ((devidstr = devid_str_encode(devid, minor_name)) == 0) {
434    ...
435}
436printf("devid %s\en", devidstr);
437devid_str_free(devidstr);
438devid_free(devid);
439devid_str_free(minor_name);
440.Ed
441.It Xo
442.Sy Example 2
443Using
444.Fn devid_deviceid_to_nmlist
445and
446.Fn devid_free_nmlist
447.Xc
448The following example shows the proper use of
449.Fn devid_deviceid_to_nmlist
450and
451.Fn devid_free_nmlist :
452.Bd -literal
453devid_nmlist_t *list = NULL;
454int err;
455
456if (devid_deviceid_to_nmlist("/dev/rdsk", devid,
457    minor_name, &list))
458	return (-1);
459/* loop through list and process device names and numbers */
460devid_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
472