1devid_get(3DEVID)         Device ID Library Functions        devid_get(3DEVID)
2
3
4

NAME

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

SYNOPSIS

12       cc [ flag... ] file... -ldevid [ library... ]
13       #include <devid.h>
14
15       int devid_get(int fd, ddi_devid_t *retdevid);
16
17
18       void devid_free(ddi_devid_t devid);
19
20
21       int devid_get_minor_name(int fd, char **retminor_name);
22
23
24       int devid_deviceid_to_nmlist(char *search_path, ddi_devid_t devid,
25            char *minor_name, devid_nmlist_t **retlist);
26
27
28       void devid_free_nmlist(devid_nmlist_t *list);
29
30
31       int devid_compare(ddi_devid_t devid1, ddi_devid_t devid2);
32
33
34       size_t devid_sizeof(ddi_devid_t devid);
35
36
37       int devid_valid(ddi_devid_t devid);
38
39
40       char *devid_str_encode(ddi_devid_t devid, char *minor_name);
41
42
43       int devid_str_decode(char *devidstr, ddi_devid_t *retdevid,
44            char **retminor_name);
45
46
47       void devid_str_free(char *str);
48
49

DESCRIPTION

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
56
57       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
63
64       The  devid_free()  function  frees the space that was allocated for the
65       returned devid by devid_get() and devid_str_decode().
66
67
68       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
74
75       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
92
93       The  devid_free_nmlist()  function  frees  the  memory allocated by the
94       devid_deviceid_to_nmlist() function.
95
96
97       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
108
109       The devid_sizeof() function returns the size of devid in bytes.
110
111
112       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
117
118       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
134
135       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
145
146       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

RETURN VALUES

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
155
156       The devid_compare() function returns the following values:
157
158       −1       The device ID pointed to by devid1 is less than the device  ID
159                pointed to by devid2.
160
161
162       0        The  device ID pointed to by devid1 is equal to  the device ID
163                pointed to by devid2.
164
165
166       1        The device ID pointed to by devid1 is greater than the  device
167                ID pointed to by devid2.
168
169
170
171       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
175
176       The devid_valid() function returns 1 if the devid is valid and 0 if the
177       devid is invalid.
178
179
180       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

EXAMPLES

186       Example    1    Using    devid_get(),    devid_get_minor_name(),    and
187       devid_str_encode()
188
189
190       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
194
195         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
215
216       Example 2 Using devid_deviceid_to_nmlist() and devid_free_nmlist()
217
218
219       The  following  example  shows   the   proper   use   of    devid_devi‐
220       ceid_to_nmlist() and devid_free_nmlist():
221
222
223         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
231

ATTRIBUTES

233       See attributes(5) for description of the following attributes:
234
235
236
237
238       ┌─────────────────────────────┬─────────────────────────────┐
239       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
240       ├─────────────────────────────┼─────────────────────────────┤
241       │MT-Level                     │MT−Safe                      │
242       ├─────────────────────────────┼─────────────────────────────┤
243       │Interface Stability          │Stable                       │
244       └─────────────────────────────┴─────────────────────────────┘
245

SEE ALSO

247       free(3C), libdevid(3LIB), attributes(5), ddi_devid_compare(9F)
248
249
250
251SunOS 5.11                        30 Nov 2001                devid_get(3DEVID)
Impressum