1devid_get(3DEVID) Device ID Library Functions devid_get(3DEVID)
2
6 devid_get, devid_compare, devid_deviceid_to_nmlist, devid_free,
7 devid_free_nmlist, devid_get_minor_name, devid_sizeof,
8 devid_str_decode, devid_str_free, devid_str_encode, devid_valid -
9 device ID interfaces for user applications
10
12 cc [ flag... ] file... -ldevid [ library... ]
13 #include <devid.h>
14 int devid_get(int fd, ddi_devid_t *retdevid);
16 void devid_free(ddi_devid_t devid);
19 int devid_get_minor_name(int fd, char **retminor_name);
22 int devid_deviceid_to_nmlist(char *search_path, ddi_devid_t devid,
25 char *minor_name, devid_nmlist_t **retlist);
26 void devid_free_nmlist(devid_nmlist_t *list);
29 int devid_compare(ddi_devid_t devid1, ddi_devid_t devid2);
32 size_t devid_sizeof(ddi_devid_t devid);
35 int devid_valid(ddi_devid_t devid);
38 char *devid_str_encode(ddi_devid_t devid, char *minor_name);
41 int devid_str_decode(char *devidstr, ddi_devid_t *retdevid,
44 char **retminor_name);
45 void devid_str_free(char *str);
48
51 These functions provide unique identifiers (device IDs) for devices.
52 Applications and device drivers use these functions to identify and
53 locate devices, independent of the device's physical connection or its
54 logical device name or number.
55 The devid_get() function returns in retdevid the device ID for the
58 device associated with the open file descriptor fd, which refers to any
59 device. It returns an error if the device does not have an associated
60 device ID. The caller must free the memory allocated for retdevid using
61 the devid_free() function.
62 The devid_free() function frees the space that was allocated for the
65 returned devid by devid_get() and devid_str_decode().
66 The devid_get_minor_name() function returns the minor name, in retmi‐
69 nor_name, for the device associated with the open file descriptor fd.
70 This name is specific to the particular minor number, but is "instance
71 number" specific. The caller of this function must free the memory
72 allocated for the returned retminor_name string using devid_str_free().
73 The devid_deviceid_to_nmlist() function returns an array of
76 devid_nmlist structures, where each entry matches the devid and
77 minor_name passed in. If the minor_name specified is one of the special
78 values (DEVID_MINOR_NAME_ALL, DEVID_MINOR_NAME_ALL_CHR, or
79 DEVID_MINOR_NAME_ALL_BLK) , then all minor names associated with devid
80 which also meet the special minor_name filtering requirements are
81 returned. The devid_nmlist structure contains the device name and
82 device number. The last entry of the array contains a null pointer for
83 the devname and NODEV for the device number. This function traverses
84 the file tree, starting at search_path. For each device with a matching
85 device ID and minor name tuple, a device name and device number are
86 added to the retlist. If no matches are found, an error is returned.
87 The caller of this function must free the memory allocated for the
88 returned array with the devid_free_nmlist() function. This function may
89 take a long time to complete if called with the device ID of an unat‐
90 tached device.
91 The devid_free_nmlist() function frees the memory allocated by the
94 devid_deviceid_to_nmlist() function.
95 The devid_compare() function compares two device IDs and determines
98 both equality and sort order. The function returns an integer greater
99 than 0 if the device ID pointed to by devid1 is greater than the device
100 ID pointed to by devid2. It returns 0 if the device ID pointed to by
101 devid1 is equal to the device ID pointed to by devid2. It returns an
102 integer less than 0 if the device ID pointed to by devid1 is less than
103 the device ID pointed to by devid2. This function is the only valid
104 mechanism to determine the equality of two devids. This function may
105 indicate equality for arguments which by simple inspection appear dif‐
106 ferent.
107 The devid_sizeof() function returns the size of devid in bytes.
110 The devid_valid() function validates the format of a devid. It returns
113 1 if the format is valid, and 0 if invalid. This check may not be as
114 complete as the corresponding kernel function ddi_devid_valid() (see
115 ddi_devid_compare(9F)).
116 The devid_str_encode() function encodes a devid and minor_name into a
119 null-terminated ASCII string, returning a pointer to that string. To
120 avoid shell conflicts, the devid portion of the string is limited to
121 uppercase and lowercase letters, digits, and the plus (+), minus (-),
122 period (.), equals (=), underscore (_), tilde (~), and comma (,) char‐
123 acters. If there is an ASCII quote character in the binary form of a
124 devid, the string representation will be in hex_id form, not ascii_id
125 form. The comma (,) character is added for "id1," at the head of the
126 string devid. If both a devid and a minor_name are non-null, a slash
127 (/)is used to separate the devid from the minor_name in the encoded
128 string. If minor_name is null, only the devid is encoded. If the devid
129 is null then the special string "id0" is returned. Note that you cannot
130 compare the returned string against another string with strcmp(3C) to
131 determine devid equality. The string returned must be freed by calling
132 devid_str_free().
133 The devid_str_decode() function takes a string previously produced by
136 the devid_str_encode() or ddi_devid_str_encode() (see ddi_devid_com‐
137 pare(9F)) function and decodes the contained device ID and minor name,
138 allocating and returning pointers to the extracted parts via the retde‐
139 vid and retminor_name arguments. If the special devidstr "id0" was
140 specified, the returned device ID and minor name will both be null. A
141 non-null returned devid must be freed by the caller by the devid_free()
142 function. A non-null returned minor name must be freed by calling
143 devid_str_free().
144 The devid_str_free() function frees the character string returned by
147 devid_str_encode() and the retminor_name argument returned by
148 devid_str_decode().
149
151 Upon successful completion, the devid_get(), devid_get_minor_name(),
152 devid_str_decode(), and devid_deviceid_to_nmlist() functions return 0.
153 Otherwise, they return −1.
154 The devid_compare() function returns the following values:
157 −1 The device ID pointed to by devid1 is less than the device ID
159 pointed to by devid2.
160 0 The device ID pointed to by devid1 is equal to the device ID
163 pointed to by devid2.
164 1 The device ID pointed to by devid1 is greater than the device
167 ID pointed to by devid2.
168 The devid_sizeof() function returns the size of devid in bytes. If
172 devid is null, the number of bytes that must be allocated and initial‐
173 ized to determine the size of a complete device ID is returned.
174 The devid_valid() function returns 1 if the devid is valid and 0 if the
177 devid is invalid.
178 The devid_str_encode() function returns NULL to indicate failure. Fail‐
181 ure may be caused by attempting to encode an invalid string. If the
182 return value is non-null, the caller must free the returned string by
183 using the devid_str_free() function.
184
186 Example 1 Using devid_get(), devid_get_minor_name(), and
187 devid_str_encode()
188 The following example shows the proper use of devid_get(),
191 devid_get_minor_name(), and devid_str_encode() to free the space allo‐
192 cated for devid, minor_name and encoded devid.
193 int fd;
196 ddi_devid_t devid;
197 char *minor_name, *devidstr;
198 if ((fd = open("/dev/dsk/c0t3d0s0", O_RDONLY|O_NDELAY)) < 0) {
199 ...
200 }
201 if (devid_get(fd, &devid) != 0) {
202 ...
203 }
204 if (devid_get_minor_name(fd, &minor_name) != 0) {
205 ...
206 }
207 if ((devidstr = devid_str_encode(devid, minor_name)) == 0) {
208 ...
209 }
210 printf("devid %s\n", devidstr);
211 devid_str_free(devidstr);
212 devid_free(devid);
213 devid_str_free(minor_name);
214 Example 2 Using devid_deviceid_to_nmlist() and devid_free_nmlist()
217 The following example shows the proper use of devid_devi‐
220 ceid_to_nmlist() and devid_free_nmlist():
221 devid_nmlist_t *list = NULL;
224 int err;
225 if (devid_deviceid_to_nmlist("/dev/rdsk", devid,
226 minor_name, &list))
227 return (-1);
228 /* loop through list and process device names and numbers */
229 devid_free_nmlist(list);
230
233 See attributes(5) for description of the following attributes:
234 ┌─────────────────────────────┬─────────────────────────────┐
239 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
240 ├─────────────────────────────┼─────────────────────────────┤
241 │MT-Level │MT−Safe │
242 ├─────────────────────────────┼─────────────────────────────┤
243 │Interface Stability │Stable │
244 └─────────────────────────────┴─────────────────────────────┘
245
247 free(3C), libdevid(3LIB), attributes(5), ddi_devid_compare(9F)
248SunOS 5.11 30 Nov 2001 devid_get(3DEVID)